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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flare-kernel
-Version: 0.2.4
+Version: 0.2.5
 Summary: FLARE kernel runtime package
 License: Proprietary
 Classifier: Development Status :: 3 - Alpha
@@ -27,7 +27,8 @@ Requires-Dist: qdrant-client<2,>=1.9
 边界文档：
 
 1. `packages/flare-kernel/docs/KERNEL-BOUNDARY.md`
-2. `docs/contracts/agent-contract-v1.md`
+2. `docs/contracts/core/agent.md`
+3. `packages/flare-kernel/docs/replay-snapshot-technical-spec.md`
 
 职责：
 

{flare_kernel-0.2.4 → flare_kernel-0.2.5}/README.md

@@ -5,7 +5,8 @@
 边界文档：
 
 1. `packages/flare-kernel/docs/KERNEL-BOUNDARY.md`
-2. `docs/contracts/agent-contract-v1.md`
+2. `docs/contracts/core/agent.md`
+3. `packages/flare-kernel/docs/replay-snapshot-technical-spec.md`
 
 职责：
 

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

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

{flare_kernel-0.2.4 → flare_kernel-0.2.5}/src/flare_kernel/app.py

@@ -5,13 +5,13 @@ from __future__ import annotations
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 
-from flare_kernel.router.api_errors import (
+from flare_kernel.router.api.errors import (
     ApiError,
     api_error_exception_handler,
     http_exception_handler,
     unhandled_exception_handler,
 )
-from flare_kernel.router import kernel_router, project_api_router, session_api_router, source_library_router
+from flare_kernel.router import chat_api_router, kernel_router, project_api_router, session_api_router, source_library_router
 
 
 def create_app() -> FastAPI:
@@ -30,6 +30,7 @@ def create_app() -> FastAPI:
     )
 
     app.include_router(kernel_router)
+    app.include_router(chat_api_router)
     app.include_router(project_api_router)
     app.include_router(session_api_router)
     app.include_router(source_library_router)

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

@@ -2,9 +2,11 @@
 
 from flare_kernel.contracts.context import (
     ContextAnalysisResult,
+    ContextClaimItem,
     ContextContract,
     ContextEvidenceItem,
     ContextSourcingResult,
+    ContextTurnItem,
     create_empty_context,
 )
 from flare_kernel.contracts.kernel_contract import (
@@ -57,9 +59,11 @@ __all__ = [
     "SourcingSearchRequest",
     "SourcingSearchResponse",
     "ContextContract",
+    "ContextClaimItem",
     "ContextAnalysisResult",
     "ContextEvidenceItem",
     "ContextSourcingResult",
+    "ContextTurnItem",
     "create_empty_context",
     "Mode",
     "ModeHandler",

{flare_kernel-0.2.4 → flare_kernel-0.2.5}/src/flare_kernel/contracts/context.py

@@ -9,11 +9,29 @@ from pydantic import BaseModel, Field
 
 class ContextEvidenceItem(BaseModel):
     id: str
-    source: str
+    source_id: str = ""
+    source: str = ""
     snippet: str = ""
     meta: dict[str, Any] = Field(default_factory=dict)
 
 
+class ContextClaimItem(BaseModel):
+    id: str
+    text: str
+    source_id: str = ""
+    evidence_ids: list[str] = Field(default_factory=list)
+    confidence: float | None = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContextTurnItem(BaseModel):
+    turn_id: str
+    user_message: str = ""
+    assistant_message: str = ""
+    source_ids: list[str] = Field(default_factory=list)
+    created_at: str = ""
+
+
 class ContextSourcingResult(BaseModel):
     round: int
     items: list[dict[str, Any]] = Field(default_factory=list)
@@ -28,14 +46,25 @@ class ContextAnalysisResult(BaseModel):
 
 class ContextContract(BaseModel):
     context_revision_id: str = ""
+    session_summary: str = ""
+    user_focus: list[str] = Field(default_factory=list)
+    response_priorities: list[str] = Field(default_factory=list)
     confirmed_fields: dict[str, Any] = Field(default_factory=dict)
     missing_fields: list[str] = Field(default_factory=list)
     notes: list[str] = Field(default_factory=list)
+    turns: list[ContextTurnItem] = Field(default_factory=list)
     evidence: list[ContextEvidenceItem] = Field(default_factory=list)
+    facts: list[ContextClaimItem] = Field(default_factory=list)
+    inferences: list[ContextClaimItem] = Field(default_factory=list)
+    unknowns: list[ContextClaimItem] = Field(default_factory=list)
+    source_attributions: list[dict[str, Any]] = Field(default_factory=list)
+    artifact_context: list[dict[str, Any]] = Field(default_factory=list)
+    track: dict[str, Any] = Field(default_factory=dict)
     sourcing_results: list[ContextSourcingResult] = Field(default_factory=list)
     analysis_results: list[ContextAnalysisResult] = Field(default_factory=list)
     rank_profile: dict[str, Any] = Field(default_factory=dict)
     rank_feedback_log: list[dict[str, Any]] = Field(default_factory=list)
+    updated_at: str = ""
 
 
 def create_empty_context() -> ContextContract:

{flare_kernel-0.2.4 → flare_kernel-0.2.5}/src/flare_kernel/contracts/kernel_contract.py

@@ -39,6 +39,7 @@ class IntakeFieldValue(BaseModel):
 
 class KernelRequest(BaseModel):
     contract_version: str = "flare.v1"
+    content: str | None = None
     client_request_id: str | None = None
     tenant_id: str = "default"
     instance_id: str = "default"
@@ -60,7 +61,7 @@ class KernelRequest(BaseModel):
     entities: list[dict[str, Any] | str] = Field(default_factory=list)
     entity_query_mode: Literal["off", "prefer", "only"] = "prefer"
     context_refs: list[Any] = Field(default_factory=list)
-    knowledge_refs: list[str] = Field(default_factory=list)
+    knowledge_refs: list[Any] = Field(default_factory=list)
     action_key: str | None = None
     target_mode: str | None = None
     action_status: str | None = None
@@ -70,6 +71,18 @@ class KernelRequest(BaseModel):
     field_key: str | None = None
     field_value: IntakeFieldValue | None = None
 
+    @model_validator(mode="after")
+    def normalize_top_level_content_into_payload(self) -> "KernelRequest":
+        content = str(self.content or "").strip()
+        if not content:
+            return self
+        payload = dict(self.payload or {})
+        message = str(payload.get("message") or "").strip()
+        if not message:
+            payload["message"] = content
+            self.payload = payload
+        return self
+
 
 class AnalysisRouteDecision(BaseModel):
     analysis_type: Literal["requirement", "sourcing"] = "requirement"
@@ -150,7 +163,7 @@ class SourcingSearchRequest(BaseModel):
     source_scope: Literal["local", "web", "hybrid"] = "hybrid"
     sourcing_enabled: bool = False
     context_refs: list[Any] = Field(default_factory=list)
-    knowledge_refs: list[str] = Field(default_factory=list)
+    knowledge_refs: list[Any] = Field(default_factory=list)
     source_ids: list[str] = Field(default_factory=list)
     entities: list[dict[str, Any] | str] = Field(default_factory=list)
     entity_query_mode: Literal["off", "prefer", "only"] = "prefer"
@@ -165,6 +178,8 @@ class SourcingSearchResponse(BaseModel):
     query: str
     effective_query: str = ""
     intent: str = ""
+    sourcing_task_kind: str = "mixed"
+    response_label: str = "候选条目"
     source_scope: Literal["local", "web", "hybrid"]
     sourcing_enabled: bool
     requested_top_k: int = 8

flare_kernel-0.2.5/src/flare_kernel/contracts/project_contract.py

@@ -0,0 +1,49 @@
+"""Project API contracts."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ProjectRecord(BaseModel):
+    """Persisted Project row returned by the Project API.
+
+    Attributes:
+        project_id: Stable Project identifier used by frontend and backend routes.
+        project_name: Human-readable Project name shown in the UI.
+        status: Project lifecycle state, for example "active" or "archived".
+        session_count: Number of sessions currently linked to this Project.
+        created_at: ISO timestamp for Project creation when available.
+        updated_at: ISO timestamp for the stored Project row update when available.
+        latest_updated_at: Most recent Project activity timestamp, including sessions.
+    """
+
+    project_id: str
+    project_name: str
+    status: str = "active"
+    session_count: int = 0
+    created_at: str | None = None
+    updated_at: str | None = None
+    latest_updated_at: str | None = None
+
+
+class ProjectUpsertRequest(BaseModel):
+    """Request body for creating or updating a Project.
+
+    Attributes:
+        project_name: Optional replacement Project display name.
+        status: Project lifecycle state to persist; defaults to "active".
+    """
+
+    project_name: str | None = None
+    status: str = "active"
+
+
+class ProjectsResponse(BaseModel):
+    """Response body for listing Projects.
+
+    Attributes:
+        projects: Persisted Project records visible in the current user scope.
+    """
+
+    projects: list[ProjectRecord] = Field(default_factory=list)

{flare_kernel-0.2.4 → flare_kernel-0.2.5}/src/flare_kernel/contracts/session_contract.py

@@ -6,6 +6,8 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
+from flare_kernel.contracts.context import ContextContract, create_empty_context
+
 
 class SessionRecord(BaseModel):
     session_id: str
@@ -16,6 +18,7 @@ class SessionRecord(BaseModel):
     status: str = "active"
     user_id: str | None = None
     function_type: str | None = None
+    context: ContextContract = Field(default_factory=create_empty_context)
     created_at: str
     updated_at: str
 
@@ -54,6 +57,7 @@ class SessionMessageRecord(BaseModel):
     sourcing_candidates: dict[str, Any] | None = None
     knowledge_citation: dict[str, Any] | None = None
     context_usage: dict[str, Any] | None = None
+    plan_payload: dict[str, Any] | None = None
     created_at: str
 
 
@@ -74,3 +78,9 @@ class SessionAppendExchangeRequest(BaseModel):
     sourcing_candidates: dict[str, Any] | None = None
     knowledge_citation: dict[str, Any] | None = None
     context_usage: dict[str, Any] | None = None
+    plan_payload: dict[str, Any] | None = None
+    reasoning_result: dict[str, Any] | None = None
+    document_result: dict[str, Any] | None = None
+    track_result: dict[str, Any] | None = None
+    context_patch: dict[str, Any] | None = None
+    context_snapshot: dict[str, Any] | None = None

flare_kernel-0.2.5/src/flare_kernel/project_store.py

@@ -0,0 +1,249 @@
+"""Project repository backed by FLARE SQL storage."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from flare_kernel.runtime.infrastructure.database import build_sqlalchemy_engine
+from flare_kernel.session_store import list_sessions
+from flare_kernel.user_store import get_current_user_id
+
+
+def _now_iso() -> str:
+    """Build the current UTC timestamp for persisted Project records.
+
+    Returns:
+        ISO-formatted UTC timestamp string.
+    """
+
+    return datetime.now(UTC).isoformat()
+
+
+def _normalize_text(value: Any) -> str:
+    """Normalize a Project text value before storage or response projection.
+
+    Args:
+        value: Raw text-like value from API input or persisted storage.
+
+    Returns:
+        Whitespace-collapsed string, or an empty string when value is missing.
+    """
+
+    return " ".join(str(value or "").split()).strip()
+
+
+def _ensure_project_table(conn: Any, text_fn: Any) -> None:
+    """Create the durable Project table when it does not exist.
+
+    Args:
+        conn: Active SQLAlchemy connection or transaction connection.
+        text_fn: SQLAlchemy text factory used by the caller's SQL boundary.
+
+    Returns:
+        None. The table is created as a database side effect.
+    """
+
+    conn.execute(
+        text_fn(
+            """
+            CREATE TABLE IF NOT EXISTS flare_projects (
+                project_id TEXT NOT NULL,
+                user_id TEXT NOT NULL,
+                project_name TEXT NOT NULL,
+                status TEXT NOT NULL,
+                created_at TEXT,
+                updated_at TEXT,
+                PRIMARY KEY (user_id, project_id)
+            )
+            """
+        )
+    )
+
+
+def _build_project_view(record: dict[str, Any]) -> dict[str, Any]:
+    """Project a stored Project row into the Project API response shape.
+
+    Args:
+        record: Persisted Project row with project_id, project_name, status, and timestamps.
+
+    Returns:
+        Dictionary matching ProjectRecord fields, including derived session_count and latest_updated_at.
+    """
+
+    project_id = _normalize_text(record.get("project_id"))
+    session_rows = list_sessions(project_id=project_id)
+    latest_updated_at = ""
+    if session_rows:
+        latest_updated_at = str(session_rows[0].get("updated_at") or "").strip()
+    updated_at = _normalize_text(record.get("updated_at")) or latest_updated_at or _normalize_text(record.get("created_at"))
+    return {
+        "project_id": project_id,
+        "project_name": _normalize_text(record.get("project_name")) or project_id,
+        "status": _normalize_text(record.get("status")) or "active",
+        "session_count": len(session_rows),
+        "created_at": _normalize_text(record.get("created_at")) or None,
+        "updated_at": updated_at or None,
+        "latest_updated_at": latest_updated_at or updated_at or None,
+    }
+
+
+def _project_engine() -> Any:
+    """Resolve the SQLAlchemy engine required by Project persistence.
+
+    Returns:
+        SQLAlchemy Engine configured from FLARE_POSTGRES_DSN.
+
+    Raises:
+        RuntimeError: When SQLAlchemy or the configured engine is unavailable.
+    """
+
+    engine = build_sqlalchemy_engine()
+    if engine is None:
+        raise RuntimeError("SQLAlchemy engine is unavailable for project storage")
+    return engine
+
+
+def list_projects() -> list[dict[str, Any]]:
+    """List durable Projects for the current database user scope.
+
+    Returns:
+        Project view dictionaries sorted by persisted updated_at descending.
+    """
+
+    from sqlalchemy import text
+
+    with _project_engine().begin() as conn:
+        _ensure_project_table(conn, text)
+        user_id = get_current_user_id(conn, text)
+        rows = conn.execute(
+            text(
+                """
+                SELECT project_id, user_id, project_name, status, created_at, updated_at
+                FROM flare_projects
+                WHERE user_id = :user_id
+                ORDER BY updated_at DESC
+                """
+            ),
+            {"user_id": user_id},
+        ).mappings().all()
+    return [_build_project_view(dict(row)) for row in rows]
+
+
+def get_project(*, project_id: str) -> dict[str, Any] | None:
+    """Fetch one durable Project by id in the current database user scope.
+
+    Args:
+        project_id: Stable Project identifier to load.
+
+    Returns:
+        Project view dictionary when found, otherwise None.
+    """
+
+    resolved_project_id = _normalize_text(project_id)
+    if not resolved_project_id:
+        return None
+
+    from sqlalchemy import text
+
+    with _project_engine().begin() as conn:
+        _ensure_project_table(conn, text)
+        user_id = get_current_user_id(conn, text)
+        row = conn.execute(
+            text(
+                """
+                SELECT project_id, user_id, project_name, status, created_at, updated_at
+                FROM flare_projects
+                WHERE user_id = :user_id AND project_id = :project_id
+                LIMIT 1
+                """
+            ),
+            {"user_id": user_id, "project_id": resolved_project_id},
+        ).mappings().first()
+    return _build_project_view(dict(row)) if row else None
+
+
+def upsert_project(*, project_id: str, project_name: str | None, status: str | None = None) -> dict[str, Any]:
+    """Create or update a durable Project name and status.
+
+    Args:
+        project_id: Stable Project identifier to create or update.
+        project_name: Optional Project display name; existing name is preserved when blank on update.
+        status: Optional lifecycle status; existing status is preserved when blank on update.
+
+    Returns:
+        Project view dictionary after persistence.
+
+    Raises:
+        ValueError: When project_id is empty.
+        RuntimeError: When the upsert does not produce a stored Project record.
+    """
+
+    resolved_project_id = _normalize_text(project_id)
+    if not resolved_project_id:
+        raise ValueError("project_id is required")
+
+    now = _now_iso()
+    next_project_name = _normalize_text(project_name)
+    next_status = _normalize_text(status)
+
+    from sqlalchemy import text
+
+    with _project_engine().begin() as conn:
+        _ensure_project_table(conn, text)
+        user_id = get_current_user_id(conn, text)
+        existing = conn.execute(
+            text(
+                """
+                SELECT project_id, user_id, project_name, status, created_at, updated_at
+                FROM flare_projects
+                WHERE user_id = :user_id AND project_id = :project_id
+                LIMIT 1
+                """
+            ),
+            {"user_id": user_id, "project_id": resolved_project_id},
+        ).mappings().first()
+        if existing is None:
+            conn.execute(
+                text(
+                    """
+                    INSERT INTO flare_projects (
+                        project_id, user_id, project_name, status, created_at, updated_at
+                    ) VALUES (
+                        :project_id, :user_id, :project_name, :status, :created_at, :updated_at
+                    )
+                    """
+                ),
+                {
+                    "project_id": resolved_project_id,
+                    "user_id": user_id,
+                    "project_name": next_project_name or resolved_project_id,
+                    "status": next_status or "active",
+                    "created_at": now,
+                    "updated_at": now,
+                },
+            )
+        else:
+            current = dict(existing)
+            conn.execute(
+                text(
+                    """
+                    UPDATE flare_projects
+                    SET project_name = :project_name,
+                        status = :status,
+                        updated_at = :updated_at
+                    WHERE user_id = :user_id AND project_id = :project_id
+                    """
+                ),
+                {
+                    "project_id": resolved_project_id,
+                    "user_id": user_id,
+                    "project_name": next_project_name or _normalize_text(current.get("project_name")) or resolved_project_id,
+                    "status": next_status or _normalize_text(current.get("status")) or "active",
+                    "updated_at": now,
+                },
+            )
+    stored = get_project(project_id=resolved_project_id)
+    if stored is None:
+        raise RuntimeError("project upsert did not persist a project record")
+    return stored

flare_kernel-0.2.5/src/flare_kernel/router/__init__.py

@@ -0,0 +1,17 @@
+"""Kernel router public exports."""
+
+from __future__ import annotations
+
+from flare_kernel.router.api.project import router as project_api_router
+from flare_kernel.router.api.session import router as session_api_router
+from flare_kernel.router.api.chat import router as chat_api_router
+from flare_kernel.router.kernel import router as kernel_router
+from flare_kernel.router.source_library import router as source_library_router
+
+__all__ = [
+    "kernel_router",
+    "chat_api_router",
+    "project_api_router",
+    "session_api_router",
+    "source_library_router",
+]

flare_kernel-0.2.5/src/flare_kernel/router/api/chat.py

@@ -0,0 +1,29 @@
+"""Chat API aliases backed by kernel runtime endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+from fastapi.responses import StreamingResponse
+
+from flare_kernel.contracts import KernelRequest, KernelResponse
+from flare_kernel.router.kernel import kernel_action, kernel_run, kernel_stream
+
+router = APIRouter(tags=["chat"])
+
+
+@router.post("/chat/run", response_model=KernelResponse)
+async def chat_run(req: KernelRequest) -> KernelResponse:
+    return await kernel_run(req)
+
+
+@router.post("/chat/action", response_model=KernelResponse)
+async def chat_action(req: KernelRequest) -> KernelResponse:
+    return await kernel_action(req)
+
+
+@router.post("/chat/stream")
+async def chat_stream(req: KernelRequest) -> StreamingResponse:
+    return await kernel_stream(req)
+
+
+__all__ = ["router"]

flare_kernel-0.2.4/src/flare_kernel/router/project_api.py → flare_kernel-0.2.5/src/flare_kernel/router/api/project.py

@@ -12,12 +12,28 @@ router = APIRouter(tags=["projects"])
 
 @router.get("/projects", response_model=ProjectsResponse)
 async def list_project_records() -> ProjectsResponse:
+    """List persisted Projects visible to the current Project scope.
+
+    Returns:
+        ProjectsResponse containing Project records normalized through ProjectRecord.
+    """
+
     rows = list_projects()
     return ProjectsResponse(projects=[ProjectRecord.model_validate(row) for row in rows])
 
 
 @router.put("/projects/{project_id}", response_model=ProjectRecord)
 async def upsert_project_record(project_id: str, req: ProjectUpsertRequest) -> ProjectRecord:
+    """Create or update a persisted Project record.
+
+    Args:
+        project_id: Stable Project identifier from the route path.
+        req: Request body carrying the Project name and lifecycle status.
+
+    Returns:
+        ProjectRecord containing the stored Project row after the upsert.
+    """
+
     row = upsert_project(
         project_id=project_id,
         project_name=req.project_name,

flare_kernel-0.2.4/src/flare_kernel/router/session_api.py → flare_kernel-0.2.5/src/flare_kernel/router/api/session.py

@@ -12,7 +12,7 @@ from flare_kernel.contracts import (
     SessionRecord,
     SessionUpdateRequest,
 )
-from flare_kernel.router.api_errors import ApiError
+from flare_kernel.router.api.errors import ApiError
 from flare_kernel.session_store import (
     append_exchange,
     create_session,
@@ -116,6 +116,12 @@ async def append_chat_session_exchange(session_id: str, req: SessionAppendExchan
         sourcing_candidates=req.sourcing_candidates,
         knowledge_citation=req.knowledge_citation,
         context_usage=req.context_usage,
+        plan_payload=req.plan_payload,
+        reasoning_result=req.reasoning_result,
+        document_result=req.document_result,
+        track_result=req.track_result,
+        context_patch=req.context_patch,
+        context_snapshot=req.context_snapshot,
     )
     return SessionRecord.model_validate(row or _require_session_or_404(session_id))
 

flare_kernel-0.2.4/src/flare_kernel/router/canonical/canonical_state_context.py → flare_kernel-0.2.5/src/flare_kernel/router/canonical/context/__init__.py

@@ -15,13 +15,13 @@ from __future__ import annotations
 from typing import Any, Callable
 
 from flare_kernel.contracts import KernelRequest
-from flare_kernel.router.canonical.canonical_state_context_analysis import (
+from flare_kernel.router.canonical.context.analysis import (
     build_canonical_state_context_output,
 )
-from flare_kernel.router.canonical.canonical_state_context_inputs import (
+from flare_kernel.router.canonical.context.inputs import (
     resolve_canonical_state_context_inputs,
 )
-from flare_kernel.router.canonical.canonical_state_context_session import (
+from flare_kernel.router.canonical.context.session import (
     resolve_canonical_state_context_session,
 )
 

flare_kernel-0.2.4/src/flare_kernel/router/canonical/canonical_state_context_analysis.py → flare_kernel-0.2.5/src/flare_kernel/router/canonical/context/analysis.py

@@ -5,10 +5,10 @@ from __future__ import annotations
 from typing import Any, Callable
 
 from flare_kernel.contracts import KernelRequest
-from flare_kernel.router.canonical.canonical_state_flow import (
+from flare_kernel.router.canonical.flow import (
     resolve_analysis_generation_state,
 )
-from flare_kernel.router.canonical.canonical_state_projection import (
+from flare_kernel.router.canonical.projection import (
     build_checkpoint_projection,
     build_next_actions_projection,
     resolve_analysis_readiness_metrics,

flare_kernel-0.2.4/src/flare_kernel/router/canonical/canonical_state_context_inputs.py → flare_kernel-0.2.5/src/flare_kernel/router/canonical/context/inputs.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any, Callable
 
-from flare_kernel.router.canonical.canonical_state_projection import (
+from flare_kernel.router.canonical.projection import (
     collect_confirmed_field_values,
 )
 from flare_kernel.router.intent.compat_aliases import (