flare-kernel 1.1.0__tar.gz → 1.1.2__tar.gz

flare_kernel-1.1.2/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: flare-kernel
+Version: 1.1.2
+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<0.136,>=0.115
+Requires-Dist: python-multipart<1.0,>=0.0.9
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pypdf<6,>=4
+Requires-Dist: pillow<12,>=10
+Requires-Dist: pytesseract<1.0,>=0.3.10
+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
+Provides-Extra: ocr
+Requires-Dist: rapidocr-onnxruntime<1.3,>=1.2; extra == "ocr"
+
+# 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.1.2/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flare-kernel"
+version = "1.1.2"
+description = "FLARE kernel runtime package"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "flare-engines>=1.0.0,<2.0.0",
+    "fastapi>=0.115,<0.136",
+    "python-multipart>=0.0.9,<1.0",
+    "pydantic>=2,<3",
+    "pypdf>=4,<6",
+    "pillow>=10,<12",
+    "pytesseract>=0.3.10,<1.0",
+    "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",
+]
+
+[project.optional-dependencies]
+ocr = [
+    "rapidocr-onnxruntime>=1.2,<1.3",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

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

@@ -0,0 +1,248 @@
+"""Kernel contracts."""
+
+from flare_kernel.contracts.context import (
+    ContextAnalysisResult,
+    ContextClaimItem,
+    ContextContract,
+    ContextEvidenceItem,
+    ContextRetentionPolicy,
+    ContextSourcingResult,
+    ContextTurnItem,
+    ContextWriteDeclaration,
+    ContextWriteRegistry,
+    context_contract_field_names,
+    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,
+    ArtifactUpkeepStatus,
+    FieldPackSuggestion,
+    ProcurementPackage,
+)
+from flare_kernel.contracts.baseline_knowledge_governance import (
+    BaselineKnowledgeCandidate,
+    BaselineKnowledgeDecision,
+)
+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.llm_node_taxonomy import (
+    LLMNodeAdmissionRule,
+    LLMNodeRoleKey,
+    LLM_NODE_ADMISSION_RULES,
+    get_llm_node_admission_rule,
+    list_llm_node_admission_rules,
+)
+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 (
+    ProjectListWindow,
+    ProjectRecord,
+    ProjectsResponse,
+    ProjectUpsertRequest,
+)
+from flare_kernel.contracts.project_memory_contract import (
+    ProjectMemoryCandidate,
+    ProjectMemoryPromotionDecision,
+    ProjectMemoryPromotionCandidate,
+    ProjectMemoryPromotionReview,
+    ProjectMemoryRecall,
+    ProjectMemoryRecord,
+    ProjectMemoryVersion,
+)
+from flare_kernel.contracts.result_reuse import (
+    ResultReuseDecision,
+    ResultReuseEntry,
+    ResultReuseKey,
+)
+from flare_kernel.contracts.shared_reuse_governance import (
+    SharedReusePromotionCandidate,
+    SharedReusePromotionDecision,
+)
+from flare_kernel.contracts.run_contract import (
+    RunCancellationRequest,
+    RunConfirmationDecisionRequest,
+    RunConfirmationDecisionResponse,
+    RunEventListResponse,
+    RunEventRecord,
+    RunEventRecorderDiagnosticsResponse,
+    RunFailureRequest,
+    RunInterruptRecord,
+    RunListResponse,
+    RunRecord,
+    RunRuntimeOperationRequest,
+    RunRuntimeOperationResponse,
+    RunSettlementResponse,
+    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",
+    "ArtifactUpkeepStatus",
+    "FieldPackSuggestion",
+    "ProcurementPackage",
+    "BaselineKnowledgeCandidate",
+    "BaselineKnowledgeDecision",
+    "AnalysisRouteDecision",
+    "HealthResponse",
+    "IntentSuggestResponse",
+    "ProjectSourceRecord",
+    "ProjectSourceUploadResponse",
+    "ProjectSourcesResponse",
+    "DeleteProjectSourceResponse",
+    "KnowledgeIngestRequest",
+    "KnowledgeIngestResponse",
+    "KnowledgeSearchRequest",
+    "KnowledgeSearchResponse",
+    "SourcingSearchRequest",
+    "SourcingSearchResponse",
+    "ConfirmedField",
+    "FieldCandidate",
+    "NodeKind",
+    "NodeResult",
+    "NodeStatus",
+    "NormalizedQuestion",
+    "NormalizedResult",
+    "LLMNodeAdmissionRule",
+    "LLMNodeRoleKey",
+    "LLM_NODE_ADMISSION_RULES",
+    "get_llm_node_admission_rule",
+    "list_llm_node_admission_rules",
+    "ListEventRecord",
+    "ListEventResource",
+    "ContextContract",
+    "ContextClaimItem",
+    "ContextAnalysisResult",
+    "ContextEvidenceItem",
+    "ContextRetentionPolicy",
+    "ContextSourcingResult",
+    "ContextTurnItem",
+    "ContextWriteDeclaration",
+    "ContextWriteRegistry",
+    "context_contract_field_names",
+    "create_empty_context",
+    "Mode",
+    "ModeHandler",
+    "mode_handlers",
+    "run_mode",
+    "ProjectListWindow",
+    "ProjectRecord",
+    "ProjectUpsertRequest",
+    "ProjectsResponse",
+    "ProjectMemoryCandidate",
+    "ProjectMemoryPromotionDecision",
+    "ProjectMemoryPromotionCandidate",
+    "ProjectMemoryPromotionReview",
+    "ProjectMemoryRecord",
+    "ProjectMemoryRecall",
+    "ProjectMemoryVersion",
+    "ResultReuseDecision",
+    "ResultReuseEntry",
+    "ResultReuseKey",
+    "SharedReusePromotionCandidate",
+    "SharedReusePromotionDecision",
+    "RunRecord",
+    "RunCancellationRequest",
+    "RunConfirmationDecisionRequest",
+    "RunConfirmationDecisionResponse",
+    "RunEventRecord",
+    "RunEventRecorderDiagnosticsResponse",
+    "RunFailureRequest",
+    "RunInterruptRecord",
+    "RunListResponse",
+    "RunEventListResponse",
+    "RunRuntimeOperationRequest",
+    "RunRuntimeOperationResponse",
+    "RunSettlementResponse",
+    "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.1.2/src/flare_kernel/contracts/artifact_version.py

@@ -0,0 +1,242 @@
+"""Immutable project artifact version contract."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+from typing import Any
+
+from flare_kernel.contracts.object_store import (
+    ObjectPutRequest,
+    ObjectScope,
+    StoredObjectRef,
+)
+
+
+_MAX_REFERENCE_BYTES = 256
+_DIGEST_PATTERN = re.compile(r"^sha256:[0-9a-f]{64}$")
+_LINEAGE_FIELDS = frozenset(
+    {
+        "resource_kind",
+        "resource_id",
+        "resource_version_id",
+        "relation",
+        "content_digest",
+    }
+)
+_ENVELOPE_FIELDS = frozenset(
+    {
+        "artifact_id",
+        "artifact_version_id",
+        "artifact_type",
+        "scope",
+        "status",
+        "artifact_schema",
+        "schema_version",
+        "content_digest",
+        "manifest_ref",
+        "object_refs",
+        "lineage",
+    }
+)
+
+
+def _utf8_size(value: str, *, field: str) -> int:
+    try:
+        return len(value.encode("utf-8"))
+    except UnicodeEncodeError as exc:
+        raise ValueError(f"{field} must be valid UTF-8") from exc
+
+
+def _validate_reference(value: Any, *, field: str) -> None:
+    if type(value) is not str:
+        raise TypeError(f"{field} must be a string")
+    size = _utf8_size(value, field=field)
+    has_disallowed = any(
+        char.isspace() or unicodedata.category(char) in {"Cc", "Cf"} for char in value
+    )
+    if not value or size > _MAX_REFERENCE_BYTES or has_disallowed:
+        raise ValueError(f"{field} must be a bounded canonical reference")
+
+
+def _validate_digest(value: Any) -> None:
+    if type(value) is not str or _DIGEST_PATTERN.fullmatch(value) is None:
+        raise ValueError("content_digest must be canonical lowercase SHA-256")
+
+
+def _strict_mapping(
+    raw: Any, *, expected: frozenset[str], contract: str
+) -> dict[Any, Any]:
+    if type(raw) is not dict:
+        raise TypeError(f"{contract} payload must be an object")
+    if set(raw) != expected:
+        raise ValueError(f"{contract} fields do not match")
+    return raw
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactLineageRef:
+    resource_kind: str
+    resource_id: str
+    resource_version_id: str
+    relation: str
+    content_digest: str
+
+    def __post_init__(self) -> None:
+        _validate_reference(self.resource_kind, field="resource_kind")
+        _validate_reference(self.resource_id, field="resource_id")
+        _validate_reference(self.resource_version_id, field="resource_version_id")
+        _validate_reference(self.relation, field="relation")
+        _validate_digest(self.content_digest)
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "resource_kind": self.resource_kind,
+            "resource_id": self.resource_id,
+            "resource_version_id": self.resource_version_id,
+            "relation": self.relation,
+            "content_digest": self.content_digest,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> ArtifactLineageRef:
+        data = _strict_mapping(
+            raw, expected=_LINEAGE_FIELDS, contract="artifact lineage"
+        )
+        return cls(
+            resource_kind=data["resource_kind"],
+            resource_id=data["resource_id"],
+            resource_version_id=data["resource_version_id"],
+            relation=data["relation"],
+            content_digest=data["content_digest"],
+        )
+
+
+def _lineage_key(ref: ArtifactLineageRef) -> tuple[str, str, str, str, str]:
+    return (
+        ref.resource_kind,
+        ref.resource_id,
+        ref.resource_version_id,
+        ref.relation,
+        ref.content_digest,
+    )
+
+
+def _normalize_object_refs(
+    refs: Any, *, scope: ObjectScope, manifest_ref: StoredObjectRef
+) -> tuple[StoredObjectRef, ...]:
+    if type(refs) is not tuple:
+        raise TypeError("object_refs must be a tuple")
+    keys: set[str] = set()
+    for ref in refs:
+        if type(ref) is not StoredObjectRef:
+            raise TypeError("object_refs must contain StoredObjectRef values")
+        if ref.scope != scope:
+            raise ValueError("object_ref scope does not match artifact version")
+        if ref.object_key == manifest_ref.object_key:
+            raise ValueError("manifest_ref must not be repeated in object_refs")
+        if ref.object_key in keys:
+            raise ValueError("object_refs must have unique object keys")
+        keys.add(ref.object_key)
+    return tuple(sorted(refs, key=lambda ref: ref.object_key))
+
+
+def _normalize_lineage(refs: Any) -> tuple[ArtifactLineageRef, ...]:
+    if type(refs) is not tuple:
+        raise TypeError("lineage must be a tuple")
+    keys: set[tuple[str, str, str, str, str]] = set()
+    for ref in refs:
+        if type(ref) is not ArtifactLineageRef:
+            raise TypeError("lineage must contain ArtifactLineageRef values")
+        key = _lineage_key(ref)
+        if key in keys:
+            raise ValueError("lineage references must be unique")
+        keys.add(key)
+    return tuple(sorted(refs, key=_lineage_key))
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactVersionEnvelope:
+    artifact_id: str
+    artifact_version_id: str
+    artifact_type: str
+    scope: ObjectScope
+    status: str
+    artifact_schema: str
+    schema_version: int
+    content_digest: str
+    manifest_ref: StoredObjectRef
+    object_refs: tuple[StoredObjectRef, ...]
+    lineage: tuple[ArtifactLineageRef, ...]
+
+    def __post_init__(self) -> None:
+        _validate_reference(self.artifact_id, field="artifact_id")
+        _validate_reference(self.artifact_version_id, field="artifact_version_id")
+        _validate_reference(self.artifact_type, field="artifact_type")
+        _validate_reference(self.status, field="status")
+        _validate_reference(self.artifact_schema, field="artifact_schema")
+        if type(self.schema_version) is not int:
+            raise TypeError("schema_version must be a strict integer")
+        if self.schema_version < 1:
+            raise ValueError("schema_version must be positive")
+        if type(self.manifest_ref) is not StoredObjectRef:
+            raise TypeError("manifest_ref must be a StoredObjectRef")
+        ObjectPutRequest(
+            scope=self.scope,
+            content_digest=self.content_digest,
+            size_bytes=self.manifest_ref.size_bytes,
+        )
+        if self.manifest_ref.scope != self.scope:
+            raise ValueError("manifest_ref scope does not match artifact version")
+        if self.manifest_ref.content_digest != self.content_digest:
+            raise ValueError("manifest_ref digest does not match artifact version")
+        object_refs = _normalize_object_refs(
+            self.object_refs, scope=self.scope, manifest_ref=self.manifest_ref
+        )
+        lineage = _normalize_lineage(self.lineage)
+        object.__setattr__(self, "object_refs", object_refs)
+        object.__setattr__(self, "lineage", lineage)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "artifact_id": self.artifact_id,
+            "artifact_version_id": self.artifact_version_id,
+            "artifact_type": self.artifact_type,
+            "scope": self.scope.to_dict(),
+            "status": self.status,
+            "artifact_schema": self.artifact_schema,
+            "schema_version": self.schema_version,
+            "content_digest": self.content_digest,
+            "manifest_ref": self.manifest_ref.to_dict(),
+            "object_refs": [ref.to_dict() for ref in self.object_refs],
+            "lineage": [ref.to_dict() for ref in self.lineage],
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> ArtifactVersionEnvelope:
+        data = _strict_mapping(
+            raw, expected=_ENVELOPE_FIELDS, contract="artifact version"
+        )
+        if type(data["object_refs"]) is not list:
+            raise TypeError("object_refs payload must be a list")
+        if type(data["lineage"]) is not list:
+            raise TypeError("lineage payload must be a list")
+        return cls(
+            artifact_id=data["artifact_id"],
+            artifact_version_id=data["artifact_version_id"],
+            artifact_type=data["artifact_type"],
+            scope=ObjectScope.from_dict(data["scope"]),
+            status=data["status"],
+            artifact_schema=data["artifact_schema"],
+            schema_version=data["schema_version"],
+            content_digest=data["content_digest"],
+            manifest_ref=StoredObjectRef.from_dict(data["manifest_ref"]),
+            object_refs=tuple(
+                StoredObjectRef.from_dict(ref) for ref in data["object_refs"]
+            ),
+            lineage=tuple(ArtifactLineageRef.from_dict(ref) for ref in data["lineage"]),
+        )
+
+
+__all__ = ["ArtifactLineageRef", "ArtifactVersionEnvelope"]