🌍 LeetCode World

A multi-agent LeetCode learning system built on Google ADK and A2A: parse a problem, decide whether it is already known, solve it with specialized agents, and persist the result into an Obsidian-backed knowledge base.

Don't just solve problems — learn patterns. Build your world model.

This repo is intentionally shaped as a learning system, not just a coding assistant:

• Hybrid orchestration: a policy layer chooses between cache reuse, similar-problem search, explanation, or a fresh solve
• Deterministic execution where it matters: Parser -> Architect -> Coder -> Librarian for new problems
• Distributed agent ecosystem: each worker is available as an A2A service with its own Agent Card
• Developer tooling: ADK Web workspace, agent inspection CLI, health checks, and protocol-aware debugging
• Persistent memory: Obsidian + ChromaDB make the system stateful instead of disposable

---

Why This Project Exists

I built this project to learn LeetCode more efficiently and to avoid treating every problem as a blank slate.

The idea is simple:

• break solving into specialized steps instead of one giant prompt
• reuse prior knowledge when a problem has already been solved
• search for similar problems and patterns before writing code from scratch
• persist clean notes, pattern links, and solution metadata for later review
• build a personal "world model" of algorithmic patterns over time

The goal is not only to get an answer. The goal is to get:

• a correct solution
• a pattern-level explanation
• a reusable note
• a growing map of what I already know and what I still need to practice

---

⚡ One-Command Start (Windows)

# First time only — copy and fill in your API key
copy .env.example .env

# Solve a problem (local mode, fast)
.\start.ps1

# Distributed A2A mode — opens agent server window, then interactive solver
.\start.ps1 -a2a

# Full dev mode — A2A servers + ADK Web UI + CLI solver
.\start.ps1 -dev

# Other commands
.\start.ps1 -stats    # pattern mastery dashboard
.\start.ps1 -init     # initialize vault + ChromaDB
.\start.ps1 -test     # run test suite
.\start.ps1 -help     # show all options

Dev mode opens 3 windows automatically:

• Window 1 — A2A agent servers with uvicorn logs per agent
• Window 2 — ADK Web UI at http://localhost:8000 using a curated .adk/apps/ workspace
• Window 3 — Interactive solver in the current terminal

Important: ADK Web only shows invocations started inside the browser UI. The terminal solver is useful for quick runs, but it does not automatically appear as an ADK Web invocation.

---

🏗️ Architecture

User
  ↓
🔍 Parser
  ↓
🧭 Policy Layer
  ├── already_solved
  ├── explain_existing
  ├── search_similar
  └── solve_new
        ↓
      🧠 Architect → 💻 Coder → 📚 Librarian

The interesting part is not just that there are multiple agents, but that the system has two layers:

• a smart routing layer that decides whether to reuse knowledge or do new work
• a deterministic execution layer for the critical path when a fresh solve is needed

In distributed mode, the working agents run as independent A2A services with their own HTTP endpoints and Agent Cards. The orchestrator consumes them through RemoteA2aAgent.

What each box does:

• ParserAgent extracts structured problem data from the raw LeetCode prompt: title, difficulty, constraints, examples, keywords, and data structures.
• A2APolicyAgent is the decision layer. It checks whether the problem is already known, whether similar problems exist, and whether the system should explain, reuse, or solve from scratch.
• search_vault_problems is the semantic search tool over the existing knowledge base, used to find related solved problems and shared patterns.
• lookup_problem_note is the exact-cache lookup tool, used to answer “have we already solved this exact problem?”
• A2ARouteExecutor is the branch handoff point. If the policy decides solve_new, it forwards execution into the deterministic solving workflow.
• A2ASolveWorkflow is the fixed execution path for new problems, kept sequential on purpose so the core solve flow is reliable and easy to debug.
• ArchitectAgent identifies the best-fit algorithmic patterns for the parsed problem and can register new patterns when the existing registry is not enough.
• CoderAgent turns the chosen patterns into working Python solutions with complexity analysis and approach explanations.
• LibrarianAgent persists the result into the vault, updates pattern notes and statistics, refreshes the dashboard, and makes the system stateful over time.

How A2A Works Here

1. Agent Card Discovery — Each agent exposes /.well-known/agent-card.json describing its capabilities
2. RemoteA2aAgent — The distributed orchestrator creates proxy agents pointing to each Agent Card URL
3. A2A Protocol — Communication happens over HTTP using the standard A2A message format
4. Hybrid Routing — the policy layer chooses the route; solve_new delegates to a deterministic remote workflow

---

🤖 Agents

Agent	Port	Role
🔍 Parser	10001	Extracts title, difficulty, constraints, data structures, keywords
🧭 Policy	—	Chooses already_solved, solve_new, search_similar, or explain_existing
🧠 Architect	10002	Identifies 1-3 algorithmic patterns with confidence scores
💻 Coder	10003	Generates Python solutions with time/space complexity
📚 Librarian	10004	Writes Obsidian notes, updates pattern stats, manages knowledge graph
🎯 Orchestrator	—	Distributed ADK entrypoint that consumes A2A services via RemoteA2aAgent

The individual worker services are wrapped with to_a2a() and expose their capabilities via Agent Card.

Pattern Registry

20+ algorithmic patterns with keywords, template code, and metadata. The system dynamically registers new patterns when the Architect discovers ones outside the core registry — the World Model grows as you solve more problems.

Pattern	Category	Pattern	Category
Two Pointers	Array	Top K Elements	Heap
Sliding Window	Array	K-way Merge	Heap
Fast & Slow Pointers	Linked List	Dynamic Programming	DP
Merge Intervals	Array	Topological Sort	Graph
Cyclic Sort	Array	Monotonic Stack	Stack
In-place Linked List Reversal	Linked List	Union Find	Graph
BFS	Tree/Graph	Trie	String
DFS	Tree/Graph	Greedy	Optimization
Two Heaps	Heap	Modified Binary Search	Search
Backtracking	Recursion	Bitwise XOR	Bit Manipulation

---

🚀 Setup

Prerequisites

• Python 3.11+
• A Google Gemini API key (free tier works)
• Obsidian with the Dataview plugin (for the dashboard)

Install

# Clone
git clone https://github.com/matnabru/leetcode-world.git
cd leetcode-world

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate

# Install runtime dependencies
pip install -e .

# Optional but recommended for running tests and linting
pip install -e .[dev]

# Configure (add your GOOGLE_API_KEY)
copy .env.example .env

# Initialize vault structure + seed ChromaDB
.\start.ps1 --init

Manual CLI (without the launcher script)

# Local mode
python -m leetcode_world solve
python -m leetcode_world stats
python -m leetcode_world search "sliding window"

# A2A mode — Terminal 1
python -m leetcode_world serve

# A2A mode — Terminal 2
python -m leetcode_world solve-a2a
python -m leetcode_world agents        # inspect live agent cards, health, and skills
python -m leetcode_world agents --json # export ecosystem snapshot as JSON

# ADK visual debugger
adk web .adk/apps

The curated ADK workspace exposes individual apps for parser, architect, coder, librarian, pipeline, and orchestrator, so you can:

• chat with each agent directly
• paste a full problem into orchestrator to inspect the distributed flow
• compare the local pipeline with the distributed orchestrator
• avoid ADK trying to index Vault/, tests/, or other repo folders

---

📂 Vault Structure

The Vault/ directory (gitignored) is auto-created as your Obsidian vault:

Vault/
└── LeetCode/
    ├── Problems/
    │   ├── Two Sum.md
    │   ├── Container With Most Water.md
    │   └── ...
    ├── Patterns/
    │   ├── Two Pointers.md
    │   ├── Hash Map.md        ← dynamically discovered!
    │   ├── Sliding Window.md
    │   └── ... (20+ pattern notes)
    └── Dashboard.md  ← Dataview-powered mastery dashboard

Problem Note (auto-generated)

---
title: "Two Sum"
difficulty: Easy
date_solved: 2026-03-30
patterns: ["Hash Map", "Two Pointers"]
time_complexity: "O(n)"
space_complexity: "O(n)"
status: solved
---

With [[backlinks]] connecting to pattern notes and similar problems.

---

🧪 Tests

.\start.ps1 --test
# or
python -m pytest tests/ -v

Tests covering the pattern registry, Obsidian tools, ChromaDB, agent configuration, tracing, and A2A server/launcher setup. No LLM calls required. Install the optional dev dependencies first with pip install -e .[dev].

---

🔬 Observability

• ADK Web UI for browser-started sessions, event timelines, and per-agent debugging
• Agent Cards at each service's /.well-known/agent-card.json
• A2A inspection CLI via python -m leetcode_world agents --json
• Per-agent health checks in the launcher with named status output
• Custom trace module in leetcode_world/tracing.py for JSON trace logging and future frontend observability work

For the clearest workflow:

• use ADK Web orchestrator to watch the distributed flow
• use ADK Web single-agent apps to inspect one worker at a time
• use the terminal CLI when you want a fast manual run

---

🎯 Learning Loop

The project is designed around a repeatable learning loop:

1. Paste a new problem.
2. Check whether it already exists in the vault.
3. If it does, review the existing explanation and patterns instead of re-solving blindly.
4. If it does not, solve it through the full agent workflow.
5. Save the result as a structured note connected to broader pattern knowledge.
6. Use the vault and statistics to revisit weak areas on purpose.

That makes the system useful for:

• deliberate practice
• spaced review of solved problems
• identifying recurring patterns
• building intuition instead of only collecting accepted submissions

---

🛠️ Tech Stack

• Google ADK — Agent Development Kit for multi-agent orchestration
• A2A Protocol — Agent-to-Agent communication via to_a2a() + RemoteA2aAgent
• Gemini — LLM powering all agents (configurable via GOOGLE_GENAI_MODEL)
• ChromaDB — Local vector database for problem similarity search
• Obsidian — Knowledge management with [[backlinks]] and Dataview
• Rich — Beautiful CLI output
• Pydantic — Structured data validation
• Uvicorn — ASGI server for A2A agent services

---

📄 License

MIT — see LICENSE for details.

---

Built by Mateusz Urbanek as a multi-agent system for learning LeetCode through pattern reuse, persistent notes, and inspectable workflows.