Grampus — Production-Grade Agentic AI Framework

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

Grampus is an open-source agentic AI framework built on Dapr'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

Architecture

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

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

# 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:

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())

# 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

# 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):

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

All commands support --help.

Documentation

Full documentation is at alireza1989.github.io/grampus:

• Getting Started — 5-minute quickstart
• Single-Agent Guide — Tools, memory, and safety
• Multi-Agent Crews — Parallel and hierarchical coordination
• Memory Guide — Cross-session persistence and retrieval
• Safety Guide — Injection detection, PII redaction, policies
• Evaluation Guide — Testing agent behavior
• Observability Guide — OTEL traces, metrics, event log
• Deployment Guide — Docker and Kubernetes

See ROADMAP.md for what's shipped and what's next.

Contributing

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

See 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:

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.

Acknowledgements

Grampus stands on the shoulders of:

• Dapr — the distributed application runtime that powers Grampus's infrastructure layer
• Anthropic — for Claude and for advancing research into safe, capable AI systems
• Model Context Protocol — the open standard for tool integration that Grampus implements
• pgvector — PostgreSQL extension enabling vector similarity search without a separate database
• Pydantic, structlog, OpenTelemetry — foundational libraries throughout the framework