Merge pull request #2 from Kenearos/claude/add-claude-documentation-3aGsJ
Add CLAUDE.md with comprehensive project documentation
This commit is contained in:
Kenearos
GitHub
commit
a64fba3201
1 changed files with 233 additions and 0 deletions
233
CLAUDE.md
Normal file
233
CLAUDE.md
Normal file
|
|
@ -0,0 +1,233 @@
|
||||||
|
# CLAUDE.md — CouncilOS (KI-Konzil)
|
||||||
|
|
||||||
|
This file provides context for AI assistants (Claude and others) working in this repository. Read it fully before making any changes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
**CouncilOS** ("KI-Rat Baukasten") is a visual no-code platform for building multi-agent AI pipelines. Users compose a "council" of AI experts — each with a defined role, system prompt, LLM model, and optional tools — and connect them via a drag-and-drop canvas. The agents then collaborate in iterative loops until a document or task reaches the desired quality.
|
||||||
|
|
||||||
|
**Repository status:** This is currently a concept and architecture stage. The only file is `README.md`, which serves as the master PRD and development roadmap. No application code exists yet.
|
||||||
|
|
||||||
|
**Primary language of documentation:** German. Code, variable names, and commit messages should be in English.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planned Tech Stack
|
||||||
|
|
||||||
|
Follow these technology choices exactly — they are architectural requirements, not suggestions:
|
||||||
|
|
||||||
|
| Layer | Technology | Reason |
|
||||||
|
|---|---|---|
|
||||||
|
| AI Orchestration | **LangGraph** (Python) | Native support for cyclic graphs and `interrupt_before` (Human-in-the-Loop) |
|
||||||
|
| Backend API | **FastAPI** (Python) | WebSocket support for real-time agent status updates |
|
||||||
|
| Frontend | **React** or **Next.js** + **React Flow** | Industry standard for interactive drag-and-drop canvas UIs |
|
||||||
|
| Database | **PostgreSQL** | Stores user data and council blueprints as JSON |
|
||||||
|
| Vector DB | **ChromaDB** (local) or **Pinecone** | Powers the PDF-reader tool |
|
||||||
|
| LLMs | **Anthropic Claude 3.5 Sonnet** + **OpenAI GPT-4o** | Via API |
|
||||||
|
| Search Tool | **Tavily Search API** | For the web-search agent tool |
|
||||||
|
| PDF Tool | **PyPDF** + vector store | For the PDF-reader agent tool |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Concepts
|
||||||
|
|
||||||
|
### Core Idea: Cyclic Multi-Agent Graphs
|
||||||
|
|
||||||
|
Unlike linear pipelines, CouncilOS agents run in **loops**. A critic agent can reject a draft and send it back to the master agent repeatedly until quality meets the threshold. This is the core differentiator.
|
||||||
|
|
||||||
|
### Agent Node Properties
|
||||||
|
|
||||||
|
Each agent node on the canvas has:
|
||||||
|
- **Name** — display label
|
||||||
|
- **System Prompt** — the role/persona definition
|
||||||
|
- **LLM Model** — which model to use (Claude, GPT-4o, or local)
|
||||||
|
- **Tools** — optional toggle switches: Web Search, PDF Reader
|
||||||
|
|
||||||
|
### Edge Types
|
||||||
|
|
||||||
|
- **Linear edges** — agent A always passes output to agent B
|
||||||
|
- **Conditional edges** — agent A routes dynamically (e.g. `"rework"` → back to master, `"approve"` → next stage)
|
||||||
|
|
||||||
|
### The Global State (`CouncilState`)
|
||||||
|
|
||||||
|
This is the central data structure passed between all agents in LangGraph. Always use and extend this TypedDict:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from typing import TypedDict, Annotated, List
|
||||||
|
import operator
|
||||||
|
|
||||||
|
class CouncilState(TypedDict):
|
||||||
|
input_topic: str # The user's original prompt or uploaded PDF content
|
||||||
|
current_draft: str # The document currently being worked on
|
||||||
|
feedback_history: List[str] # All critic feedback accumulated across loop iterations
|
||||||
|
route_decision: str # Routing signal: "rework" | "approve" | custom values
|
||||||
|
messages: Annotated[list, operator.add] # LLM message history (system + responses)
|
||||||
|
```
|
||||||
|
|
||||||
|
Agents should append to `feedback_history` rather than overwriting it, so the master agent can learn from all previous critique in a loop.
|
||||||
|
|
||||||
|
### Execution Modes
|
||||||
|
|
||||||
|
| Mode | Behavior |
|
||||||
|
|---|---|
|
||||||
|
| **Auto-Pilot** | Agents run fully autonomously until completion |
|
||||||
|
| **God Mode** | LangGraph pauses at each decision point via `interrupt_before`; user approves/rejects/modifies before continuing |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Roadmap
|
||||||
|
|
||||||
|
Build in this order — **backend first, frontend second**:
|
||||||
|
|
||||||
|
### Phase 1: LangGraph Engine (Backend MVP)
|
||||||
|
- Set up Python environment and FastAPI
|
||||||
|
- Hard-code a fixed test graph: `User Input → Master AI → Critic AI → (if score < 8: back to Master; if ≥ 8: Writer AI)`
|
||||||
|
- Implement `CouncilState` and the routing logic
|
||||||
|
- Verify the loop runs correctly via terminal or Postman
|
||||||
|
|
||||||
|
### Phase 2: Visual Builder (Frontend MVP)
|
||||||
|
- Set up React + React Flow
|
||||||
|
- Build custom node components with editable name, system prompt, model selector, and tool toggles
|
||||||
|
- Build edge drawing (linear and conditional)
|
||||||
|
- Write a **parser** that converts the React Flow graph into a structured JSON and saves it to PostgreSQL
|
||||||
|
|
||||||
|
### Phase 3: Integration (Frontend ↔ Backend)
|
||||||
|
- Make LangGraph **dynamic**: read the JSON blueprint from Phase 2 and construct the graph at runtime
|
||||||
|
- Add WebSocket events: when LangGraph enters a node, emit an event so the frontend highlights that node
|
||||||
|
- Display the final output text in the frontend
|
||||||
|
|
||||||
|
### Phase 4: Tools & God Mode (Enterprise Features)
|
||||||
|
- Integrate Tavily Search API and PyPDF + vector store as agent tools
|
||||||
|
- Assign tools to specific nodes in the frontend
|
||||||
|
- Implement Human-in-the-Loop using LangGraph's `interrupt_before`
|
||||||
|
- Build the approval UI: display the paused state, reason, and Approve / Reject / Modify buttons
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI Structure
|
||||||
|
|
||||||
|
### Tab A: "Rat-Architekt" (Setup Mode)
|
||||||
|
- Infinite canvas (React Flow)
|
||||||
|
- Drag nodes from a sidebar panel onto the canvas
|
||||||
|
- Click a node → open settings panel (name, system prompt, LLM, tool toggles)
|
||||||
|
- Draw edges between nodes; mark edges as conditional where needed
|
||||||
|
|
||||||
|
### Tab B: "Konferenzzimmer" (Execution Mode)
|
||||||
|
- Text input or PDF upload to start a council run
|
||||||
|
- Auto-Pilot / God Mode toggle
|
||||||
|
- Live diagram view: active agent node pulses/glows (WebSocket-driven)
|
||||||
|
- God Mode: approval popup when the graph pauses
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conventions for AI Assistants
|
||||||
|
|
||||||
|
### Language
|
||||||
|
- All **code, variable names, function names, comments, and commit messages** must be in **English**
|
||||||
|
- User-facing UI text and in-code string literals for the UI may be in German (matching the product's target audience)
|
||||||
|
- Do not translate the existing German `README.md`
|
||||||
|
|
||||||
|
### Python Code Style
|
||||||
|
- Use Python 3.11+
|
||||||
|
- Type hints are mandatory — use `TypedDict` for state classes, `Annotated` for LangGraph reducers
|
||||||
|
- Follow PEP 8; use `ruff` for linting and `black` for formatting if configured
|
||||||
|
- Keep LangGraph node functions pure where possible (single input state → output state dict)
|
||||||
|
- Name node functions descriptively: `master_agent_node`, `critic_agent_node`, `route_decision`
|
||||||
|
|
||||||
|
### FastAPI Conventions
|
||||||
|
- Use async route handlers
|
||||||
|
- Separate route definitions from business logic (use service modules)
|
||||||
|
- WebSocket endpoint for live agent status: `/ws/council/{run_id}`
|
||||||
|
- REST endpoints for CRUD on council blueprints: `/api/councils/`
|
||||||
|
|
||||||
|
### React / Frontend Conventions
|
||||||
|
- Use functional components with hooks
|
||||||
|
- React Flow nodes must be wrapped in custom components (never use raw default nodes for agent cards)
|
||||||
|
- The JSON format emitted by the parser (Phase 2) must be the canonical exchange format between frontend and backend; keep it versioned
|
||||||
|
- State management: use React context or Zustand (avoid Redux unless team decides otherwise)
|
||||||
|
|
||||||
|
### Database
|
||||||
|
- Council blueprints are stored as JSONB columns in PostgreSQL
|
||||||
|
- Include a `version` field in blueprint JSON to allow schema evolution
|
||||||
|
- Use Alembic for migrations
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- Write pytest tests for all LangGraph node functions and routing logic
|
||||||
|
- Mock LLM calls in unit tests (do not make real API calls in CI)
|
||||||
|
- Frontend: React Testing Library for component tests
|
||||||
|
|
||||||
|
### Git Workflow
|
||||||
|
- Branch naming: `feature/<short-description>`, `fix/<short-description>`
|
||||||
|
- Commit messages: imperative mood, English, e.g. `Add critic agent routing logic`
|
||||||
|
- Never commit API keys or `.env` files
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
When code is created, expected environment variables will include:
|
||||||
|
|
||||||
|
```
|
||||||
|
ANTHROPIC_API_KEY=
|
||||||
|
OPENAI_API_KEY=
|
||||||
|
TAVILY_API_KEY=
|
||||||
|
DATABASE_URL=postgresql://...
|
||||||
|
CHROMA_PERSIST_DIR=./chroma_db
|
||||||
|
```
|
||||||
|
|
||||||
|
Create a `.env.example` file (no real values) and add `.env` to `.gitignore`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Design Constraints
|
||||||
|
|
||||||
|
1. **Cycles are first-class** — never flatten the graph into a DAG just to simplify code. LangGraph's cycle support is the core value proposition.
|
||||||
|
2. **State is the source of truth** — agents must not store state internally; everything passes through `CouncilState`.
|
||||||
|
3. **No hardcoded graphs in production** — Phase 1 may hard-code a test graph, but from Phase 3 onward the graph must be dynamically built from the JSON blueprint.
|
||||||
|
4. **WebSockets for real-time updates** — polling is not acceptable for agent status; use WebSocket events.
|
||||||
|
5. **Human-in-the-Loop via `interrupt_before`** — do not build a custom pause mechanism; use LangGraph's built-in support.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Repository Structure (Target — Once Code Exists)
|
||||||
|
|
||||||
|
```
|
||||||
|
KI-Konzil/
|
||||||
|
├── README.md # German PRD / project blueprint (do not modify)
|
||||||
|
├── CLAUDE.md # This file
|
||||||
|
├── .env.example # Template for required environment variables
|
||||||
|
├── backend/
|
||||||
|
│ ├── main.py # FastAPI app entrypoint
|
||||||
|
│ ├── api/ # Route definitions
|
||||||
|
│ ├── services/ # Business logic, LangGraph graph builder
|
||||||
|
│ ├── agents/ # Individual agent node functions
|
||||||
|
│ ├── state.py # CouncilState TypedDict definition
|
||||||
|
│ ├── tools/ # Web search and PDF reader tool wrappers
|
||||||
|
│ └── tests/ # pytest test suite
|
||||||
|
├── frontend/
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── components/ # React components
|
||||||
|
│ │ │ ├── nodes/ # React Flow custom node components
|
||||||
|
│ │ │ └── edges/ # React Flow custom edge components
|
||||||
|
│ │ ├── pages/ # Page-level components / Next.js pages
|
||||||
|
│ │ ├── hooks/ # Custom React hooks (WebSocket, council API)
|
||||||
|
│ │ └── utils/ # Parser: React Flow JSON → blueprint JSON
|
||||||
|
│ └── public/
|
||||||
|
└── docker-compose.yml # Local development environment
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Started (Once Implemented)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Backend
|
||||||
|
cd backend
|
||||||
|
python -m venv .venv && source .venv/bin/activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
uvicorn main:app --reload
|
||||||
|
|
||||||
|
# Frontend
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
Loading…
Add table
Add a link
Reference in a new issue