Metadata-Version: 2.4
Name: agentspine
Version: 0.1.6
Summary: Open-source adaptive control plane for production AI agents
Project-URL: Homepage, https://github.com/org/agentspine
Project-URL: Documentation, https://agentspine.dev/docs
Project-URL: Repository, https://github.com/org/agentspine
Author: AgentSpine Contributors
License-Expression: Apache-2.0
Keywords: agents,ai,control-plane,production,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: asyncpg<1.0,>=0.29
Requires-Dist: cryptography>=42.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0
Requires-Dist: structlog>=24.0
Requires-Dist: uuid7>=0.1
Provides-Extra: all
Requires-Dist: neo4j<6.0,>=5.0; extra == 'all'
Requires-Dist: pgvector<0.4,>=0.3; extra == 'all'
Requires-Dist: redis<6.0,>=5.0; extra == 'all'
Requires-Dist: sentence-transformers<4.0,>=3.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: alembic>=1.14; extra == 'dev'
Requires-Dist: httpx>=0.28; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: testcontainers[postgres,redis]>=4.0; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: pgvector<0.4,>=0.3; extra == 'embeddings'
Requires-Dist: sentence-transformers<4.0,>=3.0; extra == 'embeddings'
Provides-Extra: neo4j
Requires-Dist: neo4j<6.0,>=5.0; extra == 'neo4j'
Provides-Extra: redis
Requires-Dist: redis<6.0,>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

<div align="center">
<img src="https://raw.githubusercontent.com/Hrushi11/AgentSpine/master/assets/AgentSpineHero.png" alt="AgentSpine Hero">
<br>

[![PyPI - Version](https://img.shields.io/pypi/v/agentspine)](https://pypi.org/project/agentspine/)
![Python](https://img.shields.io/badge/Python-3.11%2B-blue)
![Postgres](https://img.shields.io/badge/Postgres-16%2B-blue)
![Redis](https://img.shields.io/badge/Redis-7%2B-red)
![License](https://img.shields.io/badge/License-Apache%202.0-green)
</div>

> Open-source adaptive control plane for production AI agents.

AgentSpine is an embedded Python SDK that sits between your AI agents and the tools they use — enforcing policies, preventing duplicates, managing locks, scoring risk, and logging every action for full observability.

## Features

- **Policy Engine** — Declarative rules that deny, allow, or require approval for agent actions
- **Semantic Deduplication** — Prevent agents from repeating the same action using embedding similarity
- **Distributed Locks** — Prevent two agents from modifying the same resource simultaneously
- **Risk Scoring** — Score every action on a 0–1 scale and route to fast-path, judiciary, or human approval
- **Knowledge Graph** — Track relationships between agents, actions, tools, and resources
- **Credential Vault** — Encrypted at-rest storage for API keys and OAuth tokens
- **Event Timeline** — Append-only audit log of every action and decision
- **Rate Limiting & Circuit Breakers** — Per-agent, per-tool, per-workflow limits
- **Feature Flags** — Enable only the subsystems you need; disable the rest for zero overhead

## Quickstart

```bash
# Start infrastructure
docker compose up -d

# Install SDK
pip install agentspine[all]
```

```python
import asyncio
from agentspine import AgentSpine

async def main():
    spine = AgentSpine(workflow="demo")

    async def local_echo(payload, context):
        return {"echo": payload}

    spine.register_tool("demo.echo", local_echo)

    result = await spine.request_action(
        agent="demo_agent",
        action_type="demo.echo",
        payload={"text": "Hello from AgentSpine!"},
        idempotency_key="demo_001",
    )
    print(f"Status: {result.status}")
    await spine.close()

asyncio.run(main())
```

If no local tool is registered for an action type, AgentSpine emits a normalized execution signal so an external
worker or service can perform the real side effect and report the result back later.

## Feature Flags

```python
from agentspine import AgentSpine
from agentspine.features import FeatureFlags

# Full mode (default) — all features on
spine = AgentSpine(workflow="my_workflow")

# Standard — no KG or judiciary
spine = AgentSpine(workflow="my_workflow", features=FeatureFlags.standard())

# Minimal — policy + events only
spine = AgentSpine(workflow="my_workflow", features=FeatureFlags.minimal())
```

## Architecture

```
Agent → AgentSpine SDK → Pipeline → Tool
           │
           ├── Policy Engine (allow/deny/approve)
           ├── Semantic Dedupe (pgvector)
           ├── Risk Scorer (0-1 score)
           ├── Knowledge Graph (Postgres)
           ├── Distributed Locks (Redis)
           └── Event Timeline (append-only)
```

## Requirements

- Python 3.11+
- PostgreSQL 16+ (with pgvector extension)
- Redis 7+ (optional, for locks/rate-limiting/circuit-breakers)

## Documentation

- [Quickstart](docs/quickstart.md)
- [Architecture](docs/architecture.md)
- [Deployment](docs/deployment.md)
- [Plugins](docs/plugins.md)
- [API Reference](docs/api-reference.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

Apache 2.0 — See [LICENSE](LICENSE).
