flare-kernel 1.0.2__tar.gz → 1.0.4__tar.gz

flare_kernel-1.0.4/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: flare-kernel
+Version: 1.0.4
+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.4/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.4"
+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.4/src/flare_kernel/contracts/__init__.py

@@ -0,0 +1,218 @@
+"""Kernel contracts."""
+
+from flare_kernel.contracts.context import (
+    ContextAnalysisResult,
+    ContextClaimItem,
+    ContextContract,
+    ContextEvidenceItem,
+    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.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 (
+    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 (
+    RunCancellationRequest,
+    RunConfirmationDecisionRequest,
+    RunConfirmationDecisionResponse,
+    RunEventListResponse,
+    RunEventRecord,
+    RunFailureRequest,
+    RunInterruptRecord,
+    RunListResponse,
+    RunRecord,
+    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",
+    "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",
+    "ContextSourcingResult",
+    "ContextTurnItem",
+    "ContextWriteDeclaration",
+    "ContextWriteRegistry",
+    "context_contract_field_names",
+    "create_empty_context",
+    "Mode",
+    "ModeHandler",
+    "mode_handlers",
+    "run_mode",
+    "ProjectRecord",
+    "ProjectUpsertRequest",
+    "ProjectsResponse",
+    "ProjectMemoryCandidate",
+    "ProjectMemoryPromotionDecision",
+    "ProjectMemoryPromotionCandidate",
+    "ProjectMemoryPromotionReview",
+    "ProjectMemoryRecord",
+    "ProjectMemoryRecall",
+    "ProjectMemoryVersion",
+    "RunRecord",
+    "RunCancellationRequest",
+    "RunConfirmationDecisionRequest",
+    "RunConfirmationDecisionResponse",
+    "RunEventRecord",
+    "RunFailureRequest",
+    "RunInterruptRecord",
+    "RunListResponse",
+    "RunEventListResponse",
+    "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.0.4/src/flare_kernel/contracts/code_proposal_contract.py

@@ -0,0 +1,150 @@
+"""Schema-grounded code proposal contracts."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+ApplicationMode = Literal["proposal_only"]
+DiffOperation = Literal["create", "modify", "delete", "rename"]
+SchemaRefKind = Literal["contract", "schema", "migration", "test", "runtime_policy", "other"]
+
+_BANNED_RAW_KEYS = frozenset(
+    {
+        "raw_provider_payload",
+        "provider_payload",
+        "provider_response",
+        "raw_completion",
+        "choices",
+    }
+)
+
+
+def _clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split()).strip()
+
+
+def _contains_banned_raw_payload(value: Any) -> bool:
+    if isinstance(value, dict):
+        return any(key in _BANNED_RAW_KEYS for key in value) or any(
+            _contains_banned_raw_payload(item) for item in value.values()
+        )
+    if isinstance(value, list):
+        return any(_contains_banned_raw_payload(item) for item in value)
+    return False
+
+
+class _StrictContract(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SchemaReference(_StrictContract):
+    ref: str
+    kind: SchemaRefKind = "contract"
+    description: str = ""
+
+    @field_validator("ref")
+    @classmethod
+    def require_ref(cls, value: str) -> str:
+        text = _clean_text(value)
+        if not text:
+            raise ValueError("schema ref is required")
+        return text
+
+
+class ProposedFileDiff(_StrictContract):
+    target_file: str
+    operation: DiffOperation
+    diff: str
+    rationale: str
+    schema_refs: list[SchemaReference] = Field(default_factory=list)
+    assumptions: list[str] = Field(default_factory=list)
+    validation_notes: list[str] = Field(default_factory=list)
+
+    @field_validator("target_file", "diff", "rationale")
+    @classmethod
+    def require_text(cls, value: str) -> str:
+        text = _clean_text(value)
+        if not text:
+            raise ValueError("target_file, diff, and rationale are required")
+        return text
+
+    @field_validator("assumptions", "validation_notes")
+    @classmethod
+    def normalize_text_list(cls, value: list[str]) -> list[str]:
+        return [text for item in value if (text := _clean_text(item))]
+
+    @model_validator(mode="after")
+    def require_schema_refs(self) -> "ProposedFileDiff":
+        if not self.schema_refs:
+            raise ValueError("schema_refs are required for each proposed diff")
+        return self
+
+
+class CodeProposal(_StrictContract):
+    contract_version: str = "flare.code_proposal.v1"
+    proposal_id: str
+    application_mode: ApplicationMode = "proposal_only"
+    target_files: list[str]
+    proposed_diffs: list[ProposedFileDiff]
+    rationale: str
+    schema_refs: list[SchemaReference]
+    assumptions: list[str]
+    required_tests: list[str]
+    migration_notes: list[str]
+    rollback_notes: list[str]
+    validation_metadata: dict[str, Any] = Field(default_factory=dict)
+    provider_trace_ref: str = ""
+
+    @field_validator("proposal_id", "rationale")
+    @classmethod
+    def require_text(cls, value: str) -> str:
+        text = _clean_text(value)
+        if not text:
+            raise ValueError("proposal_id and rationale are required")
+        return text
+
+    @field_validator(
+        "target_files",
+        "assumptions",
+        "required_tests",
+        "migration_notes",
+        "rollback_notes",
+    )
+    @classmethod
+    def require_text_list(cls, value: list[str]) -> list[str]:
+        normalized = [text for item in value if (text := _clean_text(item))]
+        if not normalized:
+            raise ValueError("non-empty text list required")
+        return normalized
+
+    @field_validator("validation_metadata")
+    @classmethod
+    def forbid_raw_provider_metadata(cls, value: dict[str, Any]) -> dict[str, Any]:
+        if _contains_banned_raw_payload(value):
+            raise ValueError("raw provider payload is not allowed in code proposal metadata")
+        return dict(value)
+
+    @model_validator(mode="after")
+    def validate_reviewable_proposal(self) -> "CodeProposal":
+        if not self.proposed_diffs:
+            raise ValueError("proposed_diffs are required")
+        if not self.schema_refs:
+            raise ValueError("schema_refs are required")
+        diff_targets = {item.target_file for item in self.proposed_diffs}
+        missing_targets = [target for target in self.target_files if target not in diff_targets]
+        if missing_targets:
+            raise ValueError("every target_file must have a proposed diff")
+        return self
+
+
+__all__ = [
+    "ApplicationMode",
+    "CodeProposal",
+    "DiffOperation",
+    "ProposedFileDiff",
+    "SchemaReference",
+    "SchemaRefKind",
+]