spinekit 0.2.0__tar.gz

spinekit-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!-- Thanks for contributing to Spine! -->
+
+## What & why
+
+<!-- What does this change, and why? Link any issue. -->
+
+## Checklist
+
+- [ ] Gates pass locally: `uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run mypy`
+- [ ] Added/updated tests (no network — use `ScriptedProvider` / fakes)
+- [ ] New feature is a **middleware / backend / adapter**, not a kernel edit
+- [ ] Updated docs / package `README.md` if behavior changed
+- [ ] Conventional commit message (`feat:`, `fix:`, `docs:`, …)

spinekit-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync workspace
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy --strict)
+        run: uv run mypy
+
+      - name: Tests
+        run: uv run pytest
+
+      - name: Docs build (strict)
+        run: uv run mkdocs build --strict

spinekit-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

spinekit-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# release-please opens/maintains a "Release PR" as commits land on main.
+# Merging that PR bumps the version, updates CHANGELOG.md, and creates the
+# GitHub release + tag — which, in the SAME run, publishes to PyPI via OIDC.
+on:
+  push:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.rp.outputs.release_created }}
+      tag_name: ${{ steps.rp.outputs.tag_name }}
+    steps:
+      - id: rp
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # OIDC trusted publishing — no stored secret
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Build the spinekit distribution
+        run: |
+          rm -rf dist
+          uv build --out-dir dist
+          ls -la dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

spinekit-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Docs build output
+/site/
+
+# Tooling caches
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

spinekit-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

spinekit-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

spinekit-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## [0.2.0](https://github.com/Research-Analytics-Solutions/spine/compare/v0.1.0...v0.2.0) (2026-06-18)
+
+
+### Features
+
+* **a2a:** agent-to-agent adapter — call a remote agent as a tool ([473bdfe](https://github.com/Research-Analytics-Solutions/spine/commit/473bdfe9803dd722a27a7624ab71b64e3a2d3550))
+* **backends:** Redis + Postgres checkpoint backends + conformance suite ([a9d8990](https://github.com/Research-Analytics-Solutions/spine/commit/a9d8990e41e8f6383dc26c1f11524de2ba9b89c9))
+* **backends:** spine-backends with durable SQLite checkpoint ([9974652](https://github.com/Research-Analytics-Solutions/spine/commit/997465223cb3c3d7d01d3ace2eda755bfc01a1e2))
+* **cli:** config-driven agent build + chat/trace commands ([8da432e](https://github.com/Research-Analytics-Solutions/spine/commit/8da432e3157e7e26861e5c01e8814f4e67c79423))
+* **cli:** spine dev — live-streaming trace viewer ([5b2ed12](https://github.com/Research-Analytics-Solutions/spine/commit/5b2ed127d9520a364ee54b21f52f9a77d24c63d1))
+* **cli:** spine-cli with init/run/doctor/plugin (Typer + Rich) ([422d1b5](https://github.com/Research-Analytics-Solutions/spine/commit/422d1b579c3f810e93b8f4a96f246ef29d1d77f6))
+* **core:** parallel tool calls, cooperative cancellation, sub-agents ([14ce08f](https://github.com/Research-Analytics-Solutions/spine/commit/14ce08f1d32f72c3d71e0cf3db495e20408b376c))
+* **core:** spine-core kernel — loop, guards, middleware, tools, HITL ([450df11](https://github.com/Research-Analytics-Solutions/spine/commit/450df1135b10b8fe5032b217eb75fba93fa9c9ca))
+* **eval:** spine-eval harness + spine eval CLI command ([316c27b](https://github.com/Research-Analytics-Solutions/spine/commit/316c27bb6c1ee849bab4767c52907f404393c716))
+* **mcp:** spine-mcp adapter + raw_tool core primitive ([80676fb](https://github.com/Research-Analytics-Solutions/spine/commit/80676fb403ba607b29d1e52f3b1d8317418ccd5b))
+* **memory:** pluggable embedders + multiple memory types ([7f5a1b8](https://github.com/Research-Analytics-Solutions/spine/commit/7f5a1b8aa6a0649364fc6c776ffb497944835385))
+* **memory:** semantic memory protocol, vector backend, recall middleware ([e59b306](https://github.com/Research-Analytics-Solutions/spine/commit/e59b306a80defc8ea8a8eebc0440d149d9d34f3b))
+* **middleware:** deterministic replay (Recorder/Replayer) ([327c39b](https://github.com/Research-Analytics-Solutions/spine/commit/327c39b458d2af8e6bcaedd87741ec945a39559b))
+* **middleware:** guardrails — PII redaction, injection screening, content policy ([a714367](https://github.com/Research-Analytics-Solutions/spine/commit/a714367e0510648086f28e14b27a8fea9eb311e6))
+* **middleware:** prompt/response Cache + kernel cache-hit short-circuit ([0deab9c](https://github.com/Research-Analytics-Solutions/spine/commit/0deab9c55a9c44764b0744d4bf1cc225e0624501))
+* **middleware:** tool timeout/truncation, circuit breaker, idempotency, rate limit ([de4e27a](https://github.com/Research-Analytics-Solutions/spine/commit/de4e27a7b8c03a5a91966182c810ffbe40f655e2))
+* **middleware:** V1 middleware suite + kernel control primitives ([a6d7766](https://github.com/Research-Analytics-Solutions/spine/commit/a6d776663bdb644d5e24d7f28a8bd225c28d8617))
+* **multimodal:** image/file content parts on Message + provider mapping ([4993441](https://github.com/Research-Analytics-Solutions/spine/commit/4993441cb2f3accf475a216e15c60ed1cc51f896))
+* **multitenancy:** tenant_id on state + per-tenant budget guard ([b306e11](https://github.com/Research-Analytics-Solutions/spine/commit/b306e11a65323ea736fe24f07585150973906458))
+* **orchestration:** sequential, supervisor, handoff patterns ([d2adb2e](https://github.com/Research-Analytics-Solutions/spine/commit/d2adb2eceb769e5dc5c7f73f8917adc2fdb382f4))
+* **otel:** spine-otel — one OpenTelemetry span tree per run ([2453bf2](https://github.com/Research-Analytics-Solutions/spine/commit/2453bf2f8383389b022d2b838cf143ab497fe160))
+* **providers:** add OpenAI adapter ([6005eb9](https://github.com/Research-Analytics-Solutions/spine/commit/6005eb955a8a313fa1ce5af9e96bf7d438342f9a))
+* **providers:** spine-providers with Anthropic adapter ([cbe1171](https://github.com/Research-Analytics-Solutions/spine/commit/cbe1171a53a139fc51dec356ec3adf89189f2a1c))
+* **sandbox:** resource-limited subprocess sandbox for sync tools ([5622d1a](https://github.com/Research-Analytics-Solutions/spine/commit/5622d1a4dfc0266fae16357a6de33919384bccef))
+* **streaming:** token-level streaming through provider + kernel ([85df88a](https://github.com/Research-Analytics-Solutions/spine/commit/85df88aff07f9672d1d8e06e2d309422f243dea7))
+
+
+### Bug Fixes
+
+* **core:** auto-resolve provider scheme via plugin entry points ([4f2213d](https://github.com/Research-Analytics-Solutions/spine/commit/4f2213d419393153d62703495f691932168cb98c))
+* **core:** bound provider-retry loop; make resume token durable ([1b6c434](https://github.com/Research-Analytics-Solutions/spine/commit/1b6c434c15e74864c734ebd387df50da3383e32d))
+
+
+### Documentation
+
+* contributor guide, plugin development & publishing, eval/MCP deep dives ([81b126f](https://github.com/Research-Analytics-Solutions/spine/commit/81b126f4cdbdc5fa02a8de5ea4a399b9bdddfbc4))
+* deep reference — data model, cookbook, patterns, expanded CLI & API ([409701a](https://github.com/Research-Analytics-Solutions/spine/commit/409701a834202fdc5aef938814bc6ae7c66cc16f))
+* fix mermaid diagram invisibility in dark mode ([359985d](https://github.com/Research-Analytics-Solutions/spine/commit/359985ddde0d6fe42c8f4824f55b43c4d2b67b3b))
+* landing page hero, logo, mermaid + grid-card fixes ([13f929b](https://github.com/Research-Analytics-Solutions/spine/commit/13f929b05ddeae0f54eaee1c6d4cefe1adb38c1f))
+* mkdocs-material documentation site ([4e63082](https://github.com/Research-Analytics-Solutions/spine/commit/4e630824e14303896c3d0c2e0254654f9d6bb4d2))
+* reconcile with single spinekit distribution ([878a934](https://github.com/Research-Analytics-Solutions/spine/commit/878a934cfbc2611b62edadfde1d090bb6f0e69ef))
+* replace ASCII four-planes box with a styled mermaid diagram ([86c3de3](https://github.com/Research-Analytics-Solutions/spine/commit/86c3de382c21bc0b53b860c5be504fabeda66ecb))
+
+
+### Build & Packaging
+
+* repackage as a single 'spinekit' distribution with extras ([a4e3765](https://github.com/Research-Analytics-Solutions/spine/commit/a4e37655c38751990134a3b6cbb62e584c31d5f1))

spinekit-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+and will take appropriate and fair corrective action in response to any behavior
+that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers responsible for enforcement. All complaints
+will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org

spinekit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Research Analytics Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spinekit-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: spinekit
+Version: 0.2.0
+Summary: A lightweight, modular, protocol-native runtime for production AI agents.
+Project-URL: Homepage, https://github.com/Research-Analytics-Solutions/spine
+Project-URL: Documentation, https://research-analytics-solutions.github.io/spine/
+Project-URL: Repository, https://github.com/Research-Analytics-Solutions/spine
+Author: Research Analytics Solutions
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a2a,agents,ai,kernel,llm,mcp,runtime
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.4
+Requires-Dist: pydantic>=2.7
+Provides-Extra: a2a
+Requires-Dist: httpx>=0.27; extra == 'a2a'
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: mcp>=1.2; extra == 'all'
+Requires-Dist: openai>=1.40; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.27; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: rich>=13.7; extra == 'all'
+Requires-Dist: typer>=0.12; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: cli
+Requires-Dist: rich>=13.7; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
+Provides-Extra: eval
+Requires-Dist: pyyaml>=6.0; extra == 'eval'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.27; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otlp'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: providers
+Requires-Dist: anthropic>=0.40; extra == 'providers'
+Requires-Dist: openai>=1.40; extra == 'providers'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/logo-hero.svg" alt="Spine" width="110" />
+</p>
+
+<h1 align="center">Spine</h1>
+
+<p align="center">
+  <strong>A lightweight, modular, protocol-native runtime for production AI agents.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Research-Analytics-Solutions/spine/actions/workflows/ci.yml"><img src="https://github.com/Research-Analytics-Solutions/spine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+">
+  <a href="https://research-analytics-solutions.github.io/spine/"><img src="https://img.shields.io/badge/docs-mkdocs--material-526CFE.svg" alt="Docs"></a>
+</p>
+
+<p align="center">
+  <a href="https://research-analytics-solutions.github.io/spine/">Documentation</a> ·
+  <a href="https://research-analytics-solutions.github.io/spine/quickstart/">Quickstart</a> ·
+  <a href="https://research-analytics-solutions.github.io/spine/guides/examples/">Cookbook</a> ·
+  <a href="https://research-analytics-solutions.github.io/spine/contributing/">Contributing</a>
+</p>
+
+---
+
+Spine is the *kernel* for AI agents — a tiny, load-bearing runtime that everything
+else plugs into. Where monolithic frameworks bundle heavy abstractions, Spine
+ships a small core and pushes every feature into **opt-in middleware, swappable
+backends, and protocol adapters**.
+
+```python
+from spine_core import Agent
+
+agent = Agent("openai:gpt-4o-mini")
+print((await agent.run("say hello")).answer)
+```
+
+## Three guarantees
+
+- **No hidden prompts** — every model call consumes inspectable, typed `Message` objects.
+- **No runaway loops** — guards are enforced inside the kernel, every iteration.
+- **Deterministic replay** — any run can be recorded and replayed step-for-step.
+
+## Install
+
+One package, lean core, opt-in extras:
+
+```bash
+pip install spinekit                  # kernel only (pydantic + anyio)
+pip install "spinekit[openai]"        # + OpenAI
+pip install "spinekit[anthropic,redis,cli]"   # pick parts
+pip install "spinekit[all]"           # everything
+```
+
+Import name stays `spine_core`. See the [install guide](https://research-analytics-solutions.github.io/spine/install/).
+
+## What's in the box
+
+| Module | Extra | What |
+|---|---|---|
+| `spine_core` | — | the kernel — loop, state, guards, tracer, protocols, HITL, streaming |
+| `spine_middleware` | — | retry, fallback, guardrails, cache, memory recall, sandbox, replay, … |
+| `spine_backends` | `redis` / `postgres` | checkpoints (SQLite always; Redis/Postgres) + memory (vector/buffer/pgvector) |
+| `spine_providers` | `openai` / `anthropic` | OpenAI + Anthropic (and any OpenAI-compatible endpoint) |
+| `spine_mcp` · `spine_a2a` · `spine_otel` | `mcp` · `a2a` · `otel` | MCP tools · remote agents · OpenTelemetry |
+| `spine_eval` | `eval` | dataset + scorers + Cost/Latency/Efficacy/Reliability report |
+| `spine_orchestration` | — | sequential / supervisor / handoff |
+| `spine_cli` | `cli` | `init` / `run` / `chat` / `dev` / `trace` / `eval` / `doctor` / `plugin` |
+
+## Develop
+
+```bash
+uv sync                      # install workspace + dev deps
+uv run pytest                # tests
+uv run ruff check .          # lint
+uv run mypy                  # strict type-check
+uv run mkdocs serve          # preview docs at http://127.0.0.1:8000
+```
+
+See the [Contributing guide](https://research-analytics-solutions.github.io/spine/contributing/)
+to build your own [middleware](https://research-analytics-solutions.github.io/spine/develop/middleware/),
+[provider](https://research-analytics-solutions.github.io/spine/develop/provider/), or
+[backend](https://research-analytics-solutions.github.io/spine/develop/publish/) and publish it
+as a plugin.
+
+## License
+
+[MIT](LICENSE) © 2026 Research Analytics Solutions

spinekit-0.2.0/README.md

@@ -0,0 +1,89 @@
+<p align="center">
+  <img src="docs/assets/logo-hero.svg" alt="Spine" width="110" />
+</p>
+
+<h1 align="center">Spine</h1>
+
+<p align="center">
+  <strong>A lightweight, modular, protocol-native runtime for production AI agents.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Research-Analytics-Solutions/spine/actions/workflows/ci.yml"><img src="https://github.com/Research-Analytics-Solutions/spine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+">
+  <a href="https://research-analytics-solutions.github.io/spine/"><img src="https://img.shields.io/badge/docs-mkdocs--material-526CFE.svg" alt="Docs"></a>
+</p>
+
+<p align="center">
+  <a href="https://research-analytics-solutions.github.io/spine/">Documentation</a> ·
+  <a href="https://research-analytics-solutions.github.io/spine/quickstart/">Quickstart</a> ·
+  <a href="https://research-analytics-solutions.github.io/spine/guides/examples/">Cookbook</a> ·
+  <a href="https://research-analytics-solutions.github.io/spine/contributing/">Contributing</a>
+</p>
+
+---
+
+Spine is the *kernel* for AI agents — a tiny, load-bearing runtime that everything
+else plugs into. Where monolithic frameworks bundle heavy abstractions, Spine
+ships a small core and pushes every feature into **opt-in middleware, swappable
+backends, and protocol adapters**.
+
+```python
+from spine_core import Agent
+
+agent = Agent("openai:gpt-4o-mini")
+print((await agent.run("say hello")).answer)
+```
+
+## Three guarantees
+
+- **No hidden prompts** — every model call consumes inspectable, typed `Message` objects.
+- **No runaway loops** — guards are enforced inside the kernel, every iteration.
+- **Deterministic replay** — any run can be recorded and replayed step-for-step.
+
+## Install
+
+One package, lean core, opt-in extras:
+
+```bash
+pip install spinekit                  # kernel only (pydantic + anyio)
+pip install "spinekit[openai]"        # + OpenAI
+pip install "spinekit[anthropic,redis,cli]"   # pick parts
+pip install "spinekit[all]"           # everything
+```
+
+Import name stays `spine_core`. See the [install guide](https://research-analytics-solutions.github.io/spine/install/).
+
+## What's in the box
+
+| Module | Extra | What |
+|---|---|---|
+| `spine_core` | — | the kernel — loop, state, guards, tracer, protocols, HITL, streaming |
+| `spine_middleware` | — | retry, fallback, guardrails, cache, memory recall, sandbox, replay, … |
+| `spine_backends` | `redis` / `postgres` | checkpoints (SQLite always; Redis/Postgres) + memory (vector/buffer/pgvector) |
+| `spine_providers` | `openai` / `anthropic` | OpenAI + Anthropic (and any OpenAI-compatible endpoint) |
+| `spine_mcp` · `spine_a2a` · `spine_otel` | `mcp` · `a2a` · `otel` | MCP tools · remote agents · OpenTelemetry |
+| `spine_eval` | `eval` | dataset + scorers + Cost/Latency/Efficacy/Reliability report |
+| `spine_orchestration` | — | sequential / supervisor / handoff |
+| `spine_cli` | `cli` | `init` / `run` / `chat` / `dev` / `trace` / `eval` / `doctor` / `plugin` |
+
+## Develop
+
+```bash
+uv sync                      # install workspace + dev deps
+uv run pytest                # tests
+uv run ruff check .          # lint
+uv run mypy                  # strict type-check
+uv run mkdocs serve          # preview docs at http://127.0.0.1:8000
+```
+
+See the [Contributing guide](https://research-analytics-solutions.github.io/spine/contributing/)
+to build your own [middleware](https://research-analytics-solutions.github.io/spine/develop/middleware/),
+[provider](https://research-analytics-solutions.github.io/spine/develop/provider/), or
+[backend](https://research-analytics-solutions.github.io/spine/develop/publish/) and publish it
+as a plugin.
+
+## License
+
+[MIT](LICENSE) © 2026 Research Analytics Solutions

spinekit-0.2.0/docs/architecture.md

@@ -0,0 +1,94 @@
+# Architecture
+
+## Design principles
+
+These are binding constraints, not aspirations.
+
+1. **Tiny kernel.** The core is the execution loop, the state model, and the
+   guard checks — importable with zero third-party runtime dependencies beyond
+   the standard library + Pydantic + anyio.
+2. **Everything is a plugin.** Each feature is exactly one of: **middleware**
+   (wraps a step), **backend** (implements a protocol), or **adapter** (bridges a
+   standard). If a feature requires editing the kernel, it was modeled wrong.
+3. **Pay only for what you import.** A beginner imports nothing extra and writes
+   3 lines. An enterprise stacks a dozen middlewares. Same kernel.
+4. **Protocol-first.** Consume MCP and A2A rather than inventing proprietary
+   equivalents. Lock-in is a non-goal.
+5. **Observable & deterministic by default.** Every step emits a trace event and
+   an OpenTelemetry span. No hidden state, no hidden prompts.
+6. **Async-first.** The core is `async`; a thin synchronous facade sits on top.
+7. **Typed and validated.** Pydantic v2 at every boundary.
+
+## The four planes
+
+```mermaid
+flowchart TB
+    API["<b>Developer API</b><br/><code>Agent()</code> · <code>@tool</code> · <code>middleware=[...]</code>"]
+
+    subgraph KERNEL ["🧠 &nbsp;KERNEL &nbsp;·&nbsp; we own"]
+        direction LR
+        K1[Step loop] ~~~ K2[State] ~~~ K3[Guards] ~~~ K4[Tracer]
+    end
+
+    subgraph MW ["🧩 &nbsp;MIDDLEWARE &nbsp;·&nbsp; opt-in, chainable"]
+        direction LR
+        M1[Retry] ~~~ M2[Guardrails] ~~~ M3[Cache] ~~~ M4[Compaction] ~~~ M5[Memory]
+    end
+
+    subgraph BE ["🔌 &nbsp;BACKENDS &nbsp;·&nbsp; swappable, behind protocols"]
+        direction LR
+        B1[Providers] ~~~ B2[Checkpoints] ~~~ B3[Memory stores]
+    end
+
+    subgraph AD ["🌐 &nbsp;ADAPTERS &nbsp;·&nbsp; bridge open standards"]
+        direction LR
+        A1[MCP] ~~~ A2[A2A] ~~~ A3[OTLP]
+    end
+
+    API --> KERNEL --> MW --> BE --> AD
+
+    %% stroke-only accents — no fill/text-color overrides, so text follows the
+    %% Material theme and stays readable in both light and dark mode.
+    classDef api stroke:#6366f1,stroke-width:2px;
+    classDef kernel stroke:#4f46e5,stroke-width:2.5px;
+    classDef plane stroke:#94a3b8,stroke-width:1.5px;
+    class API api;
+    class KERNEL kernel;
+    class MW,BE,AD plane;
+```
+
+The kernel never *constructs* behavior; it *invokes hooks*. Middlewares attach to
+defined hook points; backends sit behind tiny protocols; adapters translate open
+standards.
+
+## Repository layout
+
+```
+spine/
+├── packages/
+│   ├── spine-core/         # kernel, protocols, guards, tracer
+│   ├── spine-cli/          # Typer CLI + templates + dev server
+│   ├── spine-providers/    # OpenAI, Anthropic adapters
+│   ├── spine-middleware/   # the middleware suite
+│   ├── spine-backends/     # sqlite/redis/postgres + vector/buffer/pgvector
+│   ├── spine-mcp/          # MCP client adapter
+│   ├── spine-a2a/          # A2A adapter
+│   ├── spine-otel/         # OpenTelemetry middleware
+│   ├── spine-eval/         # eval harness + scorers
+│   └── spine-orchestration/# sequential / supervisor / handoff
+└── docs/
+```
+
+The source is organized by plane under `packages/*/src/` (import names
+`spine_core`, `spine_providers`, …), but it all ships as **one distribution,
+`spinekit`** — a lean core (Pydantic + anyio) with heavy dependencies as opt-in
+extras (`spinekit[openai]`, `spinekit[redis]`, `spinekit[all]`, …). The code is
+small; only the third-party dependencies are optional.
+
+## The bet
+
+The integration layer that made monolithic frameworks valuable has been
+commoditized by open standards. The durable value sits in the **reliability
+runtime** — the execution loop, guards, durable state, and observability that
+decide whether an agent survives production. Spine owns that core and lets the
+standards do the integration.

spinekit-0.2.0/docs/assets/favicon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" role="img" aria-label="Spine">
+  <rect width="32" height="32" rx="7" fill="#5b5bd6"/>
+  <rect x="14.4" y="4" width="3.2" height="24" rx="1.6" fill="#ffffff" opacity="0.55"/>
+  <rect x="8.5" y="5.5" width="15" height="3.1" rx="1.55" fill="#ffffff"/>
+  <rect x="7.2" y="10.8" width="17.6" height="3.1" rx="1.55" fill="#ffffff"/>
+  <rect x="7.2" y="16.1" width="17.6" height="3.1" rx="1.55" fill="#ffffff"/>
+  <rect x="8.5" y="21.4" width="15" height="3.1" rx="1.55" fill="#ffffff"/>
+</svg>

spinekit-0.2.0/docs/assets/logo-hero.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" fill="none" role="img" aria-label="Spine">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="96" y2="96" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#818cf8"/>
+      <stop offset="1" stop-color="#4f46e5"/>
+    </linearGradient>
+  </defs>
+  <rect x="42" y="10" width="12" height="76" rx="6" fill="url(#g)" opacity="0.45"/>
+  <rect x="24" y="14" width="48" height="10.5" rx="5.25" fill="url(#g)"/>
+  <rect x="19" y="31" width="58" height="10.5" rx="5.25" fill="url(#g)"/>
+  <rect x="19" y="48" width="58" height="10.5" rx="5.25" fill="url(#g)"/>
+  <rect x="24" y="65" width="48" height="10.5" rx="5.25" fill="url(#g)"/>
+  <rect x="32" y="82" width="32" height="8" rx="4" fill="url(#g)" opacity="0.8"/>
+</svg>