corespine

Spine 家族的薄共享核(见 ADR 0001)。 只装 domain-neutral 的底层原语——既不属于 RAG 也不属于 agent 的稳定地基,被 ragspine / spineagent 兄弟包各自依赖,不含任何它们的领域概念。

刻意地薄。按证据(rule of three)增长,不预先造框架。详见 CLAUDE.md 宪章。

🤖 给 AI / LLM: 用本库前先读 llms.txt(精简索引)与 docs/llms/(完整 API / recipes / 陷阱);pip install 后这些文档随包位于 site-packages/corespine/_llms/。

缝的元模式

每条缝都长一个样,核心 import 零 SDK、离线可跑:

Protocol + 离线确定性默认 + Registry / make_* 工厂 + 参数化 conformance

里面有什么

本地开发(始终从包根)

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 秒上手

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}