Metadata-Version: 2.4
Name: spinekit
Version: 0.3.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
