flare-kernel 0.2.14__tar.gz → 1.0.0__tar.gz

flare_kernel-1.0.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: flare-kernel
+Version: 1.0.0
+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<2.0.0,>=1.0.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: rapidfuzz<4.0,>=3.14
+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` 显式指定
+   - 本地仓库运行时可回退到仓库根目录下的 `domain-packs/`
+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. `APIPRO_API_KEY`（必填，真实 APIPro 调用）
+2. `LLM_PROVIDER_BACKEND`（当前本地模板为 `apipro`）
+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-1.0.0/README.md

@@ -0,0 +1,83 @@
+# 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` 显式指定
+   - 本地仓库运行时可回退到仓库根目录下的 `domain-packs/`
+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. `APIPRO_API_KEY`（必填，真实 APIPro 调用）
+2. `LLM_PROVIDER_BACKEND`（当前本地模板为 `apipro`）
+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-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flare-kernel"
+version = "1.0.0"
+description = "FLARE kernel runtime package"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "flare-engines>=1.0.0,<2.0.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",
+    "rapidfuzz>=3.14,<4.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-1.0.0/src/flare_kernel/contracts/__init__.py

@@ -0,0 +1,188 @@
+"""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.artifact_document import (
+    ArtifactDocument,
+    ArtifactFieldSuggestion,
+    ArtifactSection,
+    FieldPackSuggestion,
+    ProcurementPackage,
+)
+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.node_result import (
+    ConfirmedField,
+    FieldCandidate,
+    NodeKind,
+    NodeResult,
+    NodeStatus,
+    NormalizedQuestion,
+    NormalizedResult,
+)
+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,
+    ProjectMemoryPromotionDecision,
+    ProjectMemoryPromotionCandidate,
+    ProjectMemoryPromotionReview,
+    ProjectMemoryRecall,
+    ProjectMemoryRecord,
+    ProjectMemoryVersion,
+)
+from flare_kernel.contracts.run_contract import (
+    RunEventListResponse,
+    RunEventRecord,
+    RunInterruptRecord,
+    RunListResponse,
+    RunRecord,
+    WAITING_RUN_STATUSES,
+)
+from flare_kernel.contracts.source_image_understanding import (
+    IMAGE_UNDERSTANDING_SCHEMA_VERSION,
+    ImageUnderstandingUiElement,
+    SourceImageUnderstandingResult,
+)
+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",
+    "ArtifactDocument",
+    "ArtifactFieldSuggestion",
+    "ArtifactSection",
+    "FieldPackSuggestion",
+    "ProcurementPackage",
+    "AnalysisRouteDecision",
+    "HealthResponse",
+    "IntentSuggestResponse",
+    "ProjectSourceRecord",
+    "ProjectSourceUploadResponse",
+    "ProjectSourcesResponse",
+    "DeleteProjectSourceResponse",
+    "KnowledgeIngestRequest",
+    "KnowledgeIngestResponse",
+    "KnowledgeSearchRequest",
+    "KnowledgeSearchResponse",
+    "SourcingSearchRequest",
+    "SourcingSearchResponse",
+    "ConfirmedField",
+    "FieldCandidate",
+    "NodeKind",
+    "NodeResult",
+    "NodeStatus",
+    "NormalizedQuestion",
+    "NormalizedResult",
+    "ListEventRecord",
+    "ListEventResource",
+    "ContextContract",
+    "ContextClaimItem",
+    "ContextAnalysisResult",
+    "ContextEvidenceItem",
+    "ContextSourcingResult",
+    "ContextTurnItem",
+    "create_empty_context",
+    "Mode",
+    "ModeHandler",
+    "mode_handlers",
+    "run_mode",
+    "ProjectRecord",
+    "ProjectUpsertRequest",
+    "ProjectsResponse",
+    "ProjectMemoryCandidate",
+    "ProjectMemoryPromotionDecision",
+    "ProjectMemoryPromotionCandidate",
+    "ProjectMemoryPromotionReview",
+    "ProjectMemoryRecord",
+    "ProjectMemoryRecall",
+    "ProjectMemoryVersion",
+    "RunRecord",
+    "RunEventRecord",
+    "RunInterruptRecord",
+    "RunListResponse",
+    "RunEventListResponse",
+    "WAITING_RUN_STATUSES",
+    "IMAGE_UNDERSTANDING_SCHEMA_VERSION",
+    "ImageUnderstandingUiElement",
+    "SourceImageUnderstandingResult",
+    "SessionRecord",
+    "SessionCreateRequest",
+    "SessionUpdateRequest",
+    "SessionLifecycleRequest",
+    "SessionListResponse",
+    "SessionMessageRecord",
+    "SessionMessageListResponse",
+    "SessionReplayTurn",
+    "SessionReplayResponse",
+    "SessionAppendExchangeRequest",
+    "VersionConstraint",
+    "ReleaseManifestEntry",
+    "UpdateCheckRequest",
+    "UpdateCheckResult",
+    "UpgradePlanStep",
+    "UpgradePlanRequest",
+    "UpgradePlanResult",
+]

flare_kernel-1.0.0/src/flare_kernel/contracts/artifact_document.py

@@ -0,0 +1,85 @@
+"""Editable ArtifactDocument contracts.
+
+ArtifactDocument is the shared backend shape used by Canvas and chat-message
+attachments.  It intentionally avoids versioned route/path naming; evolution is
+handled by explicit fields and compatibility tests.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactSection(BaseModel):
+    key: str
+    label: str = ""
+    status: str = ""
+
+
+class ArtifactFieldSuggestion(BaseModel):
+    field_key: str
+    label: str = ""
+    value: Any = None
+    confidence: float | None = None
+    state: str = "candidate"
+    source_kind: str = ""
+    source_ref: str = ""
+    reason: str = ""
+    needs_confirmation: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class FieldPackSuggestion(BaseModel):
+    field_pack_id: str
+    label: str = ""
+    target_package_id: str = ""
+    source_kind: str = ""
+    source_ref: str = ""
+    confidence: float | None = None
+    fields: list[ArtifactFieldSuggestion] = Field(default_factory=list)
+    apply_action: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProcurementPackage(BaseModel):
+    package_id: str
+    title: str = ""
+    goal: str = ""
+    scope: str = ""
+    category_candidates: list[Any] = Field(default_factory=list)
+    budget_candidates: list[Any] = Field(default_factory=list)
+    quantity_candidates: list[Any] = Field(default_factory=list)
+    dependencies: list[Any] = Field(default_factory=list)
+    open_questions: list[Any] = Field(default_factory=list)
+    next_actions: list[dict[str, Any]] = Field(default_factory=list)
+    field_pack_suggestions: list[FieldPackSuggestion] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ArtifactDocument(BaseModel):
+    artifact_id: str
+    kind: str = "ArtifactDocument"
+    artifact_type: str = ""
+    title: str = ""
+    content: str = ""
+    content_format: str = "markdown"
+    source: str = ""
+    status: str = ""
+    template_key: str = ""
+    latest_revision: dict[str, Any] = Field(default_factory=dict)
+    sections: list[ArtifactSection] = Field(default_factory=list)
+    procurement_packages: list[ProcurementPackage] = Field(default_factory=list)
+    field_pack_suggestions: list[FieldPackSuggestion] = Field(default_factory=list)
+    actions: list[dict[str, Any]] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+__all__ = [
+    "ArtifactDocument",
+    "ArtifactFieldSuggestion",
+    "ArtifactSection",
+    "FieldPackSuggestion",
+    "ProcurementPackage",
+]

flare_kernel-1.0.0/src/flare_kernel/contracts/node_result.py

@@ -0,0 +1,113 @@
+"""Generic node result contracts."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+NodeKind = Literal["llm", "structured_reasoning", "capability", "policy", "workflow"]
+NodeStatus = Literal["succeeded", "partial", "blocked", "failed", "skipped"]
+
+
+def _clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split()).strip()
+
+
+class FieldCandidate(BaseModel):
+    value: Any
+    confidence: float | None = None
+    state: Literal["candidate"] = "candidate"
+    source: str = ""
+    reason: str = ""
+    needs_confirmation: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ConfirmedField(BaseModel):
+    value: Any
+    source: str = ""
+    evidence: str = ""
+    confidence: float | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class NormalizedQuestion(BaseModel):
+    question_key: str
+    question_text: str
+    target_field_keys: list[str] = Field(default_factory=list)
+    blocking: bool = False
+    priority: int = 1
+    expected_answer_type: str = ""
+    options: list[dict[str, Any]] = Field(default_factory=list)
+    rationale: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("question_key", "question_text")
+    @classmethod
+    def require_text(cls, value: str) -> str:
+        text = _clean_text(value)
+        if not text:
+            raise ValueError("question_key and question_text are required")
+        return text
+
+
+class NodeResult(BaseModel):
+    contract_version: str = "flare.node_result.v1"
+    node_key: str
+    node_kind: NodeKind
+    status: NodeStatus
+    summary: str = ""
+    content: str = ""
+    candidate_fields: dict[str, FieldCandidate] = Field(default_factory=dict)
+    confirmed_fields: dict[str, ConfirmedField] = Field(default_factory=dict)
+    questions: list[NormalizedQuestion] = Field(default_factory=list)
+    next_actions: list[dict[str, Any]] = Field(default_factory=list)
+    events: list[dict[str, Any]] = Field(default_factory=list)
+    patches: list[dict[str, Any]] = Field(default_factory=list)
+    quality: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("node_key")
+    @classmethod
+    def require_node_key(cls, value: str) -> str:
+        text = _clean_text(value)
+        if not text:
+            raise ValueError("node_key is required")
+        return text
+
+
+class NormalizedResult(BaseModel):
+    contract_version: str = "flare.normalized_result.v1"
+    status: NodeStatus
+    results: list[NodeResult] = Field(default_factory=list)
+    candidate_fields: dict[str, FieldCandidate] = Field(default_factory=dict)
+    confirmed_fields: dict[str, ConfirmedField] = Field(default_factory=dict)
+    questions: list[NormalizedQuestion] = Field(default_factory=list)
+    next_actions: list[dict[str, Any]] = Field(default_factory=list)
+    events: list[dict[str, Any]] = Field(default_factory=list)
+    patches: list[dict[str, Any]] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def aggregate_node_outputs(self) -> "NormalizedResult":
+        for result in self.results:
+            self.candidate_fields.update(result.candidate_fields)
+            self.confirmed_fields.update(result.confirmed_fields)
+            self.questions.extend(result.questions)
+            self.next_actions.extend(result.next_actions)
+            self.events.extend(result.events)
+            self.patches.extend(result.patches)
+        return self
+
+
+__all__ = [
+    "ConfirmedField",
+    "FieldCandidate",
+    "NodeKind",
+    "NodeResult",
+    "NodeStatus",
+    "NormalizedQuestion",
+    "NormalizedResult",
+]

flare_kernel-1.0.0/src/flare_kernel/contracts/run_contract.py

@@ -0,0 +1,55 @@
+"""Run state and event replay contracts."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+RunState = Literal["queued", "running", "waiting_for_user", "completed", "failed", "cancelled"]
+RunInterruptStatus = Literal["pending", "answered", "cancelled"]
+WAITING_RUN_STATUSES = frozenset({"waiting_user", "waiting_for_user", "paused", "interrupted"})
+
+
+class RunRecord(BaseModel):
+    run_id: str
+    session_id: str
+    request_id: str = ""
+    trace_id: str = ""
+    state: RunState = "queued"
+    error: str = ""
+    created_at: str
+    started_at: str = ""
+    completed_at: str = ""
+    updated_at: str
+
+
+class RunEventRecord(BaseModel):
+    event_id: str
+    run_id: str
+    session_id: str
+    request_id: str = ""
+    event_name: str
+    sequence: int
+    payload: dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+
+
+class RunInterruptRecord(BaseModel):
+    interrupt_id: str
+    run_id: str
+    session_id: str
+    request_id: str = ""
+    status: RunInterruptStatus = "pending"
+    reason: str = ""
+    question: dict[str, Any] = Field(default_factory=dict)
+    resume_hint: dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+
+
+class RunListResponse(BaseModel):
+    runs: list[RunRecord] = Field(default_factory=list)
+
+
+class RunEventListResponse(BaseModel):
+    events: list[RunEventRecord] = Field(default_factory=list)