docs: update README, wiki overview, index, log; add roles/code-review/pydantic wiki pages

- README: remove autogen/crewai references, add v2 architecture diagram, code-review scenario, cross-LLM config examples, roadmap - wiki/overview: event-driven architecture, Pydantic v2, roadmap - wiki/index: add entities/roles, concepts/code-review, packages/pydantic - wiki/log: Phase 1 completion, code-review decision - New: entities/roles.md, concepts/code-review.md, packages/pydantic.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-04 06:30:33 +03:00
parent 2887b2309a
commit 962b0beddd
7 changed files with 224 additions and 50 deletions
--- a/.wiki/concepts/code-review.md
+++ b/.wiki/concepts/code-review.md
@@ -0,0 +1,37 @@
+---
+title: Cross-LLM Code Review
+type: concept
+updated: 2026-05-04
+---
+
+# Cross-LLM Code Review
+
+Use meeting-room to run multi-agent code review where different LLM providers cross-check each other's work.
+
+## How it works
+
+1. Configure multiple providers (OpenAI, Anthropic, DeepSeek, local Ollama)
+2. Assign different providers to review roles (defender, attacker, security)
+3. Point meeting-room at a project directory with `-w /path/to/project`
+4. Agents read code files, debate quality, and produce structured findings
+
+## Scenario
+
+```bash
+meeting-room -s code-review.md -w /path/to/project
+```
+
+## Why cross-LLM?
+
+Different models have different blind spots. GPT-4o may catch type errors that Claude misses, while DeepSeek may spot performance issues neither other model flagged. Cross-LLM review is the "second pair of eyes" principle applied to AI code review.
+
+## Role separation
+
+- **defender** — explains design decisions, pushes back on unjustified criticism
+- **attacker** — hunts bugs, SOLID violations, dead code, edge cases
+- **security** — checks injection, auth gaps, CVEs in dependencies
+- **moderator** — categorizes findings (CRITICAL / IMPORTANT / MINOR / APPROVED)
+
+## Future (Phase 3)
+
+Boss role will allow injecting questions mid-review. CSO (Claude Code) will be able to join the review via REST API.
--- a/.wiki/entities/roles.md
+++ b/.wiki/entities/roles.md
@@ -0,0 +1,45 @@
+---
+title: Discussion Roles
+type: entity
+updated: 2026-05-04
+---
+
+# Discussion Roles
+
+Roles define participants in a meeting-room discussion. Each role binds to a provider, model, temperature, tool set, and system prompt.
+
+## General discussion roles
+
+| Role | Purpose | Default tools |
+|------|---------|-------------|
+| moderator | Guide conversation, summarize, keep on-topic | none |
+| skeptic | Find weaknesses, ask hard questions, counter-argue | readonly |
+| idea_generator | Propose unconventional solutions, search web for inspiration | web |
+| analyst | Structure arguments, assess risks, propose action plans | all |
+
+## Code review roles
+
+| Role | Purpose | Default tools |
+|------|---------|-------------|
+| defender | Defend code decisions, explain rationale | readonly |
+| attacker | Ruthlessly find bugs, style violations, dead code | readonly |
+| security | Check vulnerabilities, injection, CVEs | web |
+| moderator | Structure review findings into CRITICAL/IMPORTANT/MINOR | none |
+
+## Role configuration
+
+```yaml
+roles:
+  my_role:
+    name: "Display Name"
+    provider: openai          # provider key from providers section
+    model: "gpt-4o"
+    temperature: 0.7          # 0.0 = deterministic, 1.0 = creative
+    tools: "readonly"         # tool set name or list ["read_file", "web_search"]
+    system_prompt: |
+      Your instructions here...
+```
+
+## Cross-LLM review
+
+Assign different `provider` values to roles so separate LLMs cross-check each other. The defender uses one model, the attacker uses another — each catches what the other misses.
--- a/.wiki/index.md
+++ b/.wiki/index.md
@@ -4,20 +4,21 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever

 ## Overview

- [overview.md](overview.md) — project overview
+- [overview.md](overview.md) — project overview, tech stack, roadmap

 ## Entities

-<!-- (none yet) -->
+- [roles.md](entities/roles.md) — discussion roles: moderator, skeptic, idea_generator, analyst, defender, attacker, security

 ## Concepts

 - [bootstrap-manifest.md](concepts/bootstrap-manifest.md) — skills used to initialize project structure
- [meeting-room-v2.md](concepts/meeting-room-v2.md) — v2 architecture: interactive office with Web UI
+- [meeting-room-v2.md](concepts/meeting-room-v2.md) — v2 architecture: 4-phase plan, interactive office
+- [code-review.md](concepts/code-review.md) — cross-LLM code review pattern

 ## Packages

-<!-- (none yet) -->
+- [pydantic.md](packages/pydantic.md) — Pydantic v2 models for config, messages, sessions

 ## Sources

--- a/.wiki/log.md
+++ b/.wiki/log.md
@@ -12,4 +12,8 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.

 ---

-## [2026-05-03] init | wiki bootstrapped via setup-wiki@1.0.0
+## [2026-05-03] init | wiki bootstrapped via setup-wiki@1.0.0
+
+## [2026-05-04] refactor | v2 Phase 1 complete: Pydantic models, EventEmitter, APIClient class, ToolRegistry class (pure Python/Windows), DiscussionEngine (event-driven), config.py, CLI refactor, deprecation shim. 184 tests passing.
+
+## [2026-05-04] decision | code-review scenario added: cross-LLM review with defender/attacker/security/moderator roles
--- a/.wiki/overview.md
+++ b/.wiki/overview.md
@@ -1,7 +1,7 @@
 ---
 title: meeting-room overview
 type: overview
-updated: 2026-05-03
+updated: 2026-05-04
 ---

 # meeting-room — overview
@@ -10,18 +10,32 @@ Multi-agent discussion framework — an interactive workspace where AI agents de

 ## What it does

-Meeting-room is the "office" in the `.meeting-room/` org structure. It runs multi-agent roundtable discussions (Moderator, Skeptic, Idea Generator, Analyst) and supports interactive brainstorm sessions with a CSO (Chief Strategy Officer) agent.
+Meeting-room runs multi-agent roundtable discussions with configurable participants, models, and tools. Each role can use a different LLM provider, enabling cross-model review and debate. The event-driven architecture decouples the engine from I/O — CLI subscribes to events for ANSI output, future WebSocket server will stream them to browsers.

 ## Key components

- **Brainstorm** — 1:1 discussion with CSO for raw idea exploration
- **Roundtable** — multi-agent discussion with configurable participants, models, and tools
- **Setup** — interactive pre-discussion configuration (participants, models, agenda, artifacts)
- **Artifacts** — structured output: tasks → `.tasks/`, knowledge → `.wiki/`, decisions → markdown
+- **DiscussionEngine** — event-driven core: orchestrates round-robin discussion, emits events instead of printing
+- **APIClient** — class-based multi-provider client (OpenAI-compatible APIs)
+- **ToolRegistry** — class-based, pure Python (Windows compatible, no find/grep)
+- **EventEmitter** — synchronous pub/sub bus for decoupling engine from I/O
+- **Pydantic v2 models** — typed config (DiscussionConfig, ProviderConfig, RoleConfig), messages, sessions
+- **Scenarios** — Markdown + YAML frontmatter for defining discussion topics
+
+## Built-in scenarios
+
+- **Roundtable** — moderator/skeptic/idea_generator/analyst discuss a problem
+- **Code Review** — defender/attacker/security/moderator cross-LLM code review

 ## Tech stack

- Python 3.11+, httpx, pyyaml
- Custom backend (round-robin agent orchestration with tool support)
- OpenAI-compatible API (multi-provider: RouterAI, Ollama Cloud, etc.)
- Planned: FastAPI + WebSocket for Web UI
+- Python 3.11+, pydantic v2, httpx, pyyaml
+- Event-driven architecture (EventEmitter, Phase 2: AsyncEventBridge)
+- OpenAI-compatible API (multi-provider: RouterAI, Ollama Cloud, OpenAI, Anthropic, DeepSeek, local Ollama)
+- Planned: FastAPI + WebSocket for Web UI (Phase 2)
+
+## Roadmap
+
+- [x] Phase 1: Core refactor — Pydantic models, EventEmitter, class-based APIClient/ToolRegistry, DiscussionEngine
+- [ ] Phase 2: Web server — FastAPI + WebSocket + SSE, REST API, HTML UI
+- [ ] Phase 3: Interactivity — Boss role, CSO injection, Setup Wizard, BrainstormEngine
+- [ ] Phase 4: Artifacts — LLM extraction to .tasks/.wiki, SessionArchive
--- a/.wiki/packages/pydantic.md
+++ b/.wiki/packages/pydantic.md
@@ -0,0 +1,38 @@
+---
+title: Pydantic v2 Models
+type: package
+updated: 2026-05-04
+---
+
+# Pydantic v2 Models
+
+meeting-room uses Pydantic v2 for typed configuration, messages, and session data. All models are in `meeting_room/models.py`.
+
+## Config models
+
+| Model | Purpose | extra |
+|-------|---------|-------|
+| `ProviderConfig` | API provider (base_url, api_key) | forbid |
+| `RoleConfig` | Discussion role (name, provider, model, temperature, tools, system_prompt) | forbid |
+| `DefaultsConfig` | Default settings (max_rounds, language, framework, workdir) | ignore |
+| `DiscussionConfig` | Top-level config — direct counterpart of config.yaml | ignore |
+
+Key: `DiscussionConfig(**yaml_config)` works unchanged — feeds parsed YAML directly into the model.
+
+## Scenario model
+
+| Model | Purpose | extra |
+|-------|---------|-------|
+| `ScenarioConfig` | Loaded from .md/.yaml (name, participants, max_rounds, problem) | ignore |
+
+## Runtime models
+
+| Model | Purpose | extra |
+|-------|---------|-------|
+| `Message` | Single discussion message (role_id, name, content) | forbid |
+| `ToolCallRecord` | Tool call (id, name, arguments, result) | forbid |
+| `Session` | Full session (scenario, messages, tool_calls, created_at, updated_at) | ignore |
+
+## Tools field
+
+`RoleConfig.tools` accepts both `str` ("all", "readonly", etc.) and `list[str]` (["read_file", "web_search"]). A field validator coerces list items to strings.
--- a/README.md
+++ b/README.md
@@ -9,9 +9,11 @@ git clone <repo-url> meeting-room
 cd meeting-room
 pip install -e .

-# Optional backends
-pip install -e ".[autogen]"
-pip install -e ".[crewai]"
+# With dev dependencies (pytest, pytest-mock)
+pip install -e ".[dev]"
+
+# With web server dependencies (Phase 2)
+pip install -e ".[web]"
 ```

 ## Quick Start
@@ -20,32 +22,18 @@ pip install -e ".[crewai]"
 # Initialize workspace (creates .meeting-room/ in current directory)
 meeting-room init

-# Create a scenario
-cat > .meeting-room/scenarios/my-problem.md << 'EOF'
---
-name: "My Problem"
-participants:
-  - moderator
-  - skeptic
-  - idea_generator
-  - analyst
-max_rounds: 6
---
+# Run a discussion with default scenario
+meeting-room -s example-saas.md

-# Problem Title
-
-Describe the problem in Markdown...
-EOF
-
-# Run discussion
-cd .meeting-room
-meeting-room -s scenarios/my-problem.md
-
-# Run and save result
+# Run and save result to sessions/
 meeting-room -s scenarios/my-problem.md --save

-# Point agents at a project for file tools
-meeting-room -w /path/to/project -s scenarios/code-review.md
+# Cross-LLM code review — point agents at a project
+meeting-room -s code-review.md -w /path/to/project
+
+# List available scenarios and roles
+meeting-room --list-scenarios
+meeting-room --list-roles
 ```

 ## Workspace Structure
@@ -65,13 +53,41 @@ meeting-room -w /path/to/project -s scenarios/code-review.md
 meeting-room init [path]                      # Create .meeting-room workspace
 meeting-room -s scenarios/my.md               # Run discussion
 meeting-room -s scenarios/my.md --save        # Run and save result
-meeting-room -b autogen -s scenarios/my.md    # Use AutoGen backend
-meeting-room -b crewai -s scenarios/my.md     # Use CrewAI backend
+meeting-room -s code-review.md -w /path       # Code review on a project
 meeting-room --list-scenarios                 # Show available scenarios
 meeting-room --list-roles                     # Show roles and model bindings
 meeting-room -c /path/to/config.yaml -s ...   # Custom config file
+meeting-room -w /path/to/project -s ...       # Set workdir for file tools
 ```

+## Built-in Scenarios
+
+| Scenario | Description |
+|----------|-------------|
+| `example-saas.md` | General discussion: SaaS architecture with moderator/skeptic/idea_generator/analyst |
+| `code-review.md` | Cross-LLM code review with defender/attacker/security/moderator |
+
+## Architecture (v2)
+
+```
+┌──────────┐    events     ┌───────────────┐
+│   CLI    │◄────────────│  DiscussionEngine  │
+│ (ANSI)   │             │  (event-driven)    │
+└──────────┘             └───────┬───────┘
+                                 │
+                    ┌────────────┼────────────┐
+                    ▼            ▼            ▼
+              ┌──────────┐ ┌──────────┐ ┌──────────┐
+              │ APIClient│ │ToolRegistry│ │EventEmitter│
+              └──────────┘ └──────────┘ └──────────┘
+```
+
+- **DiscussionEngine** — orchestrates round-robin discussion, emits events (no print calls)
+- **APIClient** — class-based, multi-provider (OpenAI-compatible APIs)
+- **ToolRegistry** — class-based, pure Python (Windows compatible)
+- **EventEmitter** — synchronous pub/sub bus (Phase 2: AsyncEventBridge for WebSocket)
+- **Pydantic v2 models** — typed config, messages, sessions
+
 ## Configuration

 ### Config Search Order
@@ -88,6 +104,7 @@ export MEETING_ROOM_ROUTERAI_API_KEY="sk-..."
 export MEETING_ROOM_ROUTERAI_BASE_URL="https://routerai.ru/api/v1"
 export MEETING_ROOM_OPENAI_API_KEY="sk-..."
 export MEETING_ROOM_ANTHROPIC_API_KEY="sk-ant-..."
+export MEETING_ROOM_DEEPSEEK_API_KEY="sk-..."
 ```

 Or use `${ENV_VAR}` placeholders in config.yaml.
@@ -98,12 +115,23 @@ Each role binds to a provider + model + tool set:

 ```yaml
 roles:
-  analyst:
-    name: "Analyst"
-    provider: anthropic
-    model: "claude-sonnet-4"
-    temperature: 0.5
-    tools: "all"
+  defender:
+    name: "Defender"
+    provider: anthropic       # one LLM defends
+    model: "claude-sonnet-4-6"
+    tools: "readonly"
+
+  attacker:
+    name: "Attacker"
+    provider: openai          # another LLM attacks
+    model: "gpt-4o"
+    tools: "readonly"
+
+  security:
+    name: "Security"
+    provider: deepseek        # third LLM checks security
+    model: "deepseek-chat"
+    tools: "web"
 ```

 ### Tool Sets
@@ -145,6 +173,13 @@ Full Markdown description...
 2. How to scale?
 ```

+## Roadmap
+
+- [x] **Phase 1: Core refactor** — Pydantic models, EventEmitter, class-based APIClient/ToolRegistry, DiscussionEngine, backward-compatible CLI
+- [ ] **Phase 2: Web server** — FastAPI + WebSocket + SSE, REST API, minimal HTML UI, `meeting-room serve`
+- [ ] **Phase 3: Interactivity** — Boss role, CSO injection, Setup Wizard, BrainstormEngine
+- [ ] **Phase 4: Artifacts** — LLM extraction → .tasks/.wiki, SessionArchive
+
 ## License

-MIT
+MIT