Metadata-Version: 2.4
Name: grampus-ai
Version: 0.1.0
Summary: Production-grade agentic AI framework built on Dapr
Project-URL: Homepage, https://github.com/alireza1989/grampus
Project-URL: Documentation, https://alireza1989.github.io/grampus
Project-URL: Repository, https://github.com/alireza1989/grampus
Project-URL: Bug Tracker, https://github.com/alireza1989/grampus/issues
Project-URL: Changelog, https://github.com/alireza1989/grampus/blob/main/CHANGELOG.md
License: MIT
License-File: LICENSE
Keywords: agents,ai,dapr,llm,memory,orchestration,safety
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.12
Requires-Dist: click>=8.1
Requires-Dist: dapr-ext-grpc>=1.17
Requires-Dist: dapr>=1.17
Requires-Dist: httpx>=0.28
Requires-Dist: opentelemetry-api>=1.29
Requires-Dist: opentelemetry-exporter-otlp>=1.29
Requires-Dist: opentelemetry-sdk>=1.29
Requires-Dist: pydantic-settings>=2.14
Requires-Dist: pydantic>=2.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=25.5
Requires-Dist: tiktoken>=0.12
Provides-Extra: a2a
Requires-Dist: a2a-sdk>=0.3.0; extra == 'a2a'
Provides-Extra: all
Requires-Dist: a2a-sdk>=0.3.0; extra == 'all'
Requires-Dist: aiosqlite>=0.19; extra == 'all'
Requires-Dist: anthropic>=0.97; extra == 'all'
Requires-Dist: arize-phoenix-otel>=0.6; extra == 'all'
Requires-Dist: asyncpg>=0.30; extra == 'all'
Requires-Dist: cohere>=5.1.8; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: greenlet>=3.0; extra == 'all'
Requires-Dist: ipython>=8.0; extra == 'all'
Requires-Dist: jinja2>=3.0; extra == 'all'
Requires-Dist: langchain-core>=0.2; extra == 'all'
Requires-Dist: nest-asyncio>=1.6; extra == 'all'
Requires-Dist: ollama>=0.6; extra == 'all'
Requires-Dist: openai>=2.0; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: pinecone[asyncio]>=9.0; extra == 'all'
Requires-Dist: pymupdf4llm>=0.0.17; extra == 'all'
Requires-Dist: pypdf>=4.0; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: qdrant-client>=1.9; extra == 'all'
Requires-Dist: sqlalchemy>=2.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'all'
Requires-Dist: weaviate-client>=4.9; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.97; extra == 'anthropic'
Provides-Extra: cohere
Requires-Dist: cohere>=5.1.8; extra == 'cohere'
Provides-Extra: documents
Requires-Dist: openpyxl>=3.1; extra == 'documents'
Requires-Dist: pymupdf4llm>=0.0.17; extra == 'documents'
Requires-Dist: pypdf>=4.0; extra == 'documents'
Requires-Dist: python-docx>=1.1; extra == 'documents'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == 'gemini'
Provides-Extra: jupyter
Requires-Dist: ipython>=8.0; extra == 'jupyter'
Requires-Dist: nest-asyncio>=1.6; extra == 'jupyter'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: llm
Requires-Dist: anthropic>=0.97; extra == 'llm'
Requires-Dist: cohere>=5.1.8; extra == 'llm'
Requires-Dist: google-genai>=1.0; extra == 'llm'
Requires-Dist: ollama>=0.6; extra == 'llm'
Requires-Dist: openai>=2.0; extra == 'llm'
Provides-Extra: ollama
Requires-Dist: ollama>=0.6; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=2.0; extra == 'openai'
Provides-Extra: phoenix
Requires-Dist: arize-phoenix-otel>=0.6; extra == 'phoenix'
Provides-Extra: pinecone
Requires-Dist: pinecone[asyncio]>=9.0; extra == 'pinecone'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.9; extra == 'qdrant'
Provides-Extra: rag
Requires-Dist: asyncpg>=0.30; extra == 'rag'
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == 'server'
Requires-Dist: jinja2>=3.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'server'
Provides-Extra: sql
Requires-Dist: aiosqlite>=0.19; extra == 'sql'
Requires-Dist: greenlet>=3.0; extra == 'sql'
Requires-Dist: sqlalchemy>=2.0; extra == 'sql'
Provides-Extra: vectordb
Requires-Dist: pinecone[asyncio]>=9.0; extra == 'vectordb'
Requires-Dist: qdrant-client>=1.9; extra == 'vectordb'
Requires-Dist: weaviate-client>=4.9; extra == 'vectordb'
Provides-Extra: weaviate
Requires-Dist: weaviate-client>=4.9; extra == 'weaviate'
Description-Content-Type: text/markdown

# Grampus — Production-Grade Agentic AI Framework

<p align="center">
  <a href="https://pypi.org/project/grampus-ai/"><img src="https://img.shields.io/pypi/v/grampus-ai" alt="PyPI"/></a>
  <a href="https://pypi.org/project/grampus-ai/"><img src="https://img.shields.io/pypi/pyversions/grampus-ai" alt="Python"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/alireza1989/grampus" alt="License"/></a>
  <a href="https://github.com/alireza1989/grampus/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/alireza1989/grampus/ci.yml" alt="CI"/></a>
  <a href="https://codecov.io/gh/alireza1989/grampus"><img src="https://img.shields.io/codecov/c/github/alireza1989/grampus" alt="Coverage"/></a>
</p>

> As simple as CrewAI to start. As powerful as LangGraph for production.

Grampus is an open-source agentic AI framework built on [Dapr](https://dapr.io/)'s distributed runtime. It provides everything agents need to be production-ready — persistent memory, orchestration, safety guardrails, and full observability — while Dapr handles the hard infrastructure problems: durable state, pub/sub messaging, distributed locks, mTLS, and workflow checkpointing.

---

## Why Grampus

- **Production memory architecture.** Four complementary memory types (working, episodic, semantic, procedural) with SHA-256 provenance tracking, trust scoring, and injection detection. Memory poisoning attacks are blocked at write time, not detected after the fact.
- **Built-in safety, not bolted on.** A multi-layer safety pipeline intercepts every LLM call, tool call, and memory write. Prompt injection detection, PII redaction, per-agent action boundaries, and configurable YAML policies ship in the box.
- **Dapr infrastructure means zero distributed-systems boilerplate.** Swap your state backend from PostgreSQL to DynamoDB with a one-line YAML change. mTLS between agents is zero-configuration. Workflow checkpoints survive process crashes.

---

## Features

| | Feature | Description |
|---|---|---|
| 🧠 | **Four memory types** | Working (token-aware, auto-summarized), episodic (cross-session, temporally decayed), semantic (SPO facts, confidence-weighted), procedural (learned workflows) |
| 🔒 | **Memory security** | SHA-256 provenance on every write, trust scoring with temporal decay, injection detection, rate limiting, audit integrity verification |
| 🔀 | **ReAct + Graph orchestration** | Async graph engine with conditional routing, parallel branches, and checkpoint/restore. Pre-built LLM, Tool, Human, Conditional, and Subgraph nodes |
| 👥 | **Multi-agent crews** | Sequential, parallel, and hierarchical coordination. Distributed locks for shared state. Supervisor pattern with delegation |
| 📊 | **15-assertion eval framework** | Contains, regex, tool assertions, JSON schema, LLM-as-judge, semantic similarity, PII/injection safety, cost/latency/step limits. A/B prompt testing, quality baselines |
| 🛡️ | **Safety pipeline** | Multi-layer prompt injection detection (regex + heuristic, 3 strictness levels), PII detection for 6 entity types (log/redact/block), cost guards, action allowlists |
| 📡 | **OTEL observability** | Six custom span types with model, token, cost, and duration attributes. Prometheus metrics endpoint. Immutable event log. Anomaly detection |
| 📦 | **Sandboxed tool execution** | Docker container sandbox with resource limits and network isolation. Subprocess fallback for development. LLM-generated Python executes safely |
| 🔌 | **MCP protocol support** | JSON-RPC 2.0 MCP client discovers and invokes any MCP-compatible tool server. External tool results tagged with provenance |
| ⚡ | **CLI developer experience** | `grampus init` scaffolds a runnable project in under 10 seconds. `grampus dev` launches everything with hot-reload, live cost display, and trace streaming |

---

## Architecture

Grampus is organized in nine layers, each building on the one below it:

```mermaid
graph TD
    A[Dapr Runtime<br/>state · pub/sub · workflows · actors · mTLS · OTEL] --> B
    B[Core<br/>config · errors · logging · types · DI · model clients] --> C
    B --> D
    B --> E
    C[Memory<br/>working · episodic · semantic · procedural · security] --> F
    D[Tools<br/>registry · MCP client · sandbox · executor · boundaries] --> F
    E[Observability<br/>OTEL spans · Prometheus · event log · behavior monitor]
    F[Orchestration<br/>graph engine · model router · cost tracker · AgentRunner · Crew] --> G
    G[Safety<br/>injection detection · PII · action guard · YAML policies] --> H
    H[Evaluation<br/>eval suites · assertions · prompt versions · quality baselines] --> I
    I[CLI<br/>init · run · eval · memory · cost · dev]
```

---

## Quickstart

**Prerequisites:** Python 3.12+, Docker, [uv](https://docs.astral.sh/uv/)

```bash
# Install Grampus
pip install grampus-ai[anthropic]

# Scaffold a new project
grampus init hello-agent
cd hello-agent

# Start local infrastructure (Dapr + PostgreSQL + Redis)
docker compose up -d
```

Write your agent in `agent.py`:

```python
import asyncio
import os

from grampus.core.models.anthropic import AnthropicClient
from grampus.core.types import AgentDefinition
from grampus.orchestration.runner import AgentRunner, RunnerConfig
from grampus.tools.executor import ToolExecutor
from grampus.tools.registry import ToolRegistry


def create_runner() -> AgentRunner:
    client = AnthropicClient(api_key=os.environ["GRAMPUS_MODEL__ANTHROPIC_API_KEY"])
    registry = ToolRegistry()

    # Register a tool with the decorator API
    @registry.tool(name="get_weather", description="Get the current weather for a city")
    async def get_weather(city: str) -> str:
        return f"Sunny, 22°C in {city}"  # replace with real API call

    executor = ToolExecutor(registry)
    config = RunnerConfig(max_iterations=5, enable_memory=True)
    return AgentRunner(model_client=client, tool_executor=executor, config=config)


def create_agent_def() -> AgentDefinition:
    return AgentDefinition(
        name="weather-agent",
        model="claude-sonnet-4-6",
        system_prompt="You are a helpful assistant. Use tools when needed.",
        tools=["get_weather"],
    )


async def main() -> None:
    runner = create_runner()
    agent = create_agent_def()

    result = await runner.run(agent, "What's the weather in Tokyo?", session_id="s1")
    print(f"Output: {result.output}")
    print(f"Cost:   ${result.token_usage.cost_usd:.6f}")


if __name__ == "__main__":
    asyncio.run(main())
```

```bash
# Run the agent
grampus run agent.py --input "What's the weather in Tokyo?"
# Output: The current weather in Tokyo is sunny with a temperature of 22°C.
# Cost:   $0.000021
```

---

## Installation

```bash
# Core framework
pip install grampus-ai

# With Anthropic support (Claude)
pip install grampus-ai[anthropic]

# With OpenAI support (GPT-4o, o1)
pip install grampus-ai[openai]

# Both providers
pip install grampus-ai[all]
```

**Using uv (recommended):**

```bash
uv add grampus-ai[anthropic]
```

Requires Python 3.12 or 3.13. Dapr 1.17+ and Docker are required for memory persistence and sandboxed tool execution.

---

## CLI

| Command | Description |
|---|---|
| `grampus init <name>` | Scaffold a new agent project with infrastructure, config, and example code |
| `grampus run <agent.py>` | Run an agent in interactive REPL mode or single-shot with `--input` |
| `grampus eval <suite.py>` | Execute an evaluation suite; exit non-zero if pass rate falls below `--fail-under` |
| `grampus memory inspect <agent_id>` | Display an agent's current memory state across all four memory types |
| `grampus cost` | Show token usage and cost summary for recent sessions |
| `grampus dev` | Start everything in watch mode with hot-reload, live cost tracking, and trace streaming |

All commands support `--help`.

---

## Documentation

Full documentation is at **[alireza1989.github.io/grampus](https://alireza1989.github.io/grampus)**:

- [Getting Started](https://alireza1989.github.io/grampus/getting-started/quickstart/) — 5-minute quickstart
- [Single-Agent Guide](https://alireza1989.github.io/grampus/guides/single-agent/) — Tools, memory, and safety
- [Multi-Agent Crews](https://alireza1989.github.io/grampus/guides/multi-agent-crew/) — Parallel and hierarchical coordination
- [Memory Guide](https://alireza1989.github.io/grampus/guides/memory/) — Cross-session persistence and retrieval
- [Safety Guide](https://alireza1989.github.io/grampus/guides/safety/) — Injection detection, PII redaction, policies
- [Evaluation Guide](https://alireza1989.github.io/grampus/guides/evaluation/) — Testing agent behavior
- [Observability Guide](https://alireza1989.github.io/grampus/guides/observability/) — OTEL traces, metrics, event log
- [Deployment Guide](https://alireza1989.github.io/grampus/guides/deployment/) — Docker and Kubernetes

---

## Contributing

We welcome contributions. Grampus is built with strict TDD — every change begins with a failing test.

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, code conventions, the TDD requirement, conventional commit format, and guides for extending each layer of the framework.

Quick start for contributors:

```bash
git clone https://github.com/alireza1989/grampus
cd grampus-agentic-platform
uv sync
docker compose up -d
uv run pytest
```

---

## License

Grampus is released under the [MIT License](LICENSE).

---

## Acknowledgements

Grampus stands on the shoulders of:

- **[Dapr](https://dapr.io/)** — the distributed application runtime that powers Grampus's infrastructure layer
- **[Anthropic](https://www.anthropic.com/)** — for Claude and for advancing research into safe, capable AI systems
- **[Model Context Protocol](https://modelcontextprotocol.io/)** — the open standard for tool integration that Grampus implements
- **[pgvector](https://github.com/pgvector/pgvector)** — PostgreSQL extension enabling vector similarity search without a separate database
- **[Pydantic](https://docs.pydantic.dev/)**, **[structlog](https://www.structlog.org/)**, **[OpenTelemetry](https://opentelemetry.io/)** — foundational libraries throughout the framework