corespine 0.0.1__py3-none-any.whl

corespine/__init__.py

@@ -0,0 +1,69 @@
+"""corespine —— Spine 家族的【薄】共享核(ADR 0001 D3/D5)。
+
+只装 domain-neutral 的底层原语:缝注册表 / 隐私安全 observability / LLM 缝 /
+env 配置 / 任务队列 / conformance 基座。刻意保持极小,按证据(rule of three)增长——
+绝不放任何 RAG- 或 agent-特定的东西。详见 CLAUDE.md 宪章与 docs/adr/0001。
+"""
+
+from corespine.config.env import env_key, load_from_env
+from corespine.conformance.harness import CaseResult, ConformanceSuite, InvariantPack
+from corespine.errors import ConfigError, CorespineError, SeamError, error_to_dict
+from corespine.llm.provider import (
+    ChatCompletion,
+    Choice,
+    FunctionCall,
+    LLMProvider,
+    MockProvider,
+    ResponseMessage,
+    ToolCall,
+    Usage,
+)
+from corespine.observability.trace import (
+    FORBIDDEN_KEYS,
+    InProcessPrivacyTraceSink,
+    TraceError,
+    TraceEvent,
+    TraceSink,
+)
+from corespine.queue.task_queue import FakeQueue, JobStatus, TaskQueue
+from corespine.seam.registry import Registry, lazy_extra_import
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # seam
+    "Registry",
+    "lazy_extra_import",
+    # observability
+    "TraceSink",
+    "TraceEvent",
+    "TraceError",
+    "InProcessPrivacyTraceSink",
+    "FORBIDDEN_KEYS",
+    # llm(OpenAI chat-completions 规范)
+    "LLMProvider",
+    "MockProvider",
+    "ChatCompletion",
+    "Choice",
+    "ResponseMessage",
+    "ToolCall",
+    "FunctionCall",
+    "Usage",
+    # config
+    "load_from_env",
+    "env_key",
+    # queue
+    "TaskQueue",
+    "JobStatus",
+    "FakeQueue",
+    # conformance
+    "ConformanceSuite",
+    "InvariantPack",
+    "CaseResult",
+    # errors
+    "CorespineError",
+    "error_to_dict",
+    "ConfigError",
+    "SeamError",
+    "__version__",
+]

corespine/config/__init__.py

@@ -0,0 +1 @@
+"""corespine.config —— env 驱动配置基底:PREFIX_* -> frozen dataclass。"""

corespine/config/env.py

@@ -0,0 +1,77 @@
+"""env 驱动配置的基底助手:把 PREFIX_* 环境变量读进一个 frozen dataclass。
+
+范式同 ragspine `ServiceConfig.from_env`——集中、声明式、可注入(测试传入自己的
+env mapping,不碰进程环境)。但本助手是 domain-neutral 的:不预设任何具体字段,
+只提供机制——"按字段名从 PREFIX_<FIELD> 读取 + 按注解类型转换 + 缺失用 dataclass
+默认值"。app 声明自己的 frozen dataclass,调一次 load_from_env 即可。
+
+支持的字段类型:str / int / float / bool(及其 `X | None` 可选形式)。bool 解析为
+{1,true,yes,on} 为真、{0,false,no,off,""} 为假(均大小写不敏感)。未声明默认值
+的字段若缺对应 env,则抛 ValueError(把缺失的 env 名报清楚)。
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import types
+from collections.abc import Mapping
+from typing import TypeVar, Union, get_args, get_origin, get_type_hints
+
+T = TypeVar("T")
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+_FALSE = frozenset({"0", "false", "no", "off", ""})
+
+
+def env_key(prefix: str, field_name: str) -> str:
+    """字段名 -> 环境变量名:PREFIX_FIELDNAME(字段名大写,前缀以下划线相连)。"""
+    return f"{prefix.rstrip('_')}_{field_name.upper()}"
+
+
+def _unwrap_optional(tp: object) -> object:
+    """`X | None` / Optional[X] -> X;其余原样返回。"""
+    origin = get_origin(tp)
+    if origin is Union or origin is types.UnionType:
+        non_none = [a for a in get_args(tp) if a is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0]
+    return tp
+
+
+def _coerce(raw: str, tp: object) -> object:
+    """按目标类型把 env 字符串转成值;str / 未知类型原样。"""
+    base = _unwrap_optional(tp)
+    if base is bool:
+        low = raw.strip().lower()
+        if low in _TRUE:
+            return True
+        if low in _FALSE:
+            return False
+        raise ValueError(f"无法把 {raw!r} 解析为 bool")
+    if base is int:
+        return int(raw)
+    if base is float:
+        return float(raw)
+    return raw
+
+
+def load_from_env(cls: type[T], *, prefix: str, env: Mapping[str, str] | None = None) -> T:
+    """按 dataclass 字段从 PREFIX_* 读取并构造实例(缺失则用字段默认值)。
+
+    env 可注入(默认读 os.environ);get_type_hints 解析注解,故 `from __future__
+    import annotations` 下的字符串注解也能正确取到真实类型。
+    """
+    if not dataclasses.is_dataclass(cls):
+        raise TypeError(f"{cls!r} 不是 dataclass")
+    source = os.environ if env is None else env
+    hints = get_type_hints(cls)
+    kwargs: dict[str, object] = {}
+    for f in dataclasses.fields(cls):
+        key = env_key(prefix, f.name)
+        if key in source:
+            kwargs[f.name] = _coerce(source[key], hints.get(f.name, f.type))
+        elif f.default is dataclasses.MISSING and f.default_factory is dataclasses.MISSING:
+            raise ValueError(f"缺少必填配置 {key}(字段 {f.name!r} 无默认值)")
+        # 否则:留空,交给 dataclass 自身的默认值。
+    return cls(**kwargs)

corespine/conformance/__init__.py

@@ -0,0 +1 @@
+"""corespine.conformance —— 可复用 conformance 基座(机制,不含具体不变量)。"""

corespine/conformance/harness.py

@@ -0,0 +1,123 @@
+"""可复用的 conformance 基座(机制,不含任何具体不变量)。
+
+一个 Protocol -> 一套共享测试:把"每个实现都必须跑同一套不变量"做成可参数化的机制。
+给定 (1) 一份实现注册表(名字 -> 工厂)与 (2) 一个不变量包(名字 -> 检查函数),
+ConformanceSuite 把二者【绑成笛卡尔积】,逐 (实现 × 不变量) 执行,任一失败即定位到
+具体格子。
+
+这正是 ragspine tests/conformance 的泛化:让"敢放手让第三方填广度、却让脊柱不变量
+烂不掉"成立——没过 conformance 的 adapter 直接 CI 红,而非生产事故。
+
+【机制,非保证】:本模块【不】定义任何具体不变量。anti-fabrication / provenance /
+isolation 这些是各 app 自己的事(ADR 0001 D6),由 app 把自己的 InvariantPack 喂进来;
+harness 只负责"跑全套 + 报告哪个格子坏了"。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import partial
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+# 一个不变量检查:拿到一个【新构造的实现实例】,验证通过则正常返回、违反则抛异常。
+# 检查应只读、与实现内部无关(只验外部可观测行为)。
+Invariant = Callable[[T], None]
+
+# 一个工厂:无参构造一个全新实例(每个格子各拿一个,杜绝实现间状态串味)。
+Factory = Callable[[], T]
+
+
+@dataclass(frozen=True)
+class InvariantPack(Generic[T]):
+    """一组具名不变量。app 用它装自己的保证;harness 只负责跑。
+
+    add() 返回自身,便于链式登记:InvariantPack("x").add(...).add(...)。
+    """
+
+    name: str
+    invariants: dict[str, Invariant[T]] = field(default_factory=dict)
+
+    def add(self, name: str, check: Invariant[T]) -> InvariantPack[T]:
+        self.invariants[name] = check
+        return self
+
+    def names(self) -> list[str]:
+        return list(self.invariants)
+
+
+@dataclass(frozen=True)
+class CaseResult:
+    """单个 (实现 × 不变量) 格子的执行结果。"""
+
+    impl: str
+    invariant: str
+    passed: bool
+    error: str | None = None
+
+
+class ConformanceSuite(Generic[T]):
+    """把 实现注册表 × 不变量包 绑成可执行 / 可参数化的 conformance 套件。"""
+
+    def __init__(self, implementations: dict[str, Factory[T]], pack: InvariantPack[T]) -> None:
+        if not implementations:
+            raise ValueError("conformance 套件至少需要一个实现")
+        self._impls = dict(implementations)
+        self._pack = pack
+
+    def cases(self) -> list[tuple[str, str]]:
+        """全部 (实现名, 不变量名) 组合——可直接喂给 pytest.mark.parametrize。"""
+        return [(impl, inv) for impl in self._impls for inv in self._pack.names()]
+
+    def ids(self) -> list[str]:
+        """与 cases() 对齐的可读用例 id(形如 impl/invariant)。"""
+        return [f"{impl}/{inv}" for impl, inv in self.cases()]
+
+    def parametrize_kwargs(self) -> dict[str, object]:
+        """产出可直接喂给 pytest.mark.parametrize(**...) 的 kwargs(pytest-free)。
+
+        本方法【只返回纯数据】(str / list[Callable] / list[str]),core 不 import
+        pytest——pytest 依赖留在消费者的测试里。返回三键:
+
+        - argnames: 固定为 "case"(单形参,值是一个【已绑定好该格子的零参 thunk】);
+        - argvalues: 每格一个 thunk,调用即跑 check(impl, inv)——满足则静默返回,违反则
+          原样抛出(通常是 AssertionError);
+        - ids: 与 argvalues 对齐的可读用例 id,形如 "impl-inv"。
+
+        这样消费者的整套 glue 收敛成两行,无需手写 cases() 遍历或 fixture(params=...):
+
+            @pytest.mark.parametrize(**suite.parametrize_kwargs())
+            def test_conformance(case):
+                case()
+        """
+        # partial 立即绑定 impl/inv(规避 lambda 闭包晚绑定),且类型明确(mypy --strict 友好)。
+        argvalues: list[Callable[[], None]] = [
+            partial(self.check, impl, inv) for impl, inv in self.cases()
+        ]
+        ids = [f"{impl}-{inv}" for impl, inv in self.cases()]
+        return {"argnames": "case", "argvalues": argvalues, "ids": ids}
+
+    def check(self, impl: str, invariant: str) -> None:
+        """跑单个格子:新建该实现实例,对其执行该不变量(失败则原样抛出)。
+
+        每个格子都【新建实例】,杜绝实现间状态串味——与 ragspine 每用例新空库一致。
+        """
+        instance = self._impls[impl]()
+        self._pack.invariants[invariant](instance)
+
+    def run(self) -> list[CaseResult]:
+        """跑全部格子并收集结果(不抛;用于离线自检 / 报告)。"""
+        results: list[CaseResult] = []
+        for impl, inv in self.cases():
+            try:
+                self.check(impl, inv)
+                results.append(CaseResult(impl, inv, True))
+            except Exception as exc:  # noqa: BLE001 — 收集失败,不中断其余格子
+                results.append(CaseResult(impl, inv, False, f"{type(exc).__name__}: {exc}"))
+        return results
+
+    def passed(self) -> bool:
+        """便捷:全部格子是否通过(离线自检用)。"""
+        return all(result.passed for result in self.run())

corespine/errors.py

@@ -0,0 +1,81 @@
+"""家族统一异常 + 错误归一(domain-neutral 原语)。
+
+证据(rule of three):ragspine 的 `JobError(stage, retryable)` 与 `_error_dict_from_exc`、
+pdfspine 的 `error.kind()` / `LimitKind`——两个消费者都在各自重造"带机器可判别码的异常 +
+把异常拍成可序列化 dict"这同一块稳定面。这里只把【恰好那块】提上来:
+
+- 一个统一基类 `CorespineError`:带稳定、可 grep 的 `code` 与 `retryable` 标志;
+- 一个归一函数 `error_to_dict`:把【任意】异常拍成可被 `json.dumps` 序列化的 dict。
+
+这里是【机制】:基类与归一形状。具体有哪些 code、哪条可重试,由各 app 自己绑
+(ADR 0001 D6)。core 不预设任何业务语义,只给两个自然子类做示范。
+"""
+
+from __future__ import annotations
+
+
+class CorespineError(Exception):
+    """Spine 家族统一异常基类。
+
+    `code` 是稳定、机器可 grep 的判别符(子类覆盖,如 "config.invalid"/"seam.unknown");
+    `retryable` 标记此错是否值得重试。两者都既可在子类作类属性覆盖,也可在构造时实例级覆盖。
+    任意关键字参数收进 `self.context`(普通 dict),用于携带可序列化的诊断上下文。
+    """
+
+    code: str = "error"
+    retryable: bool = False
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: str | None = None,
+        retryable: bool | None = None,
+        **context: object,
+    ) -> None:
+        super().__init__(message)
+        # 仅在显式传入时做实例级覆盖,否则沿用类属性默认。
+        if code is not None:
+            self.code = code
+        if retryable is not None:
+            self.retryable = retryable
+        self.context: dict[str, object] = dict(context)
+
+    def to_dict(self) -> dict[str, object]:
+        """归一为可被 json.dumps 序列化的 dict。"""
+        return {
+            "type": type(self).__name__,
+            "code": self.code,
+            "message": str(self),
+            "retryable": self.retryable,
+            "context": dict(self.context),
+        }
+
+
+def error_to_dict(exc: BaseException) -> dict[str, object]:
+    """把【任意】异常归一为可序列化 dict(统一错误形状)。
+
+    CorespineError 走其 `to_dict()`;其余异常给出同形状的保守默认
+    (code="error"、retryable=False、context={}),便于跨进程/跨缝统一处理与日志。
+    """
+    if isinstance(exc, CorespineError):
+        return exc.to_dict()
+    return {
+        "type": type(exc).__name__,
+        "code": "error",
+        "message": str(exc),
+        "retryable": False,
+        "context": {},
+    }
+
+
+class ConfigError(CorespineError):
+    """配置非法(缺必填、类型不符等)。"""
+
+    code = "config.invalid"
+
+
+class SeamError(CorespineError):
+    """缝相关错误(未知实现、工厂构造失败等)。"""
+
+    code = "seam.unknown"

corespine/llm/__init__.py

@@ -0,0 +1 @@
+"""corespine.llm —— LLM 缝:LLMProvider 协议 + 离线确定性 MockProvider。"""

corespine/llm/provider.py

@@ -0,0 +1,120 @@
+"""LLM 缝:LLMProvider 协议(OpenAI chat-completions 规范)+ 确定性离线 MockProvider。
+
+【对外唯一规范 = OpenAI chat completions 形状】——输入是 OpenAI 风格的 messages(list[dict]:
+role / content / 可带 tool_calls / tool_call_id)与 OpenAI function-tool 形状的 tools;输出是
+OpenAI 形状的 ChatCompletion(choices[].message.{content, tool_calls[].function.{name, arguments}}、
+finish_reason、usage.{prompt_tokens, completion_tokens, total_tokens})。
+
+为什么以 OpenAI 形状作规范:它已是事实标准(LiteLLM / OpenRouter / vLLM / Ollama / Together /
+Groq 等都吐这个),所以"规范化到 OpenAI"= 兼容面最广;用户永远只按 OpenAI 规范写代码。后端是
+Anthropic 或其它非 OpenAI 兼容模型时,由各 app 的适配器【在内部转成 OpenAI 形状再吐出】,用户无感。
+domain-neutral:这是当下 LLM 的通用 wire 形状,不含任何 RAG / agent 特定概念;tool-use 循环仍归 app。
+
+核心 import 本模块零 SDK;真实 provider(Anthropic / OpenAI 等)由各 app 在自己的缝里延迟 import
+接入。MockProvider 是离线确定性默认:同样的 messages 恒定产出同样的响应(纯函数、零网络、零 key),
+让"装上即可端到端跑"成立、测试可复现;它【不】伪造 tool_calls(离线默认不假装会 function-calling)。
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class FunctionCall:
+    """工具调用的函数部分(OpenAI 形状):name + arguments(JSON 字符串,与 OpenAI 完全一致)。"""
+
+    name: str
+    arguments: str = "{}"
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """一次工具调用(OpenAI 形状):id + type + function。"""
+
+    id: str
+    function: FunctionCall
+    type: str = "function"
+
+
+@dataclass(frozen=True)
+class ResponseMessage:
+    """模型返回的消息(OpenAI 形状):role + content(可空)+ tool_calls(可空)。"""
+
+    role: str = "assistant"
+    content: str | None = None
+    tool_calls: tuple[ToolCall, ...] | None = None
+
+
+@dataclass(frozen=True)
+class Choice:
+    """一个候选(OpenAI 形状):index + message + finish_reason(stop / tool_calls / length …)。"""
+
+    index: int
+    message: ResponseMessage
+    finish_reason: str = "stop"
+
+
+@dataclass(frozen=True)
+class Usage:
+    """token 用量(OpenAI 形状):prompt / completion / total。"""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+@dataclass(frozen=True)
+class ChatCompletion:
+    """一次对话补全结果(OpenAI 形状):choices + usage + 元数据,字段与 OpenAI 完全一致。"""
+
+    choices: tuple[Choice, ...]
+    usage: Usage | None = None
+    model: str = ""
+    id: str = ""
+    created: int = 0
+    object: str = "chat.completion"
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    """provider 协议(OpenAI 规范):给 OpenAI 形状的 messages(可选 tools),拿回 OpenAI ChatCompletion。"""
+
+    def chat(
+        self, messages: list[dict[str, Any]], *, tools: list[dict[str, Any]] | None = None
+    ) -> ChatCompletion: ...
+
+
+def _text_of(message: dict[str, Any]) -> str:
+    """从一条 OpenAI message dict 取纯文本内容(content 为 None 时视作空串)。"""
+    return str(message.get("content") or "")
+
+
+class MockProvider:
+    """确定性离线 provider:零网络、零 key,输出 OpenAI 形状的 ChatCompletion,由 messages 派生、可复现。
+
+    回显最后一条 user 消息,并附一段由【整段对话】计算的稳定 hex 指纹——使不同对话(含不同 system /
+    历史)产出不同、但对同一对话恒定的文本;既便于断言,又不引入随机性。绝不伪造 tool_calls:离线
+    默认不假装会 function-calling(真工具调用需接真实 provider)。
+    """
+
+    def __init__(self, *, prefix: str = "mock") -> None:
+        self._prefix = prefix
+
+    def chat(
+        self, messages: list[dict[str, Any]], *, tools: list[dict[str, Any]] | None = None
+    ) -> ChatCompletion:
+        # 指纹覆盖整段对话(role + content),\x00/\x01 作分隔杜绝拼接歧义;取前 12 位 hex。
+        joined = "\x00".join(f"{m.get('role', '')}\x01{_text_of(m)}" for m in messages)
+        digest = hashlib.sha256(joined.encode()).hexdigest()[:12]
+        last_user = next((_text_of(m) for m in reversed(messages) if m.get("role") == "user"), "")
+        text = f"[{self._prefix}:{digest}] {last_user.strip()}"
+        usage = Usage(
+            prompt_tokens=len(joined),
+            completion_tokens=len(text),
+            total_tokens=len(joined) + len(text),
+        )
+        choice = Choice(index=0, message=ResponseMessage(role="assistant", content=text), finish_reason="stop")
+        return ChatCompletion(choices=(choice,), usage=usage, model=f"{self._prefix}", id=f"chatcmpl-{digest}")

corespine/observability/__init__.py

@@ -0,0 +1 @@
+"""corespine.observability —— 隐私安全 trace:只记元数据,拒绝正文。"""

corespine/observability/trace.py

@@ -0,0 +1,90 @@
+"""隐私安全的可观测性原语:TraceSink 协议 + 默认的进程内实现。
+
+约定("trace 按受限数据对待"):trace 只允许记【非敏感元数据】——事件 code、计数、
+耗时、布尔标志这类。绝不记原始答案正文 / 字段取值 / chunk 正文——它们一旦进 trace
+就成了受限数据的泄露面。
+
+默认实现 InProcessPrivacyTraceSink 把这条约定做成"构造即保证":任何带禁词键
+(answer / value / text / content / ...)的载荷会被【直接拒绝】(抛 TraceError),
+而不是悄悄记下去。隐私 by construction,而非靠 reviewer 自觉。
+
+domain-neutral:不预设任何具体事件 code;每个 app 用自己的 code 词表,harness 只管
+"只记元数据、拒绝正文"这条机制。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from corespine.errors import CorespineError
+
+# 禁止出现在 trace 载荷里的键(承载受限正文 / 取值的字段名,归一为小写后比对)。
+# 命中任一即拒绝整条 trace——宁可报错,也不让正文流进可观测链路。
+FORBIDDEN_KEYS = frozenset(
+    {
+        "answer",
+        "value",
+        "text",
+        "content",
+        "prompt",
+        "completion",
+        "chunk",
+        "chunk_text",
+        "body",
+    }
+)
+
+
+class TraceError(CorespineError):
+    """trace 载荷违反隐私约定(携带受限正文 / 取值字段)时抛出。
+
+    继承家族统一基类 CorespineError,带稳定可 grep 的 code,便于跨缝统一捕获 / 归一。
+    """
+
+    code = "trace.forbidden"
+
+
+@dataclass(frozen=True)
+class TraceEvent:
+    """一条被记录的 trace:事件 code + 非敏感字段快照(只读)。"""
+
+    code: str
+    fields: dict[str, object] = field(default_factory=dict)
+
+
+@runtime_checkable
+class TraceSink(Protocol):
+    """trace 出口的最小结构接口:发射一条事件(code + 非敏感字段)。"""
+
+    def emit(self, code: str, **fields: object) -> None: ...
+
+
+class InProcessPrivacyTraceSink:
+    """进程内默认 TraceSink:把事件存进内存列表,且拒绝任何携带受限内容的载荷。
+
+    隐私 by construction:emit 时先扫字段键,命中 FORBIDDEN_KEYS 立即抛 TraceError、
+    绝不记录;通过校验的事件以 TraceEvent 追加到内部列表。只记 code / 计数 / 耗时 / 标志。
+    """
+
+    def __init__(self) -> None:
+        self._events: list[TraceEvent] = []
+
+    @property
+    def events(self) -> list[TraceEvent]:
+        """已记录事件的只读视图(返回副本,外部改动不污染内部状态)。"""
+        return list(self._events)
+
+    def codes(self) -> list[str]:
+        """已记录事件的 code 序列(按记录顺序)。"""
+        return [event.code for event in self._events]
+
+    def emit(self, code: str, **fields: object) -> None:
+        """记一条 trace;载荷含受限字段即抛 TraceError(不记录)。"""
+        offending = sorted(k for k in fields if k.strip().lower() in FORBIDDEN_KEYS)
+        if offending:
+            raise TraceError(
+                f"trace 载荷含受限字段 {offending}:trace 只记 code / 计数 / 耗时,"
+                "不得携带答案正文 / 字段取值 / chunk 正文。"
+            )
+        self._events.append(TraceEvent(code=code, fields=dict(fields)))

corespine/queue/__init__.py

@@ -0,0 +1 @@
+"""corespine.queue —— 任务队列缝:TaskQueue 协议 + 同步 FakeQueue 默认。"""

corespine/queue/task_queue.py

@@ -0,0 +1,93 @@
+"""任务队列缝:TaskQueue 协议 + 同步内联的 FakeQueue 默认实现。
+
+domain-neutral 的 worker / job 队列抽象。Protocol 只约定 enqueue / get 两件事;真实
+后端(RQ+Redis / Celery 等)由各 app 在自己的缝里延迟 import 接入,核心零依赖。
+
+FakeQueue 是离线默认:enqueue 时【同步内联】执行 job 并记录结果 / 失败,不需要任何
+外部服务,让测试与离线流程可复现。job 函数签名约定为 fn(payload: dict) -> dict;
+失败被捕获记进 JobStatus(不外抛),与真实异步后端"失败也是一种终态"的语义一致。
+job 既可传可调用对象,也可传点路径字符串(末段为可调用对象)。
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Any, Protocol, cast, runtime_checkable
+
+# job 终态常量(与常见异步后端语义对齐)。
+JOB_FINISHED = "finished"
+JOB_FAILED = "failed"
+
+# job 函数:纯可序列化 dict 进、dict 出。
+JobFunc = Callable[[dict[str, Any]], dict[str, Any]]
+
+
+@dataclass
+class JobStatus:
+    """一个 job 的状态快照:id + 状态 + 结果 / 错误(成功记 result,失败记 error)。"""
+
+    id: str
+    status: str
+    result: dict[str, Any] | None = None
+    error: dict[str, Any] | None = None
+
+
+@runtime_checkable
+class TaskQueue(Protocol):
+    """任务队列的最小结构接口:投递一个 job、按 id 查状态。"""
+
+    def enqueue(
+        self,
+        func: JobFunc | str,
+        payload: dict[str, Any],
+        *,
+        job_id: str | None = None,
+    ) -> str: ...
+
+    def get(self, job_id: str) -> JobStatus | None: ...
+
+
+def _resolve(func: JobFunc | str) -> JobFunc:
+    """可调用对象原样;点路径字符串 -> 末段可调用对象。"""
+    if callable(func):
+        return func
+    module_path, _, attr = func.rpartition(".")
+    if not module_path:
+        raise ValueError(f"func 必须是可调用对象或点路径:{func!r}")
+    mod = import_module(module_path)
+    return cast("JobFunc", getattr(mod, attr))
+
+
+class FakeQueue:
+    """同步内存队列:enqueue 时内联执行 job(离线 / 测试用,无需任何外部服务)。"""
+
+    def __init__(self) -> None:
+        self._jobs: dict[str, JobStatus] = {}
+
+    def enqueue(
+        self,
+        func: JobFunc | str,
+        payload: dict[str, Any],
+        *,
+        job_id: str | None = None,
+    ) -> str:
+        # 幂等:显式 job_id 且已知 -> 直接返回,不重跑。
+        if job_id is not None and job_id in self._jobs:
+            return job_id
+        jid = job_id or uuid.uuid4().hex[:12]
+        try:
+            result = _resolve(func)(payload)
+            self._jobs[jid] = JobStatus(id=jid, status=JOB_FINISHED, result=result)
+        except Exception as exc:  # noqa: BLE001 — 内联失败记进状态,不外抛
+            self._jobs[jid] = JobStatus(
+                id=jid,
+                status=JOB_FAILED,
+                error={"type": type(exc).__name__, "message": str(exc)},
+            )
+        return jid
+
+    def get(self, job_id: str) -> JobStatus | None:
+        return self._jobs.get(job_id)

corespine/seam/__init__.py

@@ -0,0 +1 @@
+"""corespine.seam —— 缝注册表:name->factory 解析 + entry-point 自动发现。"""

corespine/seam/registry.py

@@ -0,0 +1,112 @@
+"""缝(seam)注册表:把"选哪个实现"从改代码降为一个 spec 字符串。
+
+这是 ragspine `make_vector_store` 的泛化形式——domain-neutral,不绑任何具体缝。
+一个 Registry 实例代表一条缝(如 "vector_store" / "llm" / "queue"):
+
+    - register(name, factory):登记一个 名字->工厂 的内置实现;
+    - make(spec, **kwargs):大小写/留白/连字符不敏感地把 spec 解析到工厂并构造实例;
+    - 内置名找不到时,回落到 importlib.metadata 的 entry-point 自动发现
+      (group 形如 "corespine.<seam>"),让第三方装包即扩展,无需改核心代码;
+    - 仍找不到则抛 ValueError,把【当前可用的全部名字】列清楚,绝不让人猜。
+
+lazy_extra_import 是配套助手:延迟 import 一个可选依赖,缺失时把裸 ImportError
+翻译成"pip install <pkg>[<extra>]"的友好提示——支撑"离线精简默认 + 可选重依赖"
+的范式(核心默认路径零重依赖,真实后端的 SDK 仅在选用时才 import)。
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable
+from importlib import metadata
+from typing import Any, Generic, TypeVar, cast
+
+T = TypeVar("T")
+
+# 一个工厂:任意关键字参数 -> 一个实现实例。
+Factory = Callable[..., T]
+
+
+def _normalize(spec: str) -> str:
+    """名字归一:去首尾留白 + 转小写 + 把连字符/空格统一成下划线。
+
+    使 "In-Process" / " in_process " / "IN PROCESS" 都解析到同一个键。
+    """
+    return spec.strip().lower().replace("-", "_").replace(" ", "_")
+
+
+class Registry(Generic[T]):
+    """一条缝的 名字->工厂 注册表 + spec 解析 + entry-point 自动发现。"""
+
+    def __init__(self, seam: str) -> None:
+        # seam 名既用于 entry-point group("corespine.<seam>"),也用于报错信息。
+        self._seam = seam
+        self._factories: dict[str, Factory[T]] = {}
+
+    @property
+    def seam(self) -> str:
+        return self._seam
+
+    @property
+    def group(self) -> str:
+        """entry-point 自动发现使用的 group 名。"""
+        return f"corespine.{self._seam}"
+
+    def register(self, name: str, factory: Factory[T]) -> None:
+        """登记一个内置实现;名字归一后入表(同名重复登记则后者覆盖)。"""
+        self._factories[_normalize(name)] = factory
+
+    def names(self) -> list[str]:
+        """当前【全部可用】名字:内置 + entry-point 发现,去重后按字典序。"""
+        return sorted(set(self._factories) | set(self._discover()))
+
+    def _discover(self) -> dict[str, metadata.EntryPoint]:
+        """从 importlib.metadata entry points 发现第三方实现(group=corespine.<seam>)。
+
+        延迟到解析时才扫,不在 import 期付出代价;每个 ep 的 load() 也按需触发。
+        返回 归一名 -> EntryPoint(其 load() 给出真正的工厂可调用对象)。
+        """
+        eps = metadata.entry_points(group=self.group)
+        return {_normalize(ep.name): ep for ep in eps}
+
+    def make(self, spec: str, **kwargs: Any) -> T:
+        """把 spec 解析到工厂并构造实例(大小写/留白/连字符不敏感)。
+
+        解析顺序:内置注册 -> entry-point 发现 -> 抛 ValueError(列清可用名)。
+        """
+        key = _normalize(spec)
+        factory = self._factories.get(key)
+        if factory is not None:
+            return factory(**kwargs)
+        # 回落:entry-point 自动发现(第三方装包即扩展,无需改核心)。
+        discovered = self._discover()
+        ep = discovered.get(key)
+        if ep is not None:
+            # entry-point 的 load() 返回 Any;约定它给出本缝的工厂,cast 回 Factory[T]。
+            factory = cast("Factory[T]", ep.load())
+            return factory(**kwargs)
+        raise ValueError(self._unknown_message(spec, discovered))
+
+    def _unknown_message(self, spec: str, discovered: dict[str, metadata.EntryPoint]) -> str:
+        available = sorted(set(self._factories) | set(discovered))
+        listed = ", ".join(available) if available else "(无)"
+        return (
+            f"未知的 {self._seam} spec:{spec!r}。当前可用:{listed}"
+            f"(内置注册或经 entry-point group {self.group!r} 发现;"
+            "第三方实现可装包扩展)。"
+        )
+
+
+def lazy_extra_import(module: str, *, pkg: str, extra: str) -> Any:
+    """延迟 import 一个可选依赖;缺失时给出"pip install <pkg>[<extra>]"友好提示。
+
+    用于"离线精简默认 + 可选重依赖"的范式:核心默认路径零重依赖,真实后端的 SDK
+    仅在选用该 adapter 时才 import。把裸 ImportError 翻译成可直接照做的安装指引,
+    而不是让调用方对着 ModuleNotFoundError 自己猜该装哪个 extra。
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise ImportError(
+            f"缺少可选依赖 {module!r}:请先 `pip install {pkg}[{extra}]` 再重试。"
+        ) from exc

corespine-0.0.1.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: corespine
+Version: 0.0.1
+Summary: Spine 家族的薄共享核:domain-neutral 底层原语(缝注册表 / observability / LLM 缝 / config / queue / conformance 基座)。
+Author: lin han
+License-Expression: Apache-2.0
+Keywords: conformance,framework-free,llm-provider,observability,offline,registry,seam,task-queue
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# corespine
+
+Spine 家族的**薄共享核**(见 [ADR 0001](../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md))。
+只装 **domain-neutral 的底层原语**——既不属于 RAG 也不属于 agent 的稳定地基,被 `ragspine` /
+`agentspine` 兄弟包各自依赖,**不**含任何它们的领域概念。
+
+> 刻意地薄。按证据(rule of three)增长,不预先造框架。详见 [`CLAUDE.md`](CLAUDE.md) 宪章。
+
+## 缝的元模式
+
+每条缝都长一个样,核心 import 零 SDK、离线可跑:
+
+**Protocol + 离线确定性默认 + `Registry` / `make_*` 工厂 + 参数化 conformance**
+
+## 里面有什么
+
+| 模块 | 原语 |
+|---|---|
+| `seam/registry.py` | `Registry`:name→factory 解析(大小写/留白/连字符不敏感)+ entry-point 自动发现(`corespine.<seam>` group)+ 未知 spec 列清可用名 + `lazy_extra_import`(缺 extra 给"pip install …"友好提示) |
+| `observability/trace.py` | `TraceSink` 协议 + `InProcessPrivacyTraceSink`:只记 code/计数/耗时,**拒绝**任何携带正文(answer/value/text/content…)的载荷 |
+| `llm/provider.py` | `LLMProvider` 协议 + 离线确定性 `MockProvider`(零网络、零 key、可复现) |
+| `config/env.py` | `load_from_env`:把 `PREFIX_*` 环境变量读进一个 frozen dataclass(范式同 ragspine `from_env`) |
+| `queue/task_queue.py` | `TaskQueue` 协议 + `FakeQueue`:同步内联执行 + 记录,离线/测试用 |
+| `conformance/harness.py` | `ConformanceSuite` × `InvariantPack`:把"实现 × 不变量"绑成笛卡尔积逐格执行(**机制**,具体不变量由各 app 自己绑) |
+
+## 本地开发(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -c "import corespine"
+```
+
+## 30 秒上手
+
+```python
+from corespine import Registry, MockProvider, InProcessPrivacyTraceSink, FakeQueue
+
+# 缝:一个 spec 选实现(大小写/留白不敏感;找不到列清可用名;还能 entry-point 自动发现)
+reg: Registry = Registry("llm")
+reg.register("mock", lambda **kw: MockProvider(**kw))
+provider = reg.make("  MOCK ")
+# OpenAI chat-completions 规范:messages 进,OpenAI 形状的 ChatCompletion 出(确定性可复现)
+out = provider.chat([{"role": "user", "content": "hello"}])
+print(out.choices[0].message.content)
+
+# 隐私 trace:只记元数据;塞正文会被直接拒绝(raise TraceError)
+sink = InProcessPrivacyTraceSink()
+sink.emit("retrieve", count=3, took_ms=12)
+
+# 任务队列:同步内联执行
+q = FakeQueue()
+jid = q.enqueue(lambda p: {"doubled": p["n"] * 2}, {"n": 21})
+print(q.get(jid).result)                 # {'doubled': 42}
+```

corespine-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+corespine/__init__.py,sha256=iSuKpiHK7eZoTatWSniAIBg8Y10gGgOwT4eSxh09quw,1754
+corespine/errors.py,sha256=ppMIlz46lIoOXD1MeQ2vOrsBkkkLwRxQejrLUUmUyBM,2895
+corespine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+corespine/config/__init__.py,sha256=wLleoMh5Hi7l-_fc0UvEUl1FlVKwTqQZBKEtKbskkms,85
+corespine/config/env.py,sha256=VWTmBFfzKTu2l0-4Usc6hYmhNZ8df3nnNcshyzNG22M,3112
+corespine/conformance/__init__.py,sha256=tvnJwXVWcY1H48qV80tnNdYPmr5kkHhgsiSx0Ly5iD0,97
+corespine/conformance/harness.py,sha256=AXnUhTwrCN_iGsiYF95GKiEFWkhjclyGkIdTRE1U1dc,5301
+corespine/llm/__init__.py,sha256=BxI-sSWYK7vI95z9R806LMc6LVixXBg9eHH1_PKhqtg,88
+corespine/llm/provider.py,sha256=t1Kv16wdkygA5D-E2kA3ocQXtOL50DEYZ2vZOo6mHMU,4872
+corespine/observability/__init__.py,sha256=2G9gKi8WGpa57BUUcB1mB0CQIUMH6UDfT9zNrASi56I,88
+corespine/observability/trace.py,sha256=K-Qc1sznB6vSLOHl0WMEMvljzm63A6VQiRDnambW0Vw,3337
+corespine/queue/__init__.py,sha256=4g0cb626ensd5ATrMaSiwPBzrNb1K4g3Ye9kOTzxcFs,91
+corespine/queue/task_queue.py,sha256=nWx38mNScHMqKA9bgv0cyJY0BiutjLyZVnQyHlR_wk8,3189
+corespine/seam/__init__.py,sha256=LAtM1d8laijBbXkBs9XXGAQiIh8bm0E2KhyRejGiey0,92
+corespine/seam/registry.py,sha256=m8asc3yaAuhqqh87dGr021GtyRl7i1GmC0_B12OCRyY,5003
+corespine-0.0.1.dist-info/METADATA,sha256=J2gVJZRz1VGBjXlwpG4zbpDwWskjwxGcwRHkcE_S9Zo,3630
+corespine-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+corespine-0.0.1.dist-info/RECORD,,

corespine-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any