blamr

Documentation

Install the blamr platform on your infrastructure, create an ingest API key, and connect agents via SDK or MCP. All paths are self-hosted — no cloud LLM required.

Prerequisites

RequirementWhen needed
Docker 24+Docker Compose stack
Node.js 20+Local dev, TypeScript SDK, sample agents
Python 3.10+MCP proxy, Python SDK, framework adapters
6+ GB RAMDocker stack with Ollama (~3 GB models on first pull)
LLM enrichment uses local Ollama only — nomic-embed-text (embeddings) and llama3.2:3b (blame reasons). No OpenAI or Anthropic keys required for the platform.

How monitoring works

Pipeline, blame logic, confidence gates, dashboard KPIs

Run full stack

Docker Compose — fastest path to production-like setup

Develop locally

Hot reload for API, ingest, workers, dashboard

Connect TypeScript

Emit CausalEdges from Node agents

Connect via MCP

Zero-code proxy for MCP tool servers

Installation — Docker Compose

Runs API, ingest, workers, dashboard, Postgres, ClickHouse, Redpanda, Valkey, and Ollama in one command.

Terminal
git clone https://github.com/prithvirajualluri/blamr && cd blamr
cp .env.docker.example .env
./scripts/docker-up.sh

Or manually:

Terminal
docker compose up --build -d
ServiceURLPurpose
Dashboardhttp://localhost:8080Operator UI (runs, blame graphs)
APIhttp://localhost:3000Auth, workspace, blame reports
Ingesthttp://localhost:3001/v1Agent telemetry — SDK target
Ollamahttp://localhost:11434Local embeddings + LLM
First run: open the dashboard → register a workspace → Settings → API & keys → create a key with ingest:write. You need this key to connect agents (see Connect agents).

Installation — Local development

For active development with hot reload on API, ingest, workers, and the web dashboard.

1. Clone and install

Terminal
git clone https://github.com/prithvirajualluri/blamr && cd blamr
cp .env.example .env
npm install

2. Start infrastructure

Terminal
docker compose up -d postgres clickhouse redpanda valkey ollama ollama-init
./scripts/init-clickhouse.sh

Wait for ollama-init to finish on first run (pulls models).

3. Start platform services

Terminal A — backend (API + ingest + workers):

Terminal A
./scripts/dev-backend.sh

Terminal B — dashboard:

Terminal B
npm run dev:web

Open http://localhost:8080/app for the operator console.

4. Run sample workflows (optional)

Terminal
cp samples/agents/.env.example samples/agents/.env
# Edit samples/agents/.env — set BLAMR_API_KEY from dashboard
./scripts/run-workflow.sh support

Installation — Kubernetes / Helm

Terminal
cd deploy/helm
helm dependency update
helm install blamr . -n blamr --create-namespace -f values-local.yaml

Chart includes API, ingest, workers, web, ClickHouse, Redpanda, Ollama, Postgres, and Valkey. See deploy/helm/README.md for production ingress and secrets.

Connect agents — API key setup

Agents send telemetry to the ingest service (:3001), not the dashboard API (:3000).

  1. Start blamr (Docker or local dev).
  2. Open dashboard → register → Settings → API & keys.
  3. Create key with scope ingest:write.
  4. Set BLAMR_API_KEY and BLAMR_ENDPOINT in your agent environment.

Connect agents — TypeScript SDK

Install

From monorepo
git clone https://github.com/prithvirajualluri/blamr && cd blamr
npm install
npm run build -w @blamr/types -w @blamr/sdk

Link in your agent project:

package.json
{
  "dependencies": {
    "@blamr/sdk": "file:../blamr/packages/sdk-ts",
    "@blamr/types": "file:../blamr/packages/types"
  }
}

Minimal usage

TypeScript
import { BlamrEmitter } from '@blamr/sdk';

const emitter = new BlamrEmitter(
  { workflowId: 'customer-support', agentId: 'intent_classifier' },
  process.env.BLAMR_API_KEY!,
  process.env.BLAMR_ENDPOINT ?? 'http://localhost:3001/v1',
);

emitter.startRun();
await emitter.emitEdge({
  from_agent: 'intent_classifier',
  to_agent: 'policy_lookup',
  confidence_in: 1.0,
  confidence_out: 0.92,
  intent_delta: 0.05,
  influence_score: 0.85,
  tokens_in: 120,
  tokens_out: 45,
  latency_ms: 800,
  model: 'llama3.2:3b',
  call_type: 'LLM call',
  input_preview: 'User question…',
  output_preview: 'Classified as billing…',
});
await emitter.completeRun({ businessFailed: false });

Automatic usage telemetry

When tokens_in, tokens_out, or cost_usd are omitted, the SDK estimates them from I/O previews and model pricing (default on). Set BLAMR_ENRICH_USAGE=0 to disable. Wrap Anthropic/OpenAI with wrapClient for exact provider usage on the next emitEdge.

VariableDefaultDescription
BLAMR_ENRICH_USAGEonEstimate tokens/cost from previews
BLAMR_ATTACH_PROVIDER_USAGEonAttach wrapped LLM usage to next edge

Dashboard Workflows → Instrumentation flags missing usage and other SDK integration issues.

Confidence gate (optional)

TypeScript
const emitter = new BlamrEmitter(
  {
    workflowId: 'incident-triage',
    agentId: 'alert_classifier',
    workflowConfig: {
      confidence_accept_level: 0.72,
      confidence_gate_mode: 'final', // or 'min'
    },
  },
  process.env.BLAMR_API_KEY!,
  process.env.BLAMR_ENDPOINT ?? 'http://localhost:3001/v1',
);

Connect agents — Python SDK

Terminal
pip install "git+https://github.com/prithvirajualluri/blamr.git#subdirectory=packages/sdk-py"

With BLAMR_ENRICH_USAGE=1 (default), emit_edge fills missing tokens and cost from previews. Optional: emitter.record_provider_usage(ProviderUsage(...)) before emit_edge for exact Anthropic usage.

Python
from blamr_sdk.client import BlamrEmitter

emitter = BlamrEmitter(
    "web-research",
    "orchestrator",
    api_key=os.environ["BLAMR_API_KEY"],
    endpoint=os.environ.get("BLAMR_ENDPOINT", "http://localhost:3001/v1"),
)
run_id = emitter.start_run()
emitter.emit_edge(
    from_agent="search_agent",
    to_agent="fetch_agent",
    model="claude-sonnet-4-6",
    confidence_out=0.85,
    input_preview="user query",
    output_preview="search results",
)
emitter.complete_run("success")

Connect agents — MCP proxy

Wrap any MCP server with zero code changes. The Python proxy intercepts tools/call and emits CausalEdges automatically.

There is no global blamr CLI. MCP integration uses adapters/mcp/blamr_proxy.py in the repo.

Stdio MCP server (local)

Terminal
export BLAMR_API_KEY=bk_live_...
export BLAMR_ENDPOINT=http://localhost:3001/v1
python3 adapters/mcp/blamr_proxy.py run \
  --workflow-id customer-support \
  --api-key "$BLAMR_API_KEY" \
  -- npx @modelcontextprotocol/server-filesystem /tmp

HTTP / SSE MCP server (remote)

Terminal
python3 adapters/mcp/blamr_proxy.py proxy \
  --workflow-id customer-support \
  --target https://your-mcp-server.example.com/mcp \
  --api-key "$BLAMR_API_KEY"

Every tool call emits a CausalEdge with call_type: MCP call, truncated I/O previews, and automatic run completion.

Connect agents — Framework adapters

FrameworkPath in repo
LangGraphadapters/langgraph/
CrewAIadapters/crewai/
AutoGenadapters/autogen/
MCPadapters/mcp/
LangGraph example
from blamr.adapters.langgraph import BlamrNode

graph.add_node("blamr_trace", BlamrNode(workflow_id="customer-support"))

All adapters require a running ingest endpoint and BLAMR_API_KEY.

Environment variables

VariableDefaultDescription
BLAMR_API_KEY—Ingest key with ingest:write scope
BLAMR_ENDPOINThttp://localhost:3001/v1Ingest base URL (not dashboard :3000)
BLAMR_LLM_BASE_URLhttp://localhost:11434/v1Ollama for sample agents / enrichment

Example samples/agents/.env:

.env
BLAMR_API_KEY=bk_live_xxxxxxxxxxxxxxxx
BLAMR_ENDPOINT=http://localhost:3001/v1
BLAMR_LLM_BASE_URL=http://localhost:11434/v1

Troubleshooting

ProblemFix
Dashboard empty after workflowWorkers not running — docker compose logs workers
Ingest 401Invalid or missing BLAMR_API_KEY
SDK hits wrong URLSet BLAMR_ENDPOINT to ingest (:3001/v1), not API (:3000)
Semantic drift errorsOllama not ready — curl http://localhost:11434/api/tags
Port conflicts on 3000/8080Stop local dev before docker compose up

Full reference: Causal monitoring guide · docs/INSTALL.md · docs/DEPLOYMENT.md