MANTIS

Cost-aware observability for AI agents: ingest structured traces, enforce in-memory budgets before the next LLM call, build causal graphs, and explore runs in a Next.js dashboard.

MeshFix/
├── mantis/          # FastAPI API, RCA engine, Celery worker
├── mantis-sdk/      # Python SDK (spans, cost math, BudgetGuard)
├── frontend/        # Next.js dashboard
├── examples/        # Runnable integration samples
└── docker-compose.yml

Quickstart (local)

1. API + SQLite (fastest)

cd mantis
python -m venv .venv
# Windows: .venv\Scripts\activate
pip install -r requirements.txt pydantic-settings
pip install -e ../mantis-sdk
cp .env.example .env
uvicorn main:app --reload --port 8080

Bootstrap a project and API key:

curl -s -X POST http://127.0.0.1:8080/v1/projects \
  -H "Content-Type: application/json" \
  -H "X-Admin-Secret: YOUR_MANTIS_ADMIN_SECRET" \
  -d '{"name":"demo"}'

Use the returned api_key (mt_...) for ingest and the SDK.

2. Full stack (Postgres + Redis + worker + UI)

cp mantis/.env.example mantis/.env
docker compose up --build

Service	URL
API	http://localhost:8080
Dashboard	http://localhost:3000
Metrics	http://localhost:8080/metrics

3. Instrument your agent

pip install -e ./mantis-sdk

from mantis_sdk import MantisClient, span

client = MantisClient(api_key="mt_...", base_url="http://127.0.0.1:8080")

with client.trace(agent_id="refund-bot", metadata={"env": "dev"}) as session:
    with span("fetch_ticket", input={"ticket_id": "TKT-1"}) as step:
        step.set_output({"ok": True})

See examples/ for OpenAI, LangChain, and multi-agent patterns.

Python SDK

Package: mantis-sdk (README)

Feature	Module
Client + background flush	MantisClient
Manual spans	span(), trace_session()
Integer cost math	compute_cost_microdollars()
OpenAI	mantis_sdk.openai.wrap_openai
LangChain	MantisLangChainHandler

Environment: MANTIS_API_KEY, MANTIS_BASE_URL (default http://127.0.0.1:8080).

Dashboard

cd frontend
npm install
echo "NEXT_PUBLIC_MANTIS_API_URL=http://127.0.0.1:8080" > .env.local
npm run dev

Open http://localhost:3000 — paste your API key in Settings, then browse Runs.

HTTP API

All tenant routes require X-API-Key: mt_... or Authorization: Bearer mt_....

Method	Path	Auth	Description
GET	/health	—	Liveness
GET	/ready	—	DB + fixture readiness
GET	/metrics	—	Prometheus metrics
POST	/v1/projects	X-Admin-Secret	Create project + initial API key
POST	/v1/ingest	API key	Ingest agent trace JSON
GET	/v1/runs/{id}/graph	API key	Parent-child run DAG
POST	/v1/projects/{id}/security-scans	API key	Enqueue AgentShield scan

Development

cd mantis-sdk && python -m pytest tests/ -q
cd mantis && python -m pytest tests/ -q

CI runs the same suites on push via .github/workflows/ci.yml.

License

Hackathon / demo codebase — adjust licensing before commercial use.