CypherPilot — AI-Powered Quality Engineering Platform

CypherPilot is an AI-augmented quality engineering platform that helps QA engineers and SDETs analyze requirements, generate API test suites, and diagnose automation failures — using AI as an accelerator, not a crutch.

Created by Cypher Morgan

Live demo: cyphermorgan.github.io/cypherpilot

Note: The GitHub Pages site is a static UI preview. API features require a running backend.

What's New

See the full Changelog for the complete release history.

Latest: v0.6.0 — Webhooks & Callbacks: user-managed endpoints with HMAC-signed outbound delivery, retry with backoff, test pings, and a management page. Read more.

Features

Module	Status	Description
User Authentication	✅ Working	Register, login, JWT tokens, role-based access (admin/user/viewer)
Teams	✅ Working	Create teams, invite members, manage roles, collaborate on analysis sessions
Requirement Analysis	✅ Working	Upload product requirements, get structured test cases, boundary values, and edge cases via AI. Browse past sessions.
API Test Generation	✅ Working	Paste an OpenAPI spec, get ready-to-run pytest test suites generated by AI. Browse past sessions.
Failure Analysis	✅ Working	Analyze CI/CD logs, stack traces, and error output for AI-powered root cause detection. Export as Markdown or JSON. Browse past sessions.

Quick Start

Choose one of two ways:

⚡ One-command install (no Docker required)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/CypherMorgan/cypherpilot/main/scripts/install.sh | bash

What it does (visible step-by-step):

Checks prerequisites (Python 3.11+, Node.js, git)
Clones the repo into ~/.cypherpilot
Creates a Python virtual environment and installs all dependencies
Builds the frontend SPA
Sets up SQLite database (zero config — no PostgreSQL needed)
Creates a cypherpilot shell alias and a cypherpilot-uninstall alias

Start: cypherpilot then open http://localhost:8000

Uninstall: cypherpilot-uninstall — removes venv, files, aliases, nothing left behind.

⚡ One-command install (no Docker required)

Windows:

irm https://raw.githubusercontent.com/CypherMorgan/cypherpilot/main/scripts/install.ps1 | iex

Or double-click %USERPROFILE%\.cypherpilot\start.bat after installation.

Uninstall: Double-click %USERPROFILE%\.cypherpilot\uninstall.bat

Docker (alternative — requires Docker Desktop)

docker compose up --build

Service	URL
Backend API	http://localhost:8000
API Docs	http://localhost:8000/docs
Frontend	http://localhost:3000

3. Try it

# Requirement analysis
curl -X POST http://localhost:8000/api/v1/requirements/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "Users must be able to reset their password via email."}'

# API test generation
curl -X POST http://localhost:8000/api/v1/openapi/analyze \
  -H "Content-Type: application/json" \
  -d '{"spec": "<your-openapi-spec-as-json-string>", "spec_format": "json"}'

# Failure analysis
curl -X POST http://localhost:8000/api/v1/failures/analyze \
  -H "Content-Type: application/json" \
  -d '{"content": "FAILED test_login - AssertionError: assert 401 == 200", "source_type": "ci_log"}'

Architecture

┌────────────────────────────────────────────────────────────────┐
│                    Application Layer                           │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  AI Features: Requirement Analysis,                      │  │
│  │  API Test Generation, Failure Analysis                   │  │
│  └────────────────────────┬─────────────────────────────────┘  │
│                           │ uses                               │
│  ┌────────────────────────▼──────────────────────────────────┐ │
│  │  AI Infrastructure                                        │ │
│  │  ┌──────────────┐  ┌─────────────┐  ┌──────────────────┐  │ │
│  │  │   Provider   │  │   Prompt    │  │   Response       │  │ │
│  │  │   Registry   │  │   Manager   │  │   Validator      │  │ │
│  │  └──────┬───────┘  └─────────────┘  └──────────────────┘  │ │
│  └─────────┼─────────────────────────────────────────────────┘ │
└────────────┼───────────────────────────────────────────────────┘
             │
┌────────────▼───────────────────────────────────────────────────┐
│                   Infrastructure Layer                         │
│  ┌──────────────────┐  ┌──────────────────┐                    │
│  │  OpenRouter      │  │  Ollama          │  (more to come)    │
│  │  (cloud)         │  │  (local/offline) │                    │
│  └──────────────────┘  └──────────────────┘                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  PostgreSQL 16 / SQLAlchemy 2.0 / Alembic / FastAPI      │  │
│  │  React + Vite / TanStack Query / Tailwind CSS            │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

Key Design Decisions

Provider-agnostic AI layer — business modules never know which provider is used. Add a provider = write one adapter class. ADR-001
Prompt templates as versioned Markdown files — no hardcoded prompt strings in Python. Edit prompts without code changes. ADR-002
Feature-first modular architecture — each business capability is an independent module with strict no-cross-import rules.
Async-first — FastAPI async endpoints, SQLAlchemy 2.0 async sessions, httpx for provider communication.
Single-table embedded JSONB schema — sessions, inputs, and outputs in one analysis_sessions table. Simple, fast, no complex joins. ADR-004

Project Structure

app/
├── ai/                         # AI infrastructure layer
│   ├── models.py               # AIRequest, AIResponse, TokenUsage
│   ├── protocol.py             # AIProvider Protocol (abstract interface)
│   ├── registry.py             # ProviderRegistry (factory + lifecycle)
│   ├── prompt_manager.py       # PromptManager (filesystem, Jinja2, caching)
│   ├── response_validator.py   # JSON response parsing & Pydantic validation
│   └── providers/
│       ├── openrouter.py       # OpenRouter adapter
│       └── ollama.py           # Ollama adapter
├── api/                        # REST API routes & dependency injection
├── infrastructure/             # Database engine, models, repositories
├── modules/                    # Business feature modules
│   ├── auth/                   # User authentication (JWT, bcrypt, RBAC)
│   ├── teams/                  # Team management & membership
│   ├── requirement_analysis/   # Requirement → test case generation
│   ├── api_test_generation/    # OpenAPI spec → pytest suite generation
│   └── failure_analysis/       # CI/CD failure → root cause analysis
├── middleware/                 # Request ID, structured logging
├── config.py                   # Pydantic-settings configuration
├── exceptions.py               # Domain exception hierarchy
├── logging_.py                 # structlog configuration
└── main.py                     # FastAPI application factory

frontend/                       # React + Vite + TypeScript SPA
├── src/
│   ├── modules/                # Feature pages & components
│   ├── components/             # Shared UI components
│   ├── services/               # API client (TanStack Query)
│   └── layouts/                # App shell, sidebar navigation

prompts/                        # AI prompt templates (versioned Markdown)
├── analysis/
│   ├── requirement-analysis/v1/
│   │   ├── system.md           # System instructions (Jinja2)
│   │   └── examples.md         # Few-shot examples
│   └── failure-analysis/v1/
│       ├── system.md           # System instructions (Jinja2)
│       └── examples.md         # Few-shot examples
└── shared/v1/                  # Shared prompt components

scripts/
├── install.sh                  # Linux/macOS install & uninstall
└── install.ps1                 # Windows install & uninstall

docs/
├── adr/                        # Architecture Decision Records
├── vision.md                   # Product vision
└── development.md              # Development guide

Development

Running locally (without Docker)

# Backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Running tests

# Backend (all 293+ tests)
uv run pytest -v

# Frontend
cd frontend && npm run test

# Type checking
uv run mypy app

# Linting
uv run ruff check

Tech stack

Layer	Technology
Backend	Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
Database	PostgreSQL 16 (prod), SQLite (tests via aiosqlite)
AI	Ollama (local), OpenRouter (cloud)
Frontend	React 19, TypeScript, Vite, TanStack Query, Tailwind CSS
Infrastructure	Docker Compose, Alembic migrations

Roadmap

Release	Focus	Status
v0.1.0	Foundation: backend, database, Docker, AI infra	✅ Done
v0.2.0	Requirement Analysis module	✅ Done
v0.3.0	API Test Generation module	✅ Done
v0.4.0	Automation Failure Analysis module	✅ Done
v0.4.1	Export & Share (Markdown/JSON download, clipboard copy)	✅ Done
v0.4.2	Session History Page — browse past analyses, summaries, click to details	✅ Done
v0.4.3	CI Log Presets — one-click example failure scenarios for demo/learning	✅ Done
v0.4.4	Requirement Analysis Presets — real-world product requirement examples	✅ Done
v0.4.5	API Test Generation Presets — real-world OpenAPI spec examples	✅ Done
v0.4.6	Session Cleanup & Retention — delete button + configurable retention policy	✅ Done
v0.4.7	Multi-Artifact Failure Analysis — file upload (screenshots, page source, JSON logs)	✅ Done
v0.4.8	Quality-of-Life Polish — keyboard shortcuts, elapsed timer, session search/filter, dashboard fix, requirement export fix	✅ Done
v0.4.9	Usability & Consistency — AI Provider settings UI, shared export/session-list components, friendlier error messages with retry	✅ Done
v0.5.0	Multi-User & Teams — authentication, JWT tokens, user management, team workspaces, RBAC, session sharing	✅ Done
v0.5.1	Provider Resilience — retry with backoff, fallback provider chain, health dashboard, better error messages	✅ Done
v0.5.2	Audit Log & Activity Feed — platform event logging, paginated timeline, team/user/action filtering	✅ Done
v0.5.3	Analysis Comparison — side-by-side diff of analysis results across sessions	✅ Done
v0.5.4	Batch Analysis — run failure analysis against multiple log files at once	✅ Done
v0.5.5	Notifications & Animated Logo — real-time alerts, terminal-style animated logo	✅ Done
v0.5.6	Templates — reusable analysis templates for common failure patterns	✅ Done
v0.5.7	Rate Limiting — per-user and per-team API rate limiting	✅ Done
v0.5.8	Session Export — download sessions as Markdown, JSON, or CSV	✅ Done
v0.5.9	Dashboard & Usage Analytics — personal stats, success rate, 14-day activity chart	✅ Done
v0.6.0	Webhooks & Callbacks — HMAC-signed outbound delivery, retry with backoff, test pings, management page	✅ Done
v0.6.x	CI/CD Integration & Notifications — Slack/email alerts, GitHub/GitLab integration	🔜 Planned
v0.7.x	Trends & Prompt Studio — historical trend analysis, prompt versioning UI, A/B prompt comparison	🔜 Planned
v0.8.x	Plugins & Enterprise — plugin SDK, SSO/SAML, audit logs, team billing	🔜 Planned

Deployment

GitHub Pages (Frontend UI)

The frontend is automatically deployed to GitHub Pages on every push to main via the deploy-pages.yml workflow.

URL	Notes
`https://cyphermorgan.github.io/cypherpilot/`	Live demo — static UI preview
Backend API	Requires a separate deployment (e.g. Railway, Fly.io, or your own server)

To deploy the backend, set VITE_API_BASE_URL in the Pages workflow to your backend URL.

Backend (Docker)

For production deployment of the full stack (backend + database):

cp .env.example .env
# Edit .env with real secrets and your AI provider key
docker compose up --build -d

License

MIT — see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.github/workflows		.github/workflows
alembic		alembic
app		app
docs		docs
frontend		frontend
prompts/analysis		prompts/analysis
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
opencode.jsonc		opencode.jsonc
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

CypherPilot — AI-Powered Quality Engineering Platform

What's New

Features

Quick Start

⚡ One-command install (no Docker required)

⚡ One-command install (no Docker required)

Docker (alternative — requires Docker Desktop)

3. Try it

Architecture

Key Design Decisions

Project Structure

Development

Running locally (without Docker)

Running tests

Tech stack

Roadmap

Deployment

GitHub Pages (Frontend UI)

Backend (Docker)

License

About

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

CypherPilot — AI-Powered Quality Engineering Platform

What's New

Features

Quick Start

⚡ One-command install (no Docker required)

⚡ One-command install (no Docker required)

Docker (alternative — requires Docker Desktop)

3. Try it

Architecture

Key Design Decisions

Project Structure

Development

Running locally (without Docker)

Running tests

Tech stack

Roadmap

Deployment

GitHub Pages (Frontend UI)

Backend (Docker)

License

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages