Purple8-platform

Purple8 Platform

Enterprise-grade AI software development platform. Purple8 transforms natural-language requirements into production-ready applications by orchestrating 50+ specialised AI agents across a full software development lifecycle — from ideation through deployment.

What is Purple8?

Purple8 is a self-hosted, multi-agent AI builder. You describe what you want to build; the platform produces complete, working software — source code, database schemas, API specs, tests, Docker configs, CI/CD pipelines, and deployment scripts.

It is not a code-completion tool. It runs a structured pipeline of agents, each with a defined contract, that collaborate the same way a full engineering team would.

Recent Features

Brand Kit Builder (brand-kit sprint — March 2026)

The Interactive Builder now ships a first-class brand identity system:

Feature Detail
Brand Kit form Company name, logo upload (base64), primary & secondary colour pickers, 6 style vibes (clean / bold / playful / elegant / futuristic / minimal), font family selector
Design Preview tab Live <iframe> viewer with screen tabs, desktop / tablet / mobile viewport toggle, and brand token swatch bar
Brand-aware DesignAgent Injects === BRAND IDENTITY — MANDATORY CONSTRAINTS === block into every design prompt; renders real company name + logo <img> in preview_html
FrontendDevelopmentAgent brand contract Overrides app_name with company_name; seeds --color-primary, --color-secondary, --font-family-base CSS custom properties in every frontend prompt
Deployment docs in every ZIP DEPLOYMENT.md, SECRETS.md, docker-compose.prod.yml, DATABASE.md are injected into every generated project download via _inject_deployment_docs()

Monaco Copilot in HITL Editor (hitl sprint — March 2026)

The Human-in-the-Loop review panel now includes a full Copilot experience:

Feature Detail
useCopilotProvider.ts Monaco InlineCompletionsProvider composable — debounced cursor-context calls to POST /api/ide/copilot/edit/complete
MonacoCodeEditor.vue ✨ sparkle toggle button, 320 px IDECopilot side panel, showCopilot + hitlContext props, provider wired on mount
IDECopilot.vue hitlContext prop, HITL banner badge, context injected into all API calls
HITLReviewPanel.vue Passes hitlContext string to the editor for full pipeline awareness
/api/ide/copilot/* 8 edit actions (complete, suggest, refactor, explain, fix, optimize, document, test) + agent chat + streaming + quick-action shortcuts

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Purple8 Platform                         │
│                                                                 │
│  ┌────────────┐    ┌──────────────────┐    ┌─────────────────┐ │
│  │  Vue 3     │    │  FastAPI Gateway  │    │  Purple8 Graph  │ │
│  │  Frontend  │◄──►│  (REST + WS)      │◄──►│  (Knowledge     │ │
│  │  (Vite)    │    │  /api/v1/*        │    │   Graph + Vec)  │ │
│  └────────────┘    └────────┬─────────┘    └─────────────────┘ │
│                             │                                   │
│              ┌──────────────▼──────────────┐                   │
│              │       Agent Pipeline         │                   │
│              │  Phase 1: Conception         │                   │
│              │  Phase 2: Planning           │                   │
│              │  Phase 3: Implementation     │                   │
│              │  Phase 4: QA                 │                   │
│              │  Phase 5: Delivery           │                   │
│              └──────────────┬──────────────┘                   │
│                             │                                   │
│   ┌─────────────────────────▼──────────────────────────────┐   │
│   │               50+ Specialised Agents                    │   │
│   │  Core · AI/ML · Enterprise · Specialized · Advanced     │   │
│   └─────────────────────────┬──────────────────────────────┘   │
│                             │                                   │
│   ┌──────────────┬──────────▼──────────┬────────────────────┐  │
│   │  PostgreSQL  │       Redis          │   Purple8 Graph    │  │
│   │  (primary)   │  (sessions/cache)    │  (vectors/graph)   │  │
│   └──────────────┴─────────────────────┴────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

The 4-Layer Agent Architecture

Every agent implements the same four layers (via FourLayerMixin):

Layer Responsibility
1 — Purpose Parse requirements, validate input contract, set goals
2 — Memory Load relevant context from MemoryStore and Purple8 Graph
3 — Execution Generate output via LLM (with CoT streaming)
4 — Supervision Validate output contract, self-correct, emit learning signals

Agents also implement PDCA cycles (PDCAMixin) for continuous self-improvement and emit structured signals to the LearningEngine, which writes patterns back to the knowledge graph for future sessions.

Agent Catalogue

Core Agents (17) — run for every project

| Agent | Role | |——-|——| | IdeationAgent | Requirements analysis, BRD generation | | DesignAgent | UI/UX wireframes, design tokens | | ArchitectureAgent | System design, technology selection | | DatabaseAgent | Schema design, migrations | | BackendDevelopmentAgent | API implementation | | FrontendDevelopmentAgent | UI components | | APIDevelopmentAgent | OpenAPI specs, endpoint contracts | | DevelopmentAgent | Full-stack integration | | InfrastructureDevelopmentAgent | Docker, Kubernetes, Terraform | | DeploymentAgent | CI/CD, pipeline configs | | UnitTestAgent | Unit test suites | | SITAgent | System integration tests | | UATAgent | User acceptance tests | | ErrorAnalyzerAgent | Runtime error analysis and self-healing | | IntegrationAgent | Third-party service wiring | | CyberSecurityAgent | Security review, vulnerability scanning | | DataEngineeringAgent | Data pipelines, ETL |

AI/ML Agents (20)

RAGAgent · LLMOpsAgent · MachineLearningAgent · DataScienceAgent · NLPAgent · ComputerVisionAgent · TimeSeriesAgent · RecommenderAgent · GraphAnalyticsAgent · MultimodalAgent · SpeechAgent · RLAgent · EvaluationMetricsAgent · AIEngineeringAgent · AgenticWorkflowAgent · DocumentIntelligenceAgent · DashboardAgent · PromptEngineeringAgent · MLOpsAgent · AIEngineeringAgent

Specialized Agents (10)

DevOpsAgent · MobileAgent · ObservabilityAgent · LegalAgent · APIDocsAgent · VisualDesignAgent · SoftwarePackagingAgent · ProjectAssemblerAgent · DataMigrationAgent · TerminalAgent

Enterprise Agents (6)

AuditAgent · ComplianceAgent · EnterpriseCyberSecurityAgent · EnterpriseDataEngineeringAgent · EnterpriseDataMigrationAgent · EnterpriseIntegrationAgent

Agentic / Advanced

PDCAAgent · ContextAnalysisAgent

Memory & Learning System

Agent Output
    │
    ▼
LearningEngine ──► extracts signals/patterns
    │                      │
    ▼                      ▼
MemoryStore        Purple8 Graph
(CRUD layer)       (LearningSignal, Pattern,
PostgreSQL +        Memory nodes + edges)
Redis cache
    │
    ▼
GraphVectorBackend
(BuilderMemory nodes — semantic search)

No Qdrant. All vector storage routes through the Purple8 Graph REST API (purple8_graph.client.Purple8AsyncClient).

Services

Service Path Purpose
API Gateway services/gateway/ FastAPI, all /api/v1/* routes, auth middleware, rate limiting, CORS, tracing
Pipeline Runner services/pipeline_runner.py Orchestrates agent phases, emits SSE progress events
Smart Orchestrator services/smart_orchestrator.py Knowledge-graph-based dynamic agent selection
Sandbox services/sandbox/ Isolated Docker execution environment for generated code
Search shared/services/search/ Hybrid search — vector (VectorSearchEngine) + keyword + web
Knowledge Graph services/knowledge_graph/ Purple8 Graph integration layer
Journey Engine services/journey/ Product lifecycle, roadmapping
Worker Pool services/worker_pool.py Async task queue for long-running agent jobs
Startup Validator services/common/startup_validator.py Validates PostgreSQL, Redis, Purple8 Graph on boot
IDE Copilot services/gateway/routers/ide_copilot.py 8 edit actions, agent chat, streaming — powers Monaco Copilot in HITL editor

Gateway Routes (partial)

/auth · /pipeline · /pipeline/v2 · /agents · /memory · /context · /artifacts · /sandbox · /deploy · /git · /github · /quality · /health · /admin · /workflows · /observability · /legal · /approvals · /checkpoints · /rework · /proactive · /ide-copilot

IDE Copilot routes: POST /api/ide/copilot/edit/complete · POST /api/ide/copilot/edit/action · POST /api/ide/copilot/edit/suggest · POST /api/ide/copilot/agent/chat · POST /api/ide/copilot/agent/chat/stream · POST /api/ide/copilot/quick/{explain,fix,test} · GET /api/ide/copilot/health

Tech Stack

Layer Technology
Frontend Vue 3, Vite, Pinia, Vue Router, Tailwind CSS
API FastAPI, Uvicorn, Pydantic v2, WebSockets (SSE)
LLM OpenAI GPT-4o / GPT-4o-mini, Anthropic Claude (via LLMFactory)
Embeddings MoE router across OpenAI, local models (EmbeddingMoE)
Primary DB PostgreSQL 15
Cache / Sessions Redis 7
Knowledge Graph + Vectors Purple8 Graph (purple8-graph SDK)
Auth JWT + RBAC (roles: admin, enterprise, pro, starter)
Observability Structured logging, tracing middleware, SystemAlerts
Containerisation Docker, Docker Compose

Repository Structure

Purple8-platform/
├── config.py                   # Centralised configuration
├── conftest.py                 # Pytest config + collect_ignore
├── requirements.txt            # Python dependencies
│
├── frontend-vue/               # Vue 3 frontend
│   └── src/
│       ├── BuilderApp.vue      # Main builder UI
│       ├── views/
│       │   └── InteractiveBuilderView.vue  # Brand Kit form + Design Preview tab
│       ├── components/
│       │   ├── review/
│       │   │   ├── HITLReviewPanel.vue     # HITL review with hitlContext passthrough
│       │   │   └── MonacoCodeEditor.vue    # Monaco editor + Copilot toggle + side panel
│       │   └── sandbox/
│       │       └── IDECopilot.vue          # Copilot chat panel with HITL banner
│       ├── composables/
│       │   └── useCopilotProvider.ts       # Monaco InlineCompletionsProvider
│       ├── store/              # Pinia stores
│       └── services/           # API client layer
│
├── services/                   # Backend services
│   ├── gateway/                # FastAPI app + all routers
│   │   ├── routers/            # 30+ route modules
│   │   │   ├── artifacts.py    # ZIP download + _inject_deployment_docs()
│   │   │   └── ide_copilot.py  # IDE Copilot — edit actions, agent chat, streaming
│   │   └── middleware/         # Auth, CORS, rate-limit, tracing
│   ├── sandbox/                # Docker-isolated code execution
│   ├── knowledge_graph/        # Purple8 Graph integration
│   ├── journey/                # Product lifecycle service
│   └── common/                 # Shared utilities, startup validator
│
├── shared/                     # Shared library (imported by all services)
│   ├── agents/
│   │   ├── base_agent.py       # Abstract base + FourLayerMixin
│   │   ├── four_layer_mixin.py # 4-layer architecture implementation
│   │   ├── agentic/            # PDCA mixin, tools
│   │   ├── memory/             # MemoryStore, LearningEngine, ContextManager
│   │   │   ├── memory_store.py
│   │   │   ├── learning_engine.py
│   │   │   ├── context_manager.py
│   │   │   └── storage_backend.py  # GraphVectorBackend (Purple8 Graph)
│   │   ├── core/               # 17 core SDLC agents
│   │   ├── design_agent.py             # Brand-aware generation + preview_html
│   │   └── frontend_development_agent.py  # Brand contract + CSS var injection
│   │   ├── aiml/               # 20 AI/ML agents
│   │   ├── enterprise/         # 6 enterprise agents
│   │   ├── specialized/        # 10 specialised agents
│   │   └── advanced/           # Context analysis
│   └── services/
│       └── search/             # VectorSearchEngine, DocumentIndexer, SearchService
│
├── tests/                      # Test suite (1 050+ tests)
│   ├── agents/
│   │   └── test_pdca_e2e_regression.py          # 130 PDCA regression tests
│   ├── test_brand_builder_e2e_regression.py     # 95 brand kit + HITL copilot E2E tests
│   ├── gateway/
│   └── shared/
│
└── docs/                       # Architecture and API documentation
    ├── BUILDER_COMPLETE_ARCHITECTURE.md
    ├── PURPLE8_BUILDER.md
    ├── API_ENDPOINT_REFERENCE.md
    ├── DATABASE_SCHEMA.md
    ├── SANDBOX_ARCHITECTURE.md
    ├── SELF_LEARNING_IMPLEMENTATION.md
    └── ...

Prerequisites

Required environment variables

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=purple8
POSTGRES_USER=purple8
POSTGRES_PASSWORD=your_password

# Redis
REDIS_URL=redis://localhost:6379

# Purple8 Graph
PURPLE8_GRAPH_URL=http://localhost:8010
PURPLE8_GRAPH_API_KEY=your_graph_key

# LLM
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...   # optional

# Auth
SECRET_KEY=your_jwt_secret_key

Copy config/dev.env.template to .env and fill in the values.

Running Locally

1. Start infrastructure

docker compose up -d postgres redis

Start Purple8 Graph separately (see purple8-graph repo):

cd ../purple8-graph && docker compose up -d

2. Backend

# Install dependencies
pip install -r requirements.txt

# Run database migrations
python -m alembic upgrade head

# Start the API gateway
uvicorn services.gateway.main:app --reload --port 8000

3. Frontend

cd frontend-vue
npm install
npm run dev          # starts on http://localhost:5173

Using Docker Compose (full stack)

docker compose up --build

Services will be available at:

Running Tests

# All tests (1 050+ collected)
python3.11 -m pytest tests/ -q

# Specific module
python3.11 -m pytest tests/shared/ -q
python3.11 -m pytest tests/gateway/ -q

# Brand kit + HITL copilot E2E & regression suite
python3.11 -m pytest tests/test_brand_builder_e2e_regression.py -v

# PDCA regression guard (130 tests)
python3.11 -m pytest tests/agents/test_pdca_e2e_regression.py -v

# With coverage
python3.11 -m pytest tests/ --cov=shared --cov=services --cov-report=term-missing

Note: Always use python3.11. The deepeval dependency uses Python 3.10+ union-type syntax (X | None) that is incompatible with Python 3.9.

CI runs on Python 3.11 with PostgreSQL 15 and Redis 7. No Qdrant required.

Key Design Decisions

Purple8 Graph for all vector storage — Qdrant has been removed entirely. All embeddings (memory, RAG, search) are stored as nodes in Purple8 Graph using GraphVectorBackend and queried via client.search.vector(). This gives a unified knowledge graph where vector proximity and graph traversal work together.

Lazy client initialisation — Purple8AsyncClient is never instantiated at module import time. All backends use a _get_client() pattern, keeping pytest collection fast and safe.

Knowledge-graph-based agent selection — The SmartOrchestrator queries Purple8 Graph to determine which agents to run for a given project, rather than a hardcoded sequence. Agent selection is dynamic and improves as the system learns from past projects.

MoE cost control — LLMFactory and EmbeddingMoE route tasks to the cheapest capable model. Routine work uses GPT-4o-mini; complex reasoning escalates to GPT-4o or Claude.

RBAC tiers — starter · pro · enterprise · admin. Agent availability, pipeline depth, and sandbox resources are gated per tier.

Documentation

Document Content
docs/BUILDER_COMPLETE_ARCHITECTURE.md Full architecture reference (4-layer, pipeline, agents)
docs/PURPLE8_BUILDER.md Builder feature overview
docs/API_ENDPOINT_REFERENCE.md All API endpoints incl. /api/ide/copilot/*
docs/DATABASE_SCHEMA.md PostgreSQL schema
docs/SANDBOX_ARCHITECTURE.md Sandbox isolation design
docs/SELF_LEARNING_IMPLEMENTATION.md Memory and learning system
docs/OBSERVABILITY_README.md Logging, tracing, alerts
docs/RBAC_INTEGRATION_GUIDE.md Roles and permissions
docs/CODE_GOVERNANCE.md Code protection, licensing
docs/AI_GUARDRAILS.md LLM safety and guardrails

Contributing

  1. Branch from feature/purple8-builder
  2. Run python3.11 -m ruff check . before committing
  3. Ensure python3.11 -m pytest tests/ --collect-only reports no collection errors
  4. All agents must implement the 4-layer architecture via FourLayerMixin
  5. No direct Qdrant imports — use GraphVectorBackend / VectorSearchEngine

License

Copyright © 2025–2026 Nikhil Dutt Kasturi. All Rights Reserved.
See LICENSE for terms. See docs/AI_USAGE_TERMS.md for AI output usage policy.