flare-kernel 0.2.2__tar.gz → 0.2.3__tar.gz

{flare_kernel-0.2.2 → flare_kernel-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flare-kernel
-Version: 0.2.2
+Version: 0.2.3
 Summary: FLARE kernel runtime package
 License: Proprietary
 Classifier: Development Status :: 3 - Alpha
@@ -10,7 +10,9 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: flare-engines<0.3.0,>=0.2.0
 Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: python-multipart<1.0,>=0.0.9
 Requires-Dist: pydantic<3,>=2
+Requires-Dist: pypdf<6,>=4
 Requires-Dist: uvicorn<1.0,>=0.30
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: sqlalchemy<3,>=2

{flare_kernel-0.2.2 → flare_kernel-0.2.3}/pyproject.toml

@@ -4,14 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flare-kernel"
-version = "0.2.2"
+version = "0.2.3"
 description = "FLARE kernel runtime package"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "flare-engines>=0.2.0,<0.3.0",
     "fastapi>=0.115,<1.0",
+    "python-multipart>=0.0.9,<1.0",
     "pydantic>=2,<3",
+    "pypdf>=4,<6",
     "uvicorn>=0.30,<1.0",
     "httpx>=0.27,<1.0",
     "sqlalchemy>=2,<3",

flare_kernel-0.2.3/src/flare_kernel/app.py

@@ -0,0 +1,39 @@
+"""FastAPI app factory for flare-kernel."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+
+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
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="FLARE Kernel",
+        version="0.1.0",
+        description="FLARE kernel minimal runtime",
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(kernel_router)
+    app.include_router(project_api_router)
+    app.include_router(session_api_router)
+    app.include_router(source_library_router)
+    app.add_exception_handler(ApiError, api_error_exception_handler)
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(Exception, unhandled_exception_handler)
+    return app

flare_kernel-0.2.3/src/flare_kernel/contracts/__init__.py

@@ -0,0 +1,78 @@
+"""Kernel contracts."""
+
+from flare_kernel.contracts.context import (
+    ContextAnalysisResult,
+    ContextContract,
+    ContextEvidenceItem,
+    ContextSourcingResult,
+    create_empty_context,
+)
+from flare_kernel.contracts.kernel_contract import (
+    AnalysisRouteDecision,
+    DeleteProjectSourceResponse,
+    HealthResponse,
+    IntentSuggestResponse,
+    KernelRequest,
+    KernelResponse,
+    KnowledgeIngestRequest,
+    KnowledgeIngestResponse,
+    KnowledgeSearchRequest,
+    KnowledgeSearchResponse,
+    ProjectSourceRecord,
+    ProjectSourcesResponse,
+    ProjectSourceUploadResponse,
+    SourcingSearchRequest,
+    SourcingSearchResponse,
+)
+from flare_kernel.contracts.mode import Mode, ModeHandler, mode_handlers, run_mode
+from flare_kernel.contracts.project_contract import (
+    ProjectRecord,
+    ProjectsResponse,
+    ProjectUpsertRequest,
+)
+from flare_kernel.contracts.session_contract import (
+    SessionAppendExchangeRequest,
+    SessionCreateRequest,
+    SessionListResponse,
+    SessionMessageListResponse,
+    SessionMessageRecord,
+    SessionRecord,
+    SessionUpdateRequest,
+)
+
+__all__ = [
+    "KernelRequest",
+    "KernelResponse",
+    "AnalysisRouteDecision",
+    "HealthResponse",
+    "IntentSuggestResponse",
+    "ProjectSourceRecord",
+    "ProjectSourceUploadResponse",
+    "ProjectSourcesResponse",
+    "DeleteProjectSourceResponse",
+    "KnowledgeIngestRequest",
+    "KnowledgeIngestResponse",
+    "KnowledgeSearchRequest",
+    "KnowledgeSearchResponse",
+    "SourcingSearchRequest",
+    "SourcingSearchResponse",
+    "ContextContract",
+    "ContextAnalysisResult",
+    "ContextEvidenceItem",
+    "ContextSourcingResult",
+    "create_empty_context",
+    "Mode",
+    "ModeHandler",
+    "mode_handlers",
+    "run_mode",
+    "ProjectRecord",
+    "ProjectUpsertRequest",
+    "ProjectsResponse",
+    "SessionRecord",
+    "SessionCreateRequest",
+    "SessionUpdateRequest",
+    "SessionListResponse",
+    "SessionMessageRecord",
+    "SessionMessageListResponse",
+    "SessionAppendExchangeRequest",
+]

flare_kernel-0.2.3/src/flare_kernel/contracts/context.py

@@ -0,0 +1,42 @@
+"""Canonical context contract for kernel orchestration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ContextEvidenceItem(BaseModel):
+    id: str
+    source: str
+    snippet: str = ""
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContextSourcingResult(BaseModel):
+    round: int
+    items: list[dict[str, Any]] = Field(default_factory=list)
+    timestamp: str
+
+
+class ContextAnalysisResult(BaseModel):
+    version: int
+    payload: dict[str, Any] = Field(default_factory=dict)
+    timestamp: str
+
+
+class ContextContract(BaseModel):
+    context_revision_id: str = ""
+    confirmed_fields: dict[str, Any] = Field(default_factory=dict)
+    missing_fields: list[str] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+    evidence: list[ContextEvidenceItem] = Field(default_factory=list)
+    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)
+
+
+def create_empty_context() -> ContextContract:
+    return ContextContract()

{flare_kernel-0.2.2 → flare_kernel-0.2.3}/src/flare_kernel/contracts/kernel_contract.py

@@ -57,6 +57,8 @@ class KernelRequest(BaseModel):
     canvas_config: dict[str, Any] = Field(default_factory=dict)
     plan_config: dict[str, Any] = Field(default_factory=dict)
     payload: dict[str, Any] = Field(default_factory=dict)
+    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)
     action_key: str | None = None
@@ -69,11 +71,19 @@ class KernelRequest(BaseModel):
     field_value: IntakeFieldValue | None = None
 
 
+class AnalysisRouteDecision(BaseModel):
+    analysis_type: Literal["requirement", "sourcing"] = "requirement"
+    template_id: str = "analysis_requirement_default"
+    reason_codes: list[str] = Field(default_factory=list)
+    confidence: float = 0.0
+
+
 class KernelResponse(BaseModel):
     trace_id: str
     state: Literal["RUNNING", "SUCCEEDED", "FAILED"]
     events: list[dict[str, Any]] = Field(default_factory=list)
     result: dict[str, Any] = Field(default_factory=dict)
+    analysis_route: AnalysisRouteDecision | None = None
     next_actions: list[dict[str, Any]] = Field(default_factory=list)
 
 
@@ -128,9 +138,82 @@ class KnowledgeSearchResponse(BaseModel):
     results: list[dict[str, Any]] = Field(default_factory=list)
 
 
+class SourcingSearchRequest(BaseModel):
+    project_id: str = "default"
+    user_id: str = "default"
+    session_id: str = "default"
+    query: str
+    top_k: int = 8
+    append_mode: bool = False
+    lock_existing_order: bool = True
+    base_result_ids: list[str] = Field(default_factory=list)
+    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)
+    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"
+
+
+class SourcingSearchResponse(BaseModel):
+    trace_id: str
+    retrieval_run_id: str
+    project_id: str
+    user_id: str
+    session_id: str
+    query: str
+    effective_query: str = ""
+    intent: str = ""
+    source_scope: Literal["local", "web", "hybrid"]
+    sourcing_enabled: bool
+    requested_top_k: int = 8
+    returned_count: int = 0
+    has_more: bool = False
+    next_top_k: int = 8
+    source_breakdown: dict[str, int] = Field(default_factory=dict)
+    new_results: list[dict[str, Any]] = Field(default_factory=list)
+    all_results: list[dict[str, Any]] = Field(default_factory=list)
+    results: list[dict[str, Any]] = Field(default_factory=list)
+    shortlist: list[dict[str, Any]] = Field(default_factory=list)
+    blocked: bool = False
+    reason: str = ""
+
+
 class IntentSuggestResponse(BaseModel):
     trace_id: str
     suggested_mode: str
     confidence: float = 0.0
     reason: str = ""
     source: Literal["intent_override", "manual", "current", "llm", "keywords", "fallback"] = "fallback"
+
+
+class ProjectSourceRecord(BaseModel):
+    id: str
+    source_id: str
+    project_id: str
+    user_id: str
+    session_id: str | None = None
+    scope: str = "project"
+    source: str = "local_upload"
+    filename: str
+    mime_type: str = ""
+    size: int | None = None
+    status: Literal["uploaded", "parsing", "chunked", "embedded", "indexed", "ready", "failed"] = "uploaded"
+    error_code: str | None = None
+    error_message: str = ""
+    created_at: str
+    updated_at: str
+    persisted_to_project: bool = True
+
+
+class ProjectSourceUploadResponse(BaseModel):
+    data: ProjectSourceRecord
+
+
+class ProjectSourcesResponse(BaseModel):
+    sources: list[ProjectSourceRecord] = Field(default_factory=list)
+
+
+class DeleteProjectSourceResponse(BaseModel):
+    ok: bool = True

flare_kernel-0.2.3/src/flare_kernel/contracts/mode.py

@@ -0,0 +1,32 @@
+"""Canonical mode contract and dispatch for kernel orchestration."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Literal
+
+from flare_kernel.contracts.context import ContextContract
+
+Mode = Literal["plan", "sourcing", "analysis"]
+ModeHandler = Callable[[ContextContract, dict[str, Any]], ContextContract]
+
+
+def _missing_handler(_context: ContextContract, _payload: dict[str, Any]) -> ContextContract:
+    raise ValueError("mode handler not implemented")
+
+
+mode_handlers: dict[Mode, ModeHandler] = {
+    "plan": _missing_handler,
+    "sourcing": _missing_handler,
+    "analysis": _missing_handler,
+}
+
+
+def run_mode(
+    mode: Mode,
+    handlers: dict[Mode, ModeHandler],
+    context: ContextContract,
+    payload: dict[str, Any] | None = None,
+) -> ContextContract:
+    if mode not in handlers:
+        raise ValueError(f"unsupported mode: {mode}")
+    return handlers[mode](context, payload or {})

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

@@ -0,0 +1,24 @@
+"""Project API contracts."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ProjectRecord(BaseModel):
+    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):
+    project_name: str | None = None
+    status: str = "active"
+
+
+class ProjectsResponse(BaseModel):
+    projects: list[ProjectRecord] = Field(default_factory=list)

flare_kernel-0.2.3/src/flare_kernel/contracts/session_contract.py

@@ -0,0 +1,76 @@
+"""Session API contracts."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SessionRecord(BaseModel):
+    session_id: str
+    project_id: str | None = None
+    title: str
+    preview: str = ""
+    title_source: Literal["default", "auto", "manual"] = "default"
+    status: str = "active"
+    user_id: str | None = None
+    function_type: str | None = None
+    created_at: str
+    updated_at: str
+
+
+class SessionCreateRequest(BaseModel):
+    function_type: str | None = None
+    project_id: str | None = None
+    title: str | None = None
+    user_id: str | None = None
+
+
+class SessionUpdateRequest(BaseModel):
+    function_type: str | None = None
+    status: str | None = None
+    title: str | None = None
+    preview: str | None = None
+    title_source: Literal["default", "auto", "manual"] | None = None
+
+
+class SessionListResponse(BaseModel):
+    sessions: list[SessionRecord] = Field(default_factory=list)
+
+
+class SessionMessageRecord(BaseModel):
+    message_id: str
+    session_id: str
+    role: str
+    content: str
+    attachments: list[dict[str, Any]] = Field(default_factory=list)
+    context_refs: list[dict[str, Any]] = Field(default_factory=list)
+    knowledge_refs: list[dict[str, Any]] = Field(default_factory=list)
+    agent_status: dict[str, Any] | None = None
+    thinking_trace: str = ""
+    execution_trace: dict[str, Any] | None = None
+    knowledge_search: dict[str, Any] | None = None
+    sourcing_candidates: dict[str, Any] | None = None
+    knowledge_citation: dict[str, Any] | None = None
+    context_usage: dict[str, Any] | None = None
+    created_at: str
+
+
+class SessionMessageListResponse(BaseModel):
+    messages: list[SessionMessageRecord] = Field(default_factory=list)
+
+
+class SessionAppendExchangeRequest(BaseModel):
+    user_message: str = ""
+    assistant_message: str = ""
+    attachments: list[dict[str, Any]] = Field(default_factory=list)
+    context_refs: list[dict[str, Any]] = Field(default_factory=list)
+    knowledge_refs: list[dict[str, Any]] = Field(default_factory=list)
+    agent_status: dict[str, Any] | None = None
+    thinking_trace: str = ""
+    execution_trace: dict[str, Any] | None = None
+    knowledge_search: dict[str, Any] | None = None
+    sourcing_candidates: dict[str, Any] | None = None
+    knowledge_citation: dict[str, Any] | None = None
+    context_usage: dict[str, Any] | None = None

flare_kernel-0.2.3/src/flare_kernel/project_store.py

@@ -0,0 +1,84 @@
+"""In-process project store for project APIs."""
+
+from __future__ import annotations
+
+import threading
+from datetime import UTC, datetime
+from typing import Any
+
+from flare_kernel.session_store import list_sessions
+
+_projects: dict[str, dict[str, Any]] = {}
+_lock = threading.Lock()
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _normalize_text(value: Any) -> str:
+    return " ".join(str(value or "").split()).strip()
+
+
+def _build_project_view(record: dict[str, Any]) -> dict[str, Any]:
+    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 list_projects() -> list[dict[str, Any]]:
+    with _lock:
+        rows = [_build_project_view(item) for item in _projects.values()]
+    return sorted(rows, key=lambda item: str(item.get("latest_updated_at") or item.get("updated_at") or ""), reverse=True)
+
+
+def get_project(*, project_id: str) -> dict[str, Any] | None:
+    resolved_project_id = _normalize_text(project_id)
+    if not resolved_project_id:
+        return None
+    with _lock:
+        record = _projects.get(resolved_project_id)
+    if record is None:
+        return None
+    return _build_project_view(record)
+
+
+def upsert_project(*, project_id: str, project_name: str | None, status: str | None = None) -> dict[str, Any]:
+    resolved_project_id = _normalize_text(project_id)
+    if not resolved_project_id:
+        raise ValueError("project_id is required")
+
+    now = _now_iso()
+    with _lock:
+        existing = _projects.get(resolved_project_id)
+        if existing is None:
+            record = {
+                "project_id": resolved_project_id,
+                "project_name": _normalize_text(project_name) or resolved_project_id,
+                "status": _normalize_text(status) or "active",
+                "created_at": now,
+                "updated_at": now,
+            }
+        else:
+            record = dict(existing)
+            next_project_name = _normalize_text(project_name)
+            if next_project_name:
+                record["project_name"] = next_project_name
+            next_status = _normalize_text(status)
+            if next_status:
+                record["status"] = next_status
+            record["updated_at"] = now
+        _projects[resolved_project_id] = record
+        return _build_project_view(record)

{flare_kernel-0.2.2 → flare_kernel-0.2.3}/src/flare_kernel/router/__init__.py

@@ -10,8 +10,11 @@ import importlib
 import sys
 
 from flare_kernel.router.kernel import router as kernel_router
+from flare_kernel.router.project_api import router as project_api_router
+from flare_kernel.router.session_api import router as session_api_router
+from flare_kernel.router.source_library import router as source_library_router
 
-__all__ = ["kernel_router"]
+__all__ = ["kernel_router", "project_api_router", "source_library_router", "session_api_router"]
 
 
 def _resolve_legacy_group(module_name: str) -> str | None:

flare_kernel-0.2.3/src/flare_kernel/router/api_errors.py

@@ -0,0 +1,129 @@
+"""API error contract helpers for transport-layer responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse
+
+
+@dataclass(slots=True)
+class ApiError(Exception):
+    """Structured API error for transport-layer mapping."""
+
+    code: str
+    http_status: int
+    message: str
+    description: str = ""
+    context_fields: list[str] = field(default_factory=list)
+    retryable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+def build_error_response_payload(
+    *,
+    code: str,
+    http_status: int,
+    message: str,
+    description: str = "",
+    context_fields: list[str] | None = None,
+    retryable: bool = False,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    context_field_list = list(context_fields or [])
+    return {
+        "error": {
+            "code": code,
+            "message": message,
+            "details": {
+                **(details or {}),
+                "http_status": http_status,
+                "description": description,
+                "context_fields": context_field_list,
+                "retryable": retryable,
+            },
+        }
+    }
+
+
+def _default_code_by_status(status_code: int) -> str:
+    if status_code == 403:
+        return "FORBIDDEN_SCOPE"
+    if status_code == 404:
+        return "RESOURCE_NOT_FOUND"
+    if status_code == 409:
+        return "INVALID_STATE_TRANSITION"
+    if status_code == 422:
+        return "INVALID_REQUEST"
+    if status_code == 401:
+        return "UNAUTHORIZED"
+    return "HTTP_EXCEPTION"
+
+
+def _default_message_by_status(status_code: int) -> str:
+    if status_code == 403:
+        return "forbidden scope"
+    if status_code == 404:
+        return "resource not found"
+    if status_code == 409:
+        return "invalid state transition"
+    if status_code == 422:
+        return "invalid request"
+    if status_code == 401:
+        return "unauthorized"
+    return "request failed"
+
+
+async def api_error_exception_handler(_: Request, exc: ApiError) -> JSONResponse:
+    payload = build_error_response_payload(
+        code=exc.code,
+        http_status=exc.http_status,
+        message=exc.message,
+        description=exc.description,
+        context_fields=exc.context_fields,
+        retryable=exc.retryable,
+        details=exc.details,
+    )
+    return JSONResponse(status_code=exc.http_status, content=payload)
+
+
+async def http_exception_handler(_: Request, exc: HTTPException) -> JSONResponse:
+    status_code = int(exc.status_code)
+    code = _default_code_by_status(status_code)
+    message = _default_message_by_status(status_code)
+    details: dict[str, Any] = {}
+
+    if isinstance(exc.detail, dict):
+        maybe_error = exc.detail.get("error")
+        if isinstance(maybe_error, dict):
+            code = str(maybe_error.get("code") or code)
+            message = str(maybe_error.get("message") or message)
+            details = maybe_error.get("details") if isinstance(maybe_error.get("details"), dict) else {}
+        else:
+            code = str(exc.detail.get("code") or code)
+            message = str(exc.detail.get("message") or message)
+            details = exc.detail.get("details") if isinstance(exc.detail.get("details"), dict) else {}
+    elif isinstance(exc.detail, str) and exc.detail.strip():
+        message = exc.detail.strip()
+
+    payload = build_error_response_payload(
+        code=code,
+        http_status=status_code,
+        message=message,
+        details=details,
+    )
+    return JSONResponse(status_code=status_code, content=payload)
+
+
+async def unhandled_exception_handler(_: Request, __: Exception) -> JSONResponse:
+    payload = build_error_response_payload(
+        code="INTERNAL_ERROR",
+        http_status=500,
+        message="internal server error",
+        description="unexpected server exception",
+        retryable=False,
+    )
+    return JSONResponse(status_code=500, content=payload)
+

{flare_kernel-0.2.2 → flare_kernel-0.2.3}/src/flare_kernel/router/intent/intent_retrieval.py

@@ -89,6 +89,9 @@ def search_knowledge_by_queries(
     queries: list[str],
     top_k: int,
     min_score: float,
+    source_ids: list[str] | None = None,
+    entities: list[dict[str, Any] | str] | None = None,
+    entity_query_mode: str = "prefer",
 ) -> list[dict[str, Any]]:
     return search_knowledge_by_queries_from_router(
         trace_id=trace_id,
@@ -97,5 +100,8 @@ def search_knowledge_by_queries(
         queries=queries,
         top_k=top_k,
         min_score=min_score,
+        source_ids=source_ids,
+        entities=entities,
+        entity_query_mode=entity_query_mode,
         search_knowledge_records_fn=search_knowledge_records,
     )