Vritti

Stop AI agents from repeating the same mistakes.

Vritti captures failures, analyzes patterns, and prevents AI coding assistants from making the same errors twice.

The Problem

AI coding assistants make the same mistakes repeatedly:

• Deploy with wrong image tags
• Forget to run migrations
• Use incorrect API endpoints
• Skip prerequisite steps

Each mistake wastes developer time debugging and fixing the same issue.

The Solution

Vritti learns from failures and blocks similar actions before they fail:

1. Capture: AI agent fails (wrong command, missing dependency, etc.)
2. Analyze: LLM generates root cause and solution
3. Prevent: Next time the agent tries something similar, Vritti says "Don't do that, do this instead"

Quick Start

Prerequisites

• Python 3.11+
• KyroDB server running (ports 50051 for text, 50052 for images)

Installation

pip install -r requirements.txt

Configuration

cp .env.production.example .env

Edit .env and set:

• KYRODB_TEXT_HOST - Your KyroDB instance for vector storage
• LLM_OPENROUTER_API_KEY - LLM API key for reflection generation
• EMBEDDING_OFFLINE_MODE=false - Keep online bootstrap enabled by default
• SERVICE_REQUIRE_LLM_REFLECTION - Set true in production to fail fast when LLM config is missing/placeholder

Run

uvicorn src.main:app --port 8000

API documentation: http://localhost:8000/docs

Usage

1. Capture a Failure

When your AI agent makes a mistake, send it to Vritti:

curl -X POST http://localhost:8000/api/v1/capture \
  -H "X-API-Key: em_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "episode_type": "failure",
    "goal": "Deploy application to production",
    "actions_taken": ["kubectl apply -f deployment.yaml"],
    "error_trace": "ImagePullBackOff: image not found in registry",
    "error_class": "resource_error",
    "tool_chain": ["kubectl"],
    "resolution": "Fixed image tag to match pushed version"
  }'

Vritti stores this failure and queues reflection generation.

2. Check Before Acting

Before your AI agent does something risky, ask Vritti:

curl -X POST http://localhost:8000/api/v1/reflect \
  -H "X-API-Key: em_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "proposed_action": "kubectl apply -f deployment.yaml",
    "goal": "Deploy to production",
    "tool": "kubectl",
    "context": "Deploying version 1.2.3",
    "current_state": {"cluster": "production"}
  }'

Response:

{
  "recommendation": "block",
  "confidence": 0.92,
  "rationale": "Similar action failed: ImagePullBackOff error. Verify image exists in registry first.",
  "suggested_action": "Verify image exists in registry before applying",
  "matched_failures": [],
  "hints": [],
  "relevant_skills": [],
  "search_latency_ms": 12.4,
  "total_latency_ms": 18.9
}

Recommendations:

• block: Don't do this, it will fail
• rewrite: Do this differently (suggestion provided)
• hint: Be careful, check these things first
• proceed: No known issues, go ahead

3. Search Past Failures

Find similar problems you've solved before:

curl -X POST http://localhost:8000/api/v1/search \
  -H "X-API-Key: em_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "kubectl deployment image pull error",
    "k": 5,
    "min_similarity": 0.7
  }'

How It Works

Storage

Episodes stored in KyroDB (vector database) with 384-dimensional embeddings.

Matching

Combines semantic similarity with precondition matching:

• "Using kubectl" + "production cluster" = high match
• Generic errors = low match

LLM Analysis

Uses OpenRouter API (Grok, Deepseek, or other models) to generate:

• Root cause analysis
• Specific resolution steps
• Preconditions that must match for this solution to apply

Caching

LLM semantic precondition validation results are cached for 5 minutes to reduce cost and latency.

Development

Run Tests

# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_gating.py -v

# With coverage
pytest tests/ --cov=src --cov-report=html

Code Quality

# Format
black src/ tests/

# Lint
ruff check src/ --fix

# Type check
mypy src/

Performance Targets

Recent local benchmark snapshots (KyroDB-backed):

• Ingestion load (1000 req, 100 concurrency): ~1121 RPS, ~132ms P99
• Sustained mixed load (30s, 200 concurrency): ~899 RPS, ~357ms overall P99

Run tests/load/test_load.py and tests/load/test_load_1000_rps.py for your environment.

Configuration

Key settings in .env:

# Required
KYRODB_TEXT_HOST=localhost
KYRODB_TEXT_PORT=50051
LLM_OPENROUTER_API_KEY=sk-or-v1-...
SERVICE_REQUIRE_LLM_REFLECTION=false

# Optional
LOG_LEVEL=INFO
SEARCH_LLM_VALIDATION_ENABLED=true
SEARCH_LLM_SIMILARITY_THRESHOLD=0.92
EMBEDDING_OFFLINE_MODE=false

Full configuration options in src/config.py.

Air-gapped deployment:

• Set EMBEDDING_OFFLINE_MODE=true only after preloading model caches.
• If offline mode is enabled and cached models are missing, startup fails fast with actionable instructions.

API Authentication

Generate API keys:

python scripts/generate_api_key.py

Include in requests:

curl -H "X-API-Key: em_live_..." http://localhost:8000/api/v1/search

Health Checks

# Liveness (is the service alive?)
curl http://localhost:8000/health/liveness

# Readiness (is the service ready to accept traffic?)
curl http://localhost:8000/health/readiness

# Comprehensive health check
curl http://localhost:8000/health

Production Deployment

1. Set environment variables in .env
2. Start KyroDB instances (text on port 50051, image on port 50052)
3. Start with uvicorn src.main:app --host 0.0.0.0 --port 8000
4. Configure reverse proxy (nginx/caddy) for HTTPS

Documentation

• docs/ARCHITECTURE.md - System design
• docs/API_GUIDE.md - API integration guide
• docs/KYRODB_SETUP.md - KyroDB configuration
• docs/LLM_CONFIGURATION.md - LLM tier configuration
• docs/VRITTI_INTEGRATION_GUIDE.md - Integration examples

License

Business Source License 1.1 - Free for non-production use.
Commercial use requires license: kishan@kyrodb.com

Built with: Python 3.9+ | FastAPI | KyroDB | OpenRouter