flare-kernel 0.2.5__tar.gz → 0.2.6__tar.gz

{flare_kernel-0.2.5 → flare_kernel-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flare-kernel
-Version: 0.2.5
+Version: 0.2.6
 Summary: FLARE kernel runtime package
 License: Proprietary
 Classifier: Development Status :: 3 - Alpha

{flare_kernel-0.2.5 → flare_kernel-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flare-kernel"
-version = "0.2.5"
+version = "0.2.6"
 description = "FLARE kernel runtime package"
 readme = "README.md"
 requires-python = ">=3.11"

{flare_kernel-0.2.5 → flare_kernel-0.2.6}/src/flare_kernel/contracts/__init__.py

@@ -32,6 +32,11 @@ from flare_kernel.contracts.project_contract import (
     ProjectsResponse,
     ProjectUpsertRequest,
 )
+from flare_kernel.contracts.project_memory_contract import (
+    ProjectMemoryCandidate,
+    ProjectMemoryRecall,
+    ProjectMemoryRecord,
+)
 from flare_kernel.contracts.session_contract import (
     SessionAppendExchangeRequest,
     SessionCreateRequest,
@@ -72,6 +77,9 @@ __all__ = [
     "ProjectRecord",
     "ProjectUpsertRequest",
     "ProjectsResponse",
+    "ProjectMemoryCandidate",
+    "ProjectMemoryRecord",
+    "ProjectMemoryRecall",
     "SessionRecord",
     "SessionCreateRequest",
     "SessionUpdateRequest",

flare_kernel-0.2.6/src/flare_kernel/contracts/project_memory_contract.py

@@ -0,0 +1,85 @@
+"""Project Memory contracts for OBJ-03."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ProjectMemoryCandidate(BaseModel):
+    """Runtime Project Memory candidate before durable scope is applied.
+
+    Attributes:
+        memory_type: Category used by recall and presentation.
+        content: Normalized memory text to be considered for persistence.
+        evidence: Optional source snippets that support the candidate.
+        confidence: Optional confidence score from the extraction path.
+        source_session_id: Session that produced the candidate, when available.
+        source_message_id: Message that produced the candidate, when available.
+        source_id: Source document or runtime artifact id, when available.
+    """
+
+    memory_type: str = "fact"
+    content: str
+    evidence: list[dict[str, Any]] = Field(default_factory=list)
+    confidence: float | None = None
+    source_session_id: str = ""
+    source_message_id: str = ""
+    source_id: str = ""
+
+
+class ProjectMemoryRecord(BaseModel):
+    """Durable Project Memory record stored under project and user scope.
+
+    Attributes:
+        memory_id: Stable Project Memory identifier.
+        project_id: Project scope that owns the memory.
+        user_id: User scope that owns the memory.
+        source_session_id: Session that produced the memory, when available.
+        source_message_id: Message that produced the memory, when available.
+        source_id: Source document or runtime artifact id, when available.
+        memory_type: Category used by recall and presentation.
+        content: Durable memory text.
+        evidence: Optional source snippets that support the memory.
+        confidence: Optional confidence score.
+        status: Lifecycle status, such as active or archived.
+        created_at: Creation timestamp in ISO string format.
+        updated_at: Last update timestamp in ISO string format.
+    """
+
+    memory_id: str
+    project_id: str
+    user_id: str
+    source_session_id: str = ""
+    source_message_id: str = ""
+    source_id: str = ""
+    memory_type: str = "fact"
+    content: str
+    evidence: list[dict[str, Any]] = Field(default_factory=list)
+    confidence: float | None = None
+    status: str = "active"
+    created_at: str
+    updated_at: str
+
+
+class ProjectMemoryRecall(BaseModel):
+    """Project Memory recall payload consumed by context assembly.
+
+    Attributes:
+        project_id: Project scope used for recall.
+        user_id: User scope used for recall.
+        query: Normalized recall query.
+        hit_count: Number of memory records included in the payload.
+        memory_ids: Ordered identifiers for the recalled memories.
+        memories: Presentation-safe memory snippets.
+        degraded: True when recall failed and returned an empty fallback.
+    """
+
+    project_id: str
+    user_id: str
+    query: str
+    hit_count: int = 0
+    memory_ids: list[str] = Field(default_factory=list)
+    memories: list[dict[str, Any]] = Field(default_factory=list)
+    degraded: bool = False

flare_kernel-0.2.6/src/flare_kernel/runtime/infrastructure/project_memory_codec.py

@@ -0,0 +1,231 @@
+"""Project Memory storage codecs and validation helpers."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from flare_kernel.contracts.project_memory_contract import ProjectMemoryRecord
+
+
+def utcnow_iso() -> str:
+    """Return the current UTC timestamp for durable rows.
+
+    Returns:
+        ISO formatted UTC datetime string.
+    """
+
+    return datetime.now(UTC).isoformat()
+
+
+def normalize_project_memory_text(value: Any) -> str:
+    """Normalize arbitrary input into compact text.
+
+    Args:
+        value: Raw value from caller or database row.
+
+    Returns:
+        Whitespace-normalized string.
+    """
+
+    return " ".join(str(value or "").split()).strip()
+
+
+def normalize_project_memory_status(value: Any) -> str:
+    """Normalize memory lifecycle status.
+
+    Args:
+        value: Raw status value.
+
+    Returns:
+        Non-empty status string, defaulting to active.
+    """
+
+    return normalize_project_memory_text(value) or "active"
+
+
+def normalize_project_memory_confidence(value: Any) -> float | None:
+    """Normalize confidence to a float when possible.
+
+    Args:
+        value: Raw confidence value.
+
+    Returns:
+        Float confidence, or None when unavailable/invalid.
+    """
+
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def json_dumps_evidence(value: Any) -> str:
+    """Serialize evidence-like values for SQL storage.
+
+    Args:
+        value: Evidence value supplied by caller.
+
+    Returns:
+        JSON string persisted in evidence_json.
+    """
+
+    return json.dumps(value if value is not None else [], ensure_ascii=False, sort_keys=True)
+
+
+def json_loads_evidence(value: Any) -> Any:
+    """Deserialize evidence_json from SQL storage.
+
+    Args:
+        value: Raw JSON string from database.
+
+    Returns:
+        Parsed JSON value, or an empty list on missing/invalid input.
+    """
+
+    if not value:
+        return []
+    try:
+        return json.loads(str(value))
+    except json.JSONDecodeError:
+        return []
+
+
+def build_project_memory_id() -> str:
+    """Create a local Project Memory identifier.
+
+    Returns:
+        Stable id string with pmem_ prefix.
+    """
+
+    return f"pmem_{uuid.uuid4().hex[:16]}"
+
+
+def build_project_memory_params(
+    *,
+    memory_id: str | None,
+    project_id: str,
+    user_id: str,
+    source_session_id: str | None,
+    source_message_id: str | None,
+    source_id: str | None,
+    memory_type: str,
+    content: str,
+    evidence: list[dict[str, Any]] | None,
+    confidence: float | None,
+    status: str,
+) -> dict[str, Any]:
+    """Build normalized SQL parameters for an upsert.
+
+    Args:
+        memory_id: Optional existing memory id.
+        project_id: Owning project id.
+        user_id: Owning user id.
+        source_session_id: Producing session id, when available.
+        source_message_id: Producing message id, when available.
+        source_id: Producing source id, when available.
+        memory_type: Memory category.
+        content: Durable memory text.
+        evidence: Optional supporting snippets.
+        confidence: Optional confidence score.
+        status: Lifecycle status.
+
+    Returns:
+        SQL parameter dict for insert/update statements.
+    """
+
+    now = utcnow_iso()
+    return {
+        "memory_id": normalize_project_memory_text(memory_id) or build_project_memory_id(),
+        "project_id": normalize_project_memory_text(project_id),
+        "user_id": normalize_project_memory_text(user_id),
+        "source_session_id": normalize_project_memory_text(source_session_id),
+        "source_message_id": normalize_project_memory_text(source_message_id),
+        "source_id": normalize_project_memory_text(source_id),
+        "memory_type": normalize_project_memory_text(memory_type) or "fact",
+        "content": str(content or "").strip(),
+        "evidence_json": json_dumps_evidence(evidence),
+        "confidence": confidence,
+        "status": normalize_project_memory_status(status),
+        "created_at": now,
+        "updated_at": now,
+    }
+
+
+def row_to_project_memory_record(row: Any) -> dict[str, Any]:
+    """Convert a SQL row into the public Project Memory record contract.
+
+    Args:
+        row: SQLAlchemy row mapping containing evidence_json.
+
+    Returns:
+        ProjectMemoryRecord as a dict.
+    """
+
+    record = dict(row)
+    record["evidence"] = json_loads_evidence(record.pop("evidence_json", ""))
+    record["confidence"] = normalize_project_memory_confidence(record.get("confidence"))
+    return ProjectMemoryRecord.model_validate(record).model_dump()
+
+
+def require_project_memory_scope(project_id: str, user_id: str) -> tuple[str, str]:
+    """Validate and normalize required project/user scope.
+
+    Args:
+        project_id: Project id supplied by caller.
+        user_id: User id supplied by caller.
+
+    Returns:
+        Tuple of normalized project_id and user_id.
+
+    Raises:
+        ValueError: If either scope value is empty.
+    """
+
+    resolved_project_id = normalize_project_memory_text(project_id)
+    resolved_user_id = normalize_project_memory_text(user_id)
+    if not resolved_project_id:
+        raise ValueError("project_id is required")
+    if not resolved_user_id:
+        raise ValueError("user_id is required")
+    return resolved_project_id, resolved_user_id
+
+
+def require_project_memory_content(content: str) -> str:
+    """Validate and normalize required memory content.
+
+    Args:
+        content: Memory text supplied by caller.
+
+    Returns:
+        Non-empty memory content.
+
+    Raises:
+        ValueError: If content is empty.
+    """
+
+    resolved = str(content or "").strip()
+    if not resolved:
+        raise ValueError("content is required")
+    return resolved
+
+
+def score_project_memory_record(record: dict[str, Any], query_terms: list[str]) -> tuple[int, dict[str, Any]]:
+    """Score one memory record using lexical query-term overlap.
+
+    Args:
+        record: ProjectMemoryRecord-compatible dict.
+        query_terms: Lowercase query tokens.
+
+    Returns:
+        Tuple of integer score and original record.
+    """
+
+    content = str(record.get("content") or "").lower()
+    memory_type = str(record.get("memory_type") or "").lower()
+    haystack = f"{memory_type} {content}"
+    return sum(1 for term in query_terms if term in haystack), record

{flare_kernel-0.2.5 → flare_kernel-0.2.6}/src/flare_kernel/runtime/infrastructure/project_memory_store.py

@@ -2,12 +2,19 @@
 
 from __future__ import annotations
 
-import json
-import uuid
-from datetime import UTC, datetime
 from typing import Any, Callable
 
 from flare_kernel.runtime.infrastructure.database import build_sqlalchemy_engine
+from flare_kernel.runtime.infrastructure.project_memory_codec import (
+    build_project_memory_params,
+    normalize_project_memory_confidence,
+    normalize_project_memory_status,
+    normalize_project_memory_text,
+    require_project_memory_content,
+    require_project_memory_scope,
+    row_to_project_memory_record,
+    score_project_memory_record,
+)
 from flare_kernel.runtime.infrastructure.project_memory_sql import (
     PROJECT_MEMORY_INSERT_SQL,
     PROJECT_MEMORY_LIST_WHERE_SQL,
@@ -19,107 +26,35 @@ from flare_kernel.runtime.infrastructure.project_memory_sql import (
 )
 
 
-def _utcnow_iso() -> str:
-    return datetime.now(UTC).isoformat()
-
-
-def _normalize_text(value: Any) -> str:
-    return " ".join(str(value or "").split()).strip()
-
-
-def _normalize_status(value: Any) -> str:
-    return _normalize_text(value) or "active"
-
-
-def _normalize_confidence(value: Any) -> float | None:
-    if value is None:
-        return None
-    try:
-        return float(value)
-    except (TypeError, ValueError):
-        return None
-
-
-def _json_dumps(value: Any) -> str:
-    return json.dumps(value if value is not None else [], ensure_ascii=False, sort_keys=True)
-
-
-def _json_loads(value: Any) -> Any:
-    if not value:
-        return []
-    try:
-        return json.loads(str(value))
-    except json.JSONDecodeError:
-        return []
-
+def _ensure_project_memory_table(conn: Any, text_fn: Any) -> None:
+    """Ensure Project Memory SQL table and indexes exist.
 
-def _build_memory_id() -> str:
-    return f"pmem_{uuid.uuid4().hex[:16]}"
+    Args:
+        conn: SQLAlchemy connection.
+        text_fn: SQLAlchemy text constructor.
 
+    Returns:
+        None.
+    """
 
-def _ensure_project_memory_table(conn: Any, text_fn: Any) -> None:
     conn.execute(text_fn(PROJECT_MEMORY_TABLE_SQL))
     conn.execute(text_fn(PROJECT_MEMORY_SCOPE_INDEX_SQL))
     conn.execute(text_fn(PROJECT_MEMORY_TYPE_INDEX_SQL))
 
 
-def _build_record_params(
-    *,
-    memory_id: str | None,
-    project_id: str,
-    user_id: str,
-    source_session_id: str | None,
-    source_message_id: str | None,
-    source_id: str | None,
-    memory_type: str,
-    content: str,
-    evidence: list[dict[str, Any]] | None,
-    confidence: float | None,
-    status: str,
-) -> dict[str, Any]:
-    now = _utcnow_iso()
-    return {
-        "memory_id": _normalize_text(memory_id) or _build_memory_id(),
-        "project_id": _normalize_text(project_id),
-        "user_id": _normalize_text(user_id),
-        "source_session_id": _normalize_text(source_session_id),
-        "source_message_id": _normalize_text(source_message_id),
-        "source_id": _normalize_text(source_id),
-        "memory_type": _normalize_text(memory_type) or "fact",
-        "content": str(content or "").strip(),
-        "evidence_json": _json_dumps(evidence),
-        "confidence": confidence,
-        "status": _normalize_status(status),
-        "created_at": now,
-        "updated_at": now,
-    }
-
-
-def _row_to_record(row: Any) -> dict[str, Any]:
-    record = dict(row)
-    record["evidence"] = _json_loads(record.pop("evidence_json", ""))
-    record["confidence"] = _normalize_confidence(record.get("confidence"))
-    return record
-
-
-def _require_scope(project_id: str, user_id: str) -> tuple[str, str]:
-    resolved_project_id = _normalize_text(project_id)
-    resolved_user_id = _normalize_text(user_id)
-    if not resolved_project_id:
-        raise ValueError("project_id is required")
-    if not resolved_user_id:
-        raise ValueError("user_id is required")
-    return resolved_project_id, resolved_user_id
-
-
-def _require_content(content: str) -> str:
-    resolved = str(content or "").strip()
-    if not resolved:
-        raise ValueError("content is required")
-    return resolved
+def _project_memory_engine(build_sqlalchemy_engine_fn: Callable[[], Any]) -> Any:
+    """Resolve the SQLAlchemy engine used by Project Memory storage.
 
+    Args:
+        build_sqlalchemy_engine_fn: Engine factory injected for tests/runtime.
+
+    Returns:
+        SQLAlchemy engine.
+
+    Raises:
+        RuntimeError: If no SQLAlchemy engine is available.
+    """
 
-def _project_memory_engine(build_sqlalchemy_engine_fn: Callable[[], Any]) -> Any:
     engine = build_sqlalchemy_engine_fn()
     if engine is None:
         raise RuntimeError("SQLAlchemy engine is unavailable for project memory storage")
@@ -141,10 +76,28 @@ def upsert_project_memory_record(
     status: str = "active",
     build_sqlalchemy_engine_fn: Callable[[], Any] = build_sqlalchemy_engine,
 ) -> dict[str, Any]:
-    """Create or update a Project Memory record in SQL storage."""
-
-    resolved_project_id, resolved_user_id = _require_scope(project_id, user_id)
-    params = _build_record_params(
+    """Create or update a Project Memory record in SQL storage.
+
+    Args:
+        project_id: Owning project id.
+        user_id: Owning user id.
+        content: Durable memory text.
+        memory_id: Optional existing memory id for update.
+        memory_type: Memory category.
+        source_session_id: Producing session id, when available.
+        source_message_id: Producing message id, when available.
+        source_id: Producing source id, when available.
+        evidence: Optional supporting snippets.
+        confidence: Optional confidence score.
+        status: Lifecycle status.
+        build_sqlalchemy_engine_fn: Engine factory injected for tests/runtime.
+
+    Returns:
+        Persisted ProjectMemoryRecord as a dict.
+    """
+
+    resolved_project_id, resolved_user_id = require_project_memory_scope(project_id, user_id)
+    params = build_project_memory_params(
         memory_id=memory_id,
         project_id=resolved_project_id,
         user_id=resolved_user_id,
@@ -152,9 +105,9 @@ def upsert_project_memory_record(
         source_message_id=source_message_id,
         source_id=source_id,
         memory_type=memory_type,
-        content=_require_content(content),
+        content=require_project_memory_content(content),
         evidence=evidence,
-        confidence=_normalize_confidence(confidence),
+        confidence=normalize_project_memory_confidence(confidence),
         status=status,
     )
     from sqlalchemy import text
@@ -184,9 +137,17 @@ def get_project_memory_record(
     memory_id: str,
     build_sqlalchemy_engine_fn: Callable[[], Any] = build_sqlalchemy_engine,
 ) -> dict[str, Any] | None:
-    """Fetch one Project Memory record by id."""
+    """Fetch one Project Memory record by id.
+
+    Args:
+        memory_id: Stable Project Memory identifier.
+        build_sqlalchemy_engine_fn: Engine factory injected for tests/runtime.
+
+    Returns:
+        ProjectMemoryRecord as a dict, or None when not found.
+    """
 
-    resolved_memory_id = _normalize_text(memory_id)
+    resolved_memory_id = normalize_project_memory_text(memory_id)
     if not resolved_memory_id:
         return None
     from sqlalchemy import text
@@ -197,7 +158,7 @@ def get_project_memory_record(
             text(PROJECT_MEMORY_SELECT_BASE_SQL + " WHERE memory_id = :memory_id LIMIT 1"),
             {"memory_id": resolved_memory_id},
         ).mappings().first()
-    return _row_to_record(row) if row else None
+    return row_to_project_memory_record(row) if row else None
 
 
 def list_project_memory_records(
@@ -207,10 +168,20 @@ def list_project_memory_records(
     status: str = "active",
     build_sqlalchemy_engine_fn: Callable[[], Any] = build_sqlalchemy_engine,
 ) -> list[dict[str, Any]]:
-    """List Project Memory records by project/user scope and status."""
+    """List Project Memory records by project/user scope and status.
+
+    Args:
+        project_id: Owning project id.
+        user_id: Owning user id.
+        status: Lifecycle status filter.
+        build_sqlalchemy_engine_fn: Engine factory injected for tests/runtime.
+
+    Returns:
+        ProjectMemoryRecord dicts ordered by updated_at descending.
+    """
 
-    resolved_project_id, resolved_user_id = _require_scope(project_id, user_id)
-    resolved_status = _normalize_status(status)
+    resolved_project_id, resolved_user_id = require_project_memory_scope(project_id, user_id)
+    resolved_status = normalize_project_memory_status(status)
     from sqlalchemy import text
 
     with _project_memory_engine(build_sqlalchemy_engine_fn).begin() as conn:
@@ -219,7 +190,7 @@ def list_project_memory_records(
             text(PROJECT_MEMORY_SELECT_BASE_SQL + PROJECT_MEMORY_LIST_WHERE_SQL),
             {"project_id": resolved_project_id, "user_id": resolved_user_id, "status": resolved_status},
         ).mappings().all()
-    return [_row_to_record(row) for row in rows]
+    return [row_to_project_memory_record(row) for row in rows]
 
 
 def search_project_memory_records(
@@ -231,9 +202,21 @@ def search_project_memory_records(
     status: str = "active",
     build_sqlalchemy_engine_fn: Callable[[], Any] = build_sqlalchemy_engine,
 ) -> list[dict[str, Any]]:
-    """Lexically recall Project Memory records within one project/user scope."""
+    """Lexically recall Project Memory records within one project/user scope.
 
-    clean_query = _normalize_text(query)
+    Args:
+        project_id: Owning project id.
+        user_id: Owning user id.
+        query: Recall query text.
+        top_k: Maximum number of records to return.
+        status: Lifecycle status filter.
+        build_sqlalchemy_engine_fn: Engine factory injected for tests/runtime.
+
+    Returns:
+        Matching ProjectMemoryRecord dicts ordered by score and recency.
+    """
+
+    clean_query = normalize_project_memory_text(query)
     if not clean_query:
         return []
     scoped_rows = list_project_memory_records(
@@ -243,14 +226,7 @@ def search_project_memory_records(
         build_sqlalchemy_engine_fn=build_sqlalchemy_engine_fn,
     )
     query_terms = [term.lower() for term in clean_query.split() if term.strip()]
-    scored_rows = [_score_record(row, query_terms) for row in scoped_rows]
+    scored_rows = [score_project_memory_record(row, query_terms) for row in scoped_rows]
     matches = [item for item in scored_rows if item[0] > 0]
     matches.sort(key=lambda item: (item[0], str(item[1].get("updated_at") or "")), reverse=True)
     return [row for _, row in matches[: max(1, min(int(top_k or 5), 20))]]
-
-
-def _score_record(record: dict[str, Any], query_terms: list[str]) -> tuple[int, dict[str, Any]]:
-    content = str(record.get("content") or "").lower()
-    memory_type = str(record.get("memory_type") or "").lower()
-    haystack = f"{memory_type} {content}"
-    return sum(1 for term in query_terms if term in haystack), record

flare_kernel-0.2.6/src/flare_kernel/runtime/project_memory/__init__.py

@@ -0,0 +1,10 @@
+"""Project Memory runtime policy helpers."""
+
+from flare_kernel.runtime.project_memory.extraction import extract_project_memory_candidates
+from flare_kernel.runtime.project_memory.recall import build_project_memory_recall, recall_project_memory
+
+__all__ = [
+    "build_project_memory_recall",
+    "extract_project_memory_candidates",
+    "recall_project_memory",
+]