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