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

flare_kernel-0.2.8/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: flare-kernel
+Version: 0.2.8
+Summary: FLARE kernel runtime package
+License: Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+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
+Requires-Dist: psycopg2-binary<3,>=2.9
+Requires-Dist: redis<6,>=5
+Requires-Dist: qdrant-client<1.15,>=1.13
+
+# flare-kernel
+
+通用编排与执行内核。
+
+边界文档：
+
+1. `packages/flare-kernel/docs/KERNEL-BOUNDARY.md`
+2. `docs/contracts/core/agent.md`
+3. `packages/flare-kernel/docs/replay-snapshot-technical-spec.md`
+
+职责：
+
+1. Decision 路由与策略入口。
+2. Execution 流程推进与状态管理。
+3. Runtime（含重试、超时、追踪）。
+4. 加载 domain pack 并执行。
+
+## Day 2 最小骨架
+
+目录：
+
+1. `src/flare_kernel/router`：接口路由
+2. `src/flare_kernel/runtime`：`trace_id` 与基础日志
+3. `src/flare_kernel/contracts`：请求/响应契约
+
+最小接口：
+
+1. `POST /kernel/run`
+2. `POST /kernel/stream`
+3. `GET /kernel/health`
+4. `POST /kernel/knowledge/ingest`
+5. `POST /kernel/knowledge/search`
+
+kernel 现已输出 mode/context 运行时占位事件与字段。
+
+## 品牌注入（可选）
+
+1. kernel 支持从 domain-pack 读取品牌配置：
+   `branding/instance-branding.json`
+2. 读取方式：
+   - 仅通过环境变量 `FLARE_DOMAIN_PACK_ROOT` 显式指定
+3. 注入位置：
+   - `POST /kernel/run` 响应 `result.instance_profile`
+   - `POST /kernel/stream` SSE 事件 `instance_profile`
+
+说明：品牌注入通过外部 domain-pack 配置，core 不写死产品名、logo、标签。
+
+本地启动（示例）：
+
+```bash
+uvicorn flare_kernel.main:app --app-dir packages/flare-kernel/src --host 0.0.0.0 --port 8002
+```
+
+环境变量（真实链路）：
+
+1. `DASHSCOPE_API_KEY`（必填，真实百炼调用）
+2. `LLM_PROVIDER_BACKEND`（默认 `dashscope`）
+3. `FLARE_POSTGRES_DSN`
+4. `FLARE_REDIS_URL`
+5. `FLARE_QDRANT_URL`
+
+健康检查会输出依赖状态：
+
+1. `llm_ready`
+2. `postgres_ready`
+3. `redis_ready`
+4. `qdrant_ready`
+
+模式决策优先级（`/kernel/run` 与 `/kernel/stream`）：
+
+1. `intent_override`（外部业务侧注入）
+2. 消息意图识别（内置关键词）
+3. `manual_mode`
+4. `current_mode`
+5. fallback（`intent/default`）
+
+## 最小发布说明
+
+1. 当前包版本：`0.1.0`
+2. 发布元数据：`packages/flare-kernel/pyproject.toml`
+3. 本地构建：`python -m build`
+4. 本地安装：`pip install packages/flare-kernel`

flare_kernel-0.2.8/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flare-kernel"
+version = "0.2.8"
+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",
+    "psycopg2-binary>=2.9,<3",
+    "redis>=5,<6",
+    "qdrant-client>=1.13,<1.15",
+]
+license = { text = "Proprietary" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

flare_kernel-0.2.8/src/flare_kernel/app.py

@@ -0,0 +1,54 @@
+"""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 (
+    auth_api_router,
+    chat_api_router,
+    kernel_router,
+    list_events_api_router,
+    project_api_router,
+    run_api_router,
+    session_api_router,
+    source_library_router,
+    update_api_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(auth_api_router)
+    app.include_router(kernel_router)
+    app.include_router(chat_api_router)
+    app.include_router(list_events_api_router)
+    app.include_router(project_api_router)
+    app.include_router(session_api_router)
+    app.include_router(run_api_router)
+    app.include_router(update_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.8/src/flare_kernel/contracts/__init__.py

@@ -0,0 +1,140 @@
+"""Kernel contracts."""
+
+from flare_kernel.contracts.context import (
+    ContextAnalysisResult,
+    ContextClaimItem,
+    ContextContract,
+    ContextEvidenceItem,
+    ContextSourcingResult,
+    ContextTurnItem,
+    create_empty_context,
+)
+from flare_kernel.contracts.auth_contract import (
+    AuthContext,
+    AuthExchangeRequest,
+    AuthExchangeResponse,
+    AuthPrincipal,
+    AuthorizationDecision,
+)
+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.list_event_contract import (
+    ListEventRecord,
+    ListEventResource,
+)
+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.project_memory_contract import (
+    ProjectMemoryCandidate,
+    ProjectMemoryRecall,
+    ProjectMemoryRecord,
+)
+from flare_kernel.contracts.run_contract import (
+    RunEventListResponse,
+    RunEventRecord,
+    RunListResponse,
+    RunRecord,
+)
+from flare_kernel.contracts.session_contract import (
+    SessionAppendExchangeRequest,
+    SessionCreateRequest,
+    SessionLifecycleRequest,
+    SessionListResponse,
+    SessionMessageListResponse,
+    SessionMessageRecord,
+    SessionRecord,
+    SessionReplayResponse,
+    SessionReplayTurn,
+    SessionUpdateRequest,
+)
+from flare_kernel.contracts.update_contract import (
+    ReleaseManifestEntry,
+    UpdateCheckRequest,
+    UpdateCheckResult,
+    UpgradePlanRequest,
+    UpgradePlanResult,
+    UpgradePlanStep,
+    VersionConstraint,
+)
+
+__all__ = [
+    "KernelRequest",
+    "KernelResponse",
+    "AuthPrincipal",
+    "AuthContext",
+    "AuthExchangeRequest",
+    "AuthExchangeResponse",
+    "AuthorizationDecision",
+    "AnalysisRouteDecision",
+    "HealthResponse",
+    "IntentSuggestResponse",
+    "ProjectSourceRecord",
+    "ProjectSourceUploadResponse",
+    "ProjectSourcesResponse",
+    "DeleteProjectSourceResponse",
+    "KnowledgeIngestRequest",
+    "KnowledgeIngestResponse",
+    "KnowledgeSearchRequest",
+    "KnowledgeSearchResponse",
+    "SourcingSearchRequest",
+    "SourcingSearchResponse",
+    "ListEventRecord",
+    "ListEventResource",
+    "ContextContract",
+    "ContextClaimItem",
+    "ContextAnalysisResult",
+    "ContextEvidenceItem",
+    "ContextSourcingResult",
+    "ContextTurnItem",
+    "create_empty_context",
+    "Mode",
+    "ModeHandler",
+    "mode_handlers",
+    "run_mode",
+    "ProjectRecord",
+    "ProjectUpsertRequest",
+    "ProjectsResponse",
+    "ProjectMemoryCandidate",
+    "ProjectMemoryRecord",
+    "ProjectMemoryRecall",
+    "RunRecord",
+    "RunEventRecord",
+    "RunListResponse",
+    "RunEventListResponse",
+    "SessionRecord",
+    "SessionCreateRequest",
+    "SessionUpdateRequest",
+    "SessionLifecycleRequest",
+    "SessionListResponse",
+    "SessionMessageRecord",
+    "SessionMessageListResponse",
+    "SessionReplayTurn",
+    "SessionReplayResponse",
+    "SessionAppendExchangeRequest",
+    "VersionConstraint",
+    "ReleaseManifestEntry",
+    "UpdateCheckRequest",
+    "UpdateCheckResult",
+    "UpgradePlanStep",
+    "UpgradePlanRequest",
+    "UpgradePlanResult",
+]

flare_kernel-0.2.8/src/flare_kernel/contracts/auth_contract.py

@@ -0,0 +1,57 @@
+"""Authorization capability contracts."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class AuthPrincipal(BaseModel):
+    provider: str
+    external_subject: str
+    user_id: str | None = None
+    tenant_id: str = "default"
+    instance_id: str = "default"
+    display_name: str | None = None
+
+
+class AuthContext(BaseModel):
+    contract_version: str = "auth.context.v0"
+    principal: AuthPrincipal
+    project_id: str | None = None
+    session_id: str | None = None
+    scopes: list[str] = Field(default_factory=list)
+    claims: dict[str, Any] = Field(default_factory=dict)
+
+
+class AuthorizationDecision(BaseModel):
+    contract_version: str = "auth.decision.v0"
+    allowed: bool
+    reason: str
+    reason_codes: list[str] = Field(default_factory=list)
+    allowed_scopes: list[str] = Field(default_factory=list)
+    denied_scopes: list[str] = Field(default_factory=list)
+    required_context_fields: list[str] = Field(default_factory=list)
+
+
+class AuthExchangeRequest(BaseModel):
+    provider: str
+    external_subject: str
+    user_id: str | None = None
+    tenant_id: str = "default"
+    instance_id: str = "default"
+    project_id: str | None = None
+    session_id: str | None = None
+    scopes: list[str] = Field(default_factory=list)
+    claims: dict[str, Any] = Field(default_factory=dict)
+    display_name: str | None = None
+
+
+class AuthExchangeResponse(BaseModel):
+    contract_version: str = "auth.exchange.v0"
+    auth_context: AuthContext
+    authorization: AuthorizationDecision
+    access_token: str | None = None
+    token_type: Literal["none", "bearer"] = "none"
+    token_status: Literal["not_issued", "external_required"] = "not_issued"

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

@@ -0,0 +1,95 @@
+"""Canonical context contract for kernel orchestration.
+
+DOC HELPER — OBJ-09/SRC-06 context schema boundary.
+This contract is the canonical shape for session-scoped context. Runtime layers
+may append patches, but fields must be declared here before they can survive
+validation and become reusable backend state.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ContextEvidenceItem(BaseModel):
+    id: 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):
+    id: str = ""
+    round: int = 0
+    retrieval_run_id: str = ""
+    query: str = ""
+    sourcing_task_kind: str = ""
+    source_scope: str = ""
+    requested_top_k: int = 0
+    returned_count: int = 0
+    new_count: int = 0
+    has_more: bool = False
+    next_top_k: int = 0
+    source_breakdown: dict[str, int] = Field(default_factory=dict)
+    selected_source: str = ""
+    source_priority: list[dict[str, Any]] = Field(default_factory=list)
+    fallbacks: list[str] = Field(default_factory=list)
+    provider_health: list[dict[str, Any]] = Field(default_factory=list)
+    provider_trace: list[dict[str, Any]] = Field(default_factory=list)
+    items: list[dict[str, Any]] = Field(default_factory=list)
+    shortlist: 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 = ""
+    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)
+    archive_summary: dict[str, Any] = Field(default_factory=dict)
+    updated_at: str = ""
+
+
+def create_empty_context() -> ContextContract:
+    return ContextContract()