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

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

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

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

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

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/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.7/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.5 → flare_kernel-0.2.7}/src/flare_kernel/router/kernel_facade/dependency_resolution.py

@@ -156,6 +156,7 @@ def resolve_turn_context_dependencies(
     build_structured_search_results_fn: Any,
     generate_llm_completion_fn: Any,
     resolve_analysis_route_fn: Any,
+    build_project_memory_context_layer_fn: Any,
     kernel_attr_fn: Callable[[str, Any], Any],
     defaults: dict[str, Any],
 ) -> dict[str, Any]:
@@ -202,6 +203,8 @@ def resolve_turn_context_dependencies(
         or kernel_attr_fn("generate_llm_completion", defaults["generate_llm_completion_fn"]),
         "resolve_analysis_route_fn": resolve_analysis_route_fn
         or kernel_attr_fn("resolve_analysis_route_from_runtime", defaults["resolve_analysis_route_fn"]),
+        "build_project_memory_context_layer_fn": build_project_memory_context_layer_fn
+        or kernel_attr_fn("build_project_memory_context_layer", defaults["build_project_memory_context_layer_fn"]),
     }
 
 

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/src/flare_kernel/router/kernel_facade/flow.py

@@ -51,6 +51,7 @@ async def prepare_kernel_turn_context_flow(
     generate_llm_completion_fn: Callable[..., Any] | None = None,
     search_web_sources_fn: Callable[..., list[dict[str, Any]]] | None = None,
     resolve_analysis_route_fn: Callable[..., dict[str, Any]] | None = None,
+    build_project_memory_context_layer_fn: Callable[..., dict[str, Any]] | None = None,
 ) -> dict[str, Any]:
     """Assemble the turn context consumed by kernel run/action/stream handlers."""
     trace_id = resolve_trace_id_fn(req.trace_id)
@@ -143,8 +144,18 @@ async def prepare_kernel_turn_context_flow(
             "confidence": 0.0,
         }
 
+    project_memory_recall = {}
+    if callable(build_project_memory_context_layer_fn):
+        project_memory_recall = build_project_memory_context_layer_fn(
+            project_id=project_id,
+            user_id=user_id,
+            query=raw_message,
+        )
+
     enriched_payload = enrich_payload_fn(req, resolved_mode=resolved_mode, retrieved_knowledge=retrieved_knowledge)
     if isinstance(enriched_payload, dict):
+        if isinstance(project_memory_recall, dict) and project_memory_recall:
+            enriched_payload["project_memory_recall"] = project_memory_recall
         enriched_payload["analysis_route"] = analysis_route
         if not _has_question_answer(enriched_payload):
             structured_reasoning = await generate_structured_reasoning(
@@ -244,6 +255,7 @@ async def prepare_kernel_turn_context_flow(
         "effective_command": effective_command,
         "structured_retrieved_knowledge": structured_retrieved_knowledge,
         "analysis_route": analysis_route,
+        "project_memory_recall": project_memory_recall,
     }
 
 

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/src/flare_kernel/router/kernel_facade/turn_context.py

@@ -57,6 +57,7 @@ from flare_kernel.router.text_safety import (
 from flare_kernel.runtime.orchestration.analysis_router_runtime import (
     resolve_analysis_route as resolve_analysis_route_from_runtime,
 )
+from flare_kernel.runtime.project_memory import build_project_memory_context_layer
 
 
 async def _prepare_kernel_turn_context(
@@ -86,6 +87,7 @@ async def _prepare_kernel_turn_context(
     generate_llm_completion_fn=None,
     search_web_sources_fn=None,
     resolve_analysis_route_fn=None,
+    build_project_memory_context_layer_fn=None,
 ) -> dict[str, Any]:
     turn_context_deps = resolve_turn_context_dependencies(
         resolve_trace_id_fn=resolve_trace_id_fn,
@@ -111,6 +113,7 @@ async def _prepare_kernel_turn_context(
         build_structured_search_results_fn=build_structured_search_results_fn,
         generate_llm_completion_fn=generate_llm_completion_fn,
         resolve_analysis_route_fn=resolve_analysis_route_fn,
+        build_project_memory_context_layer_fn=build_project_memory_context_layer_fn,
         kernel_attr_fn=_kernel_attr,
         defaults={
             "resolve_trace_id_fn": resolve_trace_id,
@@ -136,6 +139,7 @@ async def _prepare_kernel_turn_context(
             "build_structured_search_results_fn": build_structured_search_results_from_intake_status,
             "generate_llm_completion_fn": generate_llm_completion,
             "resolve_analysis_route_fn": resolve_analysis_route_from_runtime,
+            "build_project_memory_context_layer_fn": build_project_memory_context_layer,
         },
     )
     return await prepare_kernel_turn_context_flow(
@@ -164,6 +168,7 @@ async def _prepare_kernel_turn_context(
         generate_llm_completion_fn=turn_context_deps["generate_llm_completion_fn"],
         search_web_sources_fn=search_web_sources_fn,
         resolve_analysis_route_fn=turn_context_deps["resolve_analysis_route_fn"],
+        build_project_memory_context_layer_fn=turn_context_deps["build_project_memory_context_layer_fn"],
     )
 
 

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/src/flare_kernel/router/kernel_route/run.py

@@ -6,6 +6,7 @@ from typing import Any
 
 from flare_kernel.contracts import KernelRequest, KernelResponse
 from flare_kernel.runtime import generate_llm_completion, get_logger, persist_memory_record
+from flare_kernel.runtime.project_memory import persist_project_memory_from_runtime
 from flare_kernel.router.completion.response_builder import (
     apply_completion_content_policy as apply_completion_content_policy_from_router,
     build_kernel_success_response as build_kernel_success_response_from_router,
@@ -117,6 +118,14 @@ async def build_kernel_run_response(
             model=completion.model,
             provider_status=completion.status,
         )
+    project_memory_record = persist_project_memory_from_runtime(
+        project_id=project_id,
+        user_id=user_id,
+        source_session_id=session_id,
+        runtime_snapshot=runtime_snapshot,
+    )
+    if project_memory_record:
+        memory_record.update(project_memory_record)
     has_llm_content = bool(str(content_text or "").strip())
     apply_completion_content_policy_from_router(
         orchestration_status=orchestration_status,

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/src/flare_kernel/router/prompting/context_blocks.py

@@ -69,6 +69,31 @@ def _format_recent_turns(turns: Any, *, limit: int) -> str:
     return " || ".join(parts)
 
 
+def _format_project_memories(memories: Any, *, limit: int) -> str:
+    """Format recalled Project Memory records for prompt context.
+
+    Args:
+        memories: Recalled memory records.
+        limit: Maximum number of memory records to include.
+
+    Returns:
+        Compact Project Memory text block.
+    """
+
+    if not isinstance(memories, list):
+        return ""
+    parts: list[str] = []
+    for item in memories[:limit]:
+        if not isinstance(item, dict):
+            continue
+        memory_type = _clean_context_text(item.get("memory_type"))
+        content = _clean_context_text(item.get("content"))
+        if not content:
+            continue
+        parts.append(f"{memory_type}: {content}" if memory_type else content)
+    return "; ".join(parts)
+
+
 def _append_session_context_prompt_parts(prompt_parts: list[str], payload: dict[str, Any]) -> None:
     session_context = payload.get("session_context")
     if not isinstance(session_context, dict) or not session_context:
@@ -93,6 +118,25 @@ def _append_session_context_prompt_parts(prompt_parts: list[str], payload: dict[
         prompt_parts.append(f"session_context_recent_turns: {recent_turns}")
 
 
+def _append_project_memory_prompt_parts(prompt_parts: list[str], payload: dict[str, Any]) -> None:
+    """Append project-level recalled memory to prompt parts.
+
+    Args:
+        prompt_parts: Mutable prompt line list.
+        payload: Enriched kernel payload.
+
+    Returns:
+        None.
+    """
+
+    recall = payload.get("project_memory_recall")
+    if not isinstance(recall, dict) or not recall:
+        return
+    memories = _format_project_memories(recall.get("memories"), limit=5)
+    if memories:
+        prompt_parts.append(f"project_memory: {memories}")
+
+
 def _append_track_prompt_parts(prompt_parts: list[str], payload: dict[str, Any]) -> None:
     track = payload.get("track_result")
     if not isinstance(track, dict) or not track:
@@ -123,6 +167,7 @@ def _append_understanding_summary_prompt_part(prompt_parts: list[str], payload:
 
 
 __all__ = [
+    "_append_project_memory_prompt_parts",
     "_append_session_context_prompt_parts",
     "_append_track_prompt_parts",
     "_append_understanding_summary_prompt_part",

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/src/flare_kernel/router/prompting/core.py

@@ -7,6 +7,7 @@ from typing import Any, Callable
 
 from flare_kernel.contracts import KernelRequest
 from flare_kernel.router.prompting.context_blocks import (
+    _append_project_memory_prompt_parts,
     _append_session_context_prompt_parts,
     _append_track_prompt_parts,
     _append_understanding_summary_prompt_part,
@@ -100,6 +101,7 @@ def build_prompt(
     if product_name:
         prompt_parts.append(f"product_name: {product_name}")
     _append_session_context_prompt_parts(prompt_parts, payload)
+    _append_project_memory_prompt_parts(prompt_parts, payload)
     _append_track_prompt_parts(prompt_parts, payload)
     append_response_strategy_prompt_parts(prompt_parts, payload)
     _append_understanding_summary_prompt_part(prompt_parts, payload)

{flare_kernel-0.2.5 → flare_kernel-0.2.7}/src/flare_kernel/router/streaming/draft/completion.py

@@ -7,6 +7,7 @@ from typing import Any, Callable
 
 from flare_kernel.contracts import KernelRequest
 from flare_kernel.runtime.llm.llm_provider import LLMCompletion
+from flare_kernel.runtime.project_memory import persist_project_memory_from_runtime
 
 
 _PLAN_MODE_FINALIZE_COMMANDS = {"implement", "apply"}
@@ -100,6 +101,14 @@ async def resolve_draft_completion_artifacts(
             model=completion.model,
             provider_status=completion.status,
         )
+    project_memory_record = persist_project_memory_from_runtime(
+        project_id=project_id,
+        user_id=user_id,
+        source_session_id=session_id,
+        runtime_snapshot=runtime_snapshot,
+    )
+    if project_memory_record:
+        memory_record.update(project_memory_record)
 
     observation_runtime_event = {
         "trace_id": trace_id,

flare_kernel-0.2.7/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