Evolv

Your prompts, but smarter every week.

Evolv treats prompts like genetic sequences—extracting their DNA, tracking mutations, and understanding lineage. Transform prompt sprawl into organized, versioned templates with automatic family detection and evolution tracking.

Try it live: https://tryevolv.vercel.app/

What It Does

Evolv ingests prompts from production systems, extracts their structural DNA (variables, constraints, instructions), clusters them into semantic families, and tracks how they evolve over time. It provides:

• Automatic DNA Extraction – Parse structure, detect variables, extract instructions
• Semantic Clustering – Group similar prompts into families using embeddings
• Template Synthesis – LLM-powered canonical template extraction
• Evolution Tracking – Monitor mutations, track lineage, detect drift
• Portkey Integration – Ingest from observability logs, orchestrate LLM calls

Architecture

System Overview

The system follows a monorepo structure with three interfaces (Web, CLI, API) connecting to a central engine that orchestrates ML pipelines and external dependencies. Portkey serves a dual role — as an LLM gateway for DNA extraction and template synthesis, and as a data source for ingesting production prompt logs.

graph TD
    subgraph Interfaces
        Web[Next.js Dashboard]
        CLI[Click CLI]
    end

    subgraph Backend Core
        API[FastAPI REST Service]
        Engine[Evolv Core Engine]
    end

    subgraph External Dependencies
        DB[(SQLite / SQLAlchemy)]
        Embed[sentence-transformers<br>all-MiniLM-L6-v2]
        PortkeyGW[Portkey SDK<br>LLM Gateway]
        PortkeyObs[Portkey Observability<br>Log Storage]
    end

    ProdApp[Production Applications]

    Web -->|HTTP| API
    CLI -->|CLI Commands| API
    API --> Engine

    Engine <-->|Read/Write Models| DB
    Engine <-->|Generate 384D Vectors| Embed

    Engine -->|Extract DNA & Synthesize| PortkeyGW
    PortkeyGW -->|Route/Fallback| LLMs((LLM Providers:<br>OpenAI/Anthropic))

    ProdApp -->|Log Prompts| PortkeyObs
    PortkeyObs -->|Ingest Logs| Engine

Loading

Core Data Pipeline

Every prompt passes through a multi-stage ML pipeline. Raw prompts are deduplicated, structurally parsed via LLM, embedded into 384-dimensional vectors, and clustered into semantic families using density-based clustering.

graph LR
    A[Raw Prompts] -->|File/Log Upload| B(Ingestion)
    B -->|SHA-256 + SimHash| C(Deduplication)
    C -->|LLM via Portkey| D(DNA Extraction)
    D -->|sentence-transformers| E(Embedding)
    E -->|HDBSCAN| F(Clustering)
    F -->|Semantic Grouping| G(Family Assignment)
    G -->|LLM via Portkey| H(Template Synthesis)
    H -->|Lineage Tracking| I(Evolution Tracking)

Loading

Portkey Integration

Portkey has a bidirectional relationship with Evolv — it acts as the entry point for production data ingestion, and serves as the outbound gateway for Evolv's internal LLM tasks (DNA extraction, template synthesis).

graph TD
    subgraph Data Source Flow
        App[Production App] -->|Sends Execution Logs| P_Obs[Portkey Observability]
        P_Obs -->|Ingested via API| Evolv_Ingest[Evolv Ingestion Engine]
    end

    subgraph LLM Gateway Flow
        Evolv_DNA[Evolv DNA/Template Engine] -->|API Call| P_SDK[Portkey SDK]
        P_SDK -->|Provider Routing & Fallbacks| Router{Portkey Router}
        Router -->|Primary| OpenAI[OpenAI]
        Router -->|Fallback| Anthropic[Anthropic]
        OpenAI -->|Response| Evolv_DNA
        Anthropic -->|Response| Evolv_DNA
    end

Loading

How Evolv Differs from RAG

Evolv uses the same embedding technology as RAG but for a fundamentally different purpose. RAG retrieves relevant document chunks to augment LLM generation at query time. Evolv clusters prompt embeddings to discover structural families and track how prompts mutate over time. Same vectors, completely different goal.

graph TD
    subgraph Standard RAG Pipeline
        R1[Documents] --> R2[Chunking]
        R2 --> R3[Embed]
        R3 --> R4[(Vector DB)]
        R5[User Query] --> R6[Retrieve Relevant Docs]
        R4 --> R6
        R6 --> R7[Augment Prompt]
        R7 --> R8[LLM Generation]
    end

    subgraph Evolv Pipeline
        E1[Raw Prompts] --> E2[Extract Structural DNA]
        E2 --> E3[Embed]
        E3 --> E4[Cluster via HDBSCAN]
        E4 --> E5[Assign to Families]
        E5 --> E6[Synthesize Canonical Templates]
        E6 --> E7[Track Lineage & Evolution]
    end

Loading

Monorepo Structure

apps/
  api/       → FastAPI REST service
  cli/       → Command-line interface (Click)
  web/       → Next.js dashboard and log generator
packages/
  ingestion/ → File parsing, Portkey log fetching
  dna/       → DNA extraction logic
  clustering/→ Embedding + HDBSCAN clustering
  storage/   → SQLAlchemy models + DB operations

Key Technologies

• ML/NLP: sentence-transformers (embeddings), HDBSCAN (clustering)
• Database: SQLAlchemy with SQLite (upgradeable to PostgreSQL)
• LLM: Portkey SDK with automatic fallback
• Deduplication: SHA-256 (exact) and SimHash (near-duplicates)

Quick Start

Prerequisites

• Python 3.11+
• UV package manager
• Node.js 18+ (for web app)

Installation

# Install Python dependencies
uv sync

# Initialize database (required on first run)
uv run python scripts/init_db.py

# Install web app dependencies
cd apps/web
npm install

Run the API

uv run uvicorn apps.api.main:app --reload

API available at http://localhost:8000 with docs at /docs.

Use the CLI

uv run genome ingest examples/prompt.csv  # Ingest prompts
uv run genome run                        # Process pending
uv run genome families                  # List families
uv run genome evolve <prompt_id>        # Show evolution chain
uv run genome stats                     # System statistics

Run the Web App

cd apps/web
npm run dev

Visit http://localhost:3000 for the dashboard and log generator.

Environment Variables

Backend (API/CLI)

Copy .env.example to .env:

PORTKEY_API_KEY=your_key_here
DATABASE_URL=sqlite:///./data/genome.db

Web App

Copy apps/web/.env.example to apps/web/.env.local:

NEXT_PUBLIC_PORTKEY_API_KEY=your_portkey_api_key
NEXT_PUBLIC_PORTKEY_PROVIDER=your_provider_id  # Optional
NEXT_PUBLIC_MOCK_MODE=false
NEXT_PUBLIC_API_URL=http://localhost:8000  # Default

Web App Features

The web application provides:

• Dashboard – Overview of prompts, families, and templates
• Log Generator – Generate prompt logs for Portkey observability
• Family Explorer – Browse and analyze prompt families
• Prompt Details – View DNA structure and evolution lineage

Try it live: https://tryevolv.vercel.app/

Logs generated are automatically sent to Portkey observability and can be ingested by the Evolv system.

Why This Matters

Prompts are production infrastructure. They evolve, mutate, and accumulate technical debt. Evolv makes them observable, versioned, and governable.

API Endpoints

Main endpoints:

• POST /ingest – Upload file (JSON/CSV/TXT) and process prompts
• POST /ingest/portkey – Trigger Portkey ingestion
• GET /families – List all families
• GET /families/{id} – Get family details with members and template
• GET /prompts – List prompts
• GET /prompts/{id}/lineage – Get evolution chain
• POST /process – Trigger batch processing
• GET /stats – System statistics

Visit /docs for interactive API documentation (Swagger UI).

Additional Documentation

• docs/ml-algorithms.md – ML core algorithms and pipeline explanation
• docs/database-integration.md – Database integration architecture and design

---

Built on Portkey

Team

This project won first prize at the Portkey AI Builder Challenge and was built by:

• Ashutosh Jha
• Dhanush U
• Ravjot Singh