from __future__ import annotations
import json
from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
from pydantic import BaseModel, Field
from actrone_memory.logging import bind_logger
from actrone_memory.models import Sensitivity
if TYPE_CHECKING:
from openai import AsyncOpenAI
log = bind_logger(__name__)
# ── Shared extraction spec (language-neutral; keep in lockstep with the TS lib) ──
# The canonical reference lives at docs/memory-spec/extraction.v1.md. The prompt, the
# input framing and the output JSON shape are the contract both OSS libs and the hosted
# engine conform to, so "improve once" = update the spec + eval and both follow.
#
# 1.1: small models (a 3B model on Ollama, measured) returned "{}" for nearly every real
# exchange under 1.0, because they read the assistant's reply as part of what to mine.
# 1.1 frames the conversation, says whose facts to record, sends a JSON schema, and
# gives two worked examples: one with facts and one where the right answer is none.
EXTRACTION_SPEC_VERSION = "1.1"
# Each fact the model returns:
# { "content": str, "sensitivity": "none"|"low"|"pii"|"sensitive",
# "topic_tags": [str], "importance": float(0..1) }
EXTRACTION_SYSTEM_PROMPT = (
"You extract durable, atomic facts from a conversation so an AI agent can "
"remember them across sessions. Return ONLY facts worth remembering long term: "
"stable user attributes, preferences, decisions, commitments, and key entities. "
"Ignore small talk, transient state, and anything already obvious.\n"
"For each fact, classify its sensitivity: 'none' (non-personal), 'low' (mild "
"preference), 'pii' (personally identifiable, names, emails, phone, address, "
"account numbers), or 'sensitive' (health, financial, credentials, special "
"category). Assign an importance from 0.0 to 1.0.\n"
'Respond with strict JSON of the form {"facts": [{"content": "...", '
'"sensitivity": "none", "topic_tags": ["..."], "importance": 0.7}]}. '
"Write each fact as a self-contained sentence. Return an empty list if there is "
"nothing durable to remember.\n"
"The conversation is between a user and an AI assistant. Extract facts about the user "
"and their world from what the user says; use the assistant's replies only as context, "
"never as a source of facts.\n"
"Write one fact per piece of information: a name and a job are two facts. Classify each "
"fact by the most sensitive detail it contains: a person's name, email address, phone "
"number or postal address is 'pii'; health, emotions or mental state, money and "
"credentials are 'sensitive'; a preference is 'low'; everything else is 'none'.\n"
"Only record facts the user states about themselves, their work or their world. Never "
"record facts about the conversation itself (such as what the user asked), about the "
"assistant, or general knowledge from the assistant's answers. If the user only makes "
"small talk, thanks the assistant, "
'or asks a general question, return {"facts": []}.\n'
"Example, not part of the conversation you are given:\n"
"User: I'm Sam, a nurse, and I've been struggling with insomnia. Email me at "
"sam@example.org. I like short replies.\n"
"Assistant: Thanks Sam, noted.\n"
'Output: {"facts": ['
'{"content": "The user\'s name is Sam.", "sensitivity": "pii", '
'"topic_tags": ["identity"], "importance": 0.8}, '
'{"content": "The user works as a nurse.", "sensitivity": "none", '
'"topic_tags": ["role"], "importance": 0.6}, '
'{"content": "The user has been struggling with insomnia.", "sensitivity": "sensitive", '
'"topic_tags": ["health"], "importance": 0.7}, '
'{"content": "The user\'s email address is sam@example.org.", "sensitivity": "pii", '
'"topic_tags": ["contact"], "importance": 0.8}, '
'{"content": "The user prefers short replies.", "sensitivity": "low", '
'"topic_tags": ["preference"], "importance": 0.5}]}\n'
"Second example, also not part of the conversation:\n"
"User: Thanks, that helps!\n"
"Assistant: Glad to help. The Moon is about 384,000 km away, by the way.\n"
'Output: {"facts": []}'
)
#: JSON schema for the extraction output, sent as a structured-output ``response_format``
#: so constrained decoding keeps even a small model on the contract. Strict-mode shaped
#: (every property required, no extra properties) so OpenAI accepts it with ``strict``.
EXTRACTION_RESPONSE_SCHEMA: dict[str, Any] = {
"type": "object",
"properties": {
"facts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {"type": "string"},
"sensitivity": {"type": "string", "enum": ["none", "low", "pii", "sensitive"]},
"topic_tags": {"type": "array", "items": {"type": "string"}},
"importance": {"type": "number"},
},
"required": ["content", "sensitivity", "topic_tags", "importance"],
"additionalProperties": False,
},
}
},
"required": ["facts"],
"additionalProperties": False,
}
# Hard caps so a misbehaving model can't blow up the store or the token budget.
_MAX_FACTS = 20
_MAX_FACT_CHARS = 2_000
[docs]
def parse_facts(raw: str) -> list[ExtractedFact]:
"""Parse a model's JSON response into validated facts, defensively.
Tolerates a bare list or a ``{"facts": [...]}`` envelope, skips malformed
entries, clamps oversize content, and bounds the count. Never raises, a
completely unparseable response yields ``[]``.
"""
try:
data = json.loads(raw)
except (json.JSONDecodeError, TypeError):
log.warning("extraction.parse.invalid_json")
return []
items = data.get("facts") if isinstance(data, dict) else data
if not isinstance(items, list):
return []
facts: list[ExtractedFact] = []
for item in items[:_MAX_FACTS]:
if not isinstance(item, dict):
continue
content = item.get("content")
if not isinstance(content, str) or not content.strip():
continue
try:
fact = ExtractedFact(
content=content.strip()[:_MAX_FACT_CHARS],
sensitivity=item.get("sensitivity", "none"),
topic_tags=[str(t) for t in item.get("topic_tags", []) if isinstance(t, str)][:20],
importance=float(item.get("importance", 0.6)),
)
except (ValueError, TypeError):
# Bad sensitivity enum / importance out of range, skip this one fact.
continue
facts.append(fact)
return facts
_SCHEMA_FORMAT: dict[str, Any] = {
"type": "json_schema",
"json_schema": {
"name": "extracted_facts",
"strict": True,
"schema": EXTRACTION_RESPONSE_SCHEMA,
},
}
_JSON_FORMAT: dict[str, Any] = {"type": "json_object"}