feat: initial LegalIntern multi-agent consultation system

Nine-agent pipeline for complex legal consultations over Ukrainian
court decisions, inspired by HuggingFace PhysicsIntern architecture.

Agents: Surveyor, Planner, Orchestrator, Researcher, Analyst,
Reviewer, Critic, Adjudicator, Formatter.

Includes Gradio app for HF Space demo, SecondLayer MCP bridge,
structured ConsultationState, and example legal problems.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+workspaces/
+*.pyc
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+uv.lock

README.md

@@ -0,0 +1,135 @@
+---
+title: LegalIntern
+emoji: ⚖️
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.31.0
+app_file: app.py
+pinned: true
+license: apache-2.0
+tags:
+  - legal-nlp
+  - multi-agent
+  - ukraine
+  - court-decisions
+  - legal-consultation
+---
+
+# LegalIntern
+
+A multi-agent scaffolding system for **complex legal consultations** over Ukrainian court decisions and legislation.
+
+Inspired by [PhysicsIntern](https://huggingface.co/spaces/huggingface/physics-intern)'s multi-agent research pipeline, adapted for the legal domain with access to 100M+ Ukrainian court decisions via [SecondLayer](https://legal.org.ua).
+
+## Architecture
+
+Nine specialised LLM agents work in a loop, each starting from a fresh context (no conversation history). All state lives in a structured `ConsultationState` object. The workspace is git-versioned for full reproducibility.
+
+```
+                    ┌─────────────┐
+                    │   Client    │
+                    │  Question   │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │  Surveyor   │  Maps legal landscape (once)
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │   Planner   │  Research strategy
+                    └──────┬──────┘
+                           │
+              ┌────────────▼────────────┐
+              │      Orchestrator       │  Dispatches tasks
+              └───┬─────────────────┬───┘
+                  │                 │
+           ┌──────▼──────┐  ┌──────▼──────┐
+           │ Researcher  │  │   Analyst   │
+           │ (case law,  │  │ (deadlines, │
+           │ legislation)│  │  penalties) │
+           └──────┬──────┘  └──────┬──────┘
+                  │                 │
+              ┌───▼─────────────────▼───┐
+              │       Reviewer          │  Adversarial verification
+              └────────────┬────────────┘
+                           │
+              ┌────────────▼────────────┐
+              │    Critic (periodic)    │  Strategy audit
+              └──────┬──────────┬───────┘
+                     │          │
+              ┌──────▼──┐ ┌────▼────────┐
+              │ Planner │ │ Adjudicator │  Resolve disputes
+              │(revise) │ └─────────────┘
+              └─────────┘
+                           │
+              ┌────────────▼────────────┐
+              │       Formatter         │  Final consultation
+              └─────────────────────────┘
+```
+
+### Agent Roles
+
+| Agent | Role | secondlayer-core Equivalent |
+|-------|------|---------------------------|
+| **Surveyor** | Maps legal landscape, identifies relevant areas of law | IntentClassifier + QueryPlanner |
+| **Planner** | Produces/revises research strategy | ExecutionPlan generation |
+| **Orchestrator** | Dispatches tasks, formulates hypotheses | ChatService agentic loop |
+| **Researcher** | Finds case law, legislation, doctrine via SecondLayer MCP | Tool calls (search, legislation) |
+| **Analyst** | Computes deadlines, penalties, procedural checks | Calculation tool calls |
+| **Reviewer** | Adversarial verification of evidence | CitationValidator + HallucinationGuard |
+| **Critic** | Periodic strategy and coherence audit | *New capability* |
+| **Adjudicator** | Resolves inter-agent disagreements | *New capability* |
+| **Formatter** | Produces structured legal consultation | Response synthesis |
+
+### Key Design Decisions
+
+1. **No agent carries conversation history** -- each call starts from a fresh context with the current `ConsultationState` rendered as text. This prevents context contamination and allows any agent to be swapped or retried independently.
+
+2. **Structured state** -- `ConsultationState` tracks hypotheses, evidence, critiques, and their relationships. Agents mutate state via typed operations, not free-form text.
+
+3. **Git-versioned workspace** -- every iteration creates a commit, making the full research process reproducible and auditable.
+
+4. **SecondLayer MCP bridge** -- agents access 100M+ court decisions, legislation, and Supreme Court positions through the SecondLayer API.
+
+## Quick Start
+
+```bash
+# Install
+pip install -e .
+
+# Set API keys
+export ANTHROPIC_API_KEY=sk-...
+export SECONDLAYER_API_KEY=...
+
+# Run a consultation
+legal-intern "Чи може продавець стягнути пеню за прострочення оплати товару?"
+
+# Run from a problem file
+legal-intern problems/consumer_penalty.yaml
+```
+
+## Example Problems
+
+| Problem | Difficulty | Description |
+|---------|-----------|-------------|
+| `consumer_penalty.yaml` | Medium | Penalty and interest calculation for late payment |
+| `labor_dismissal.yaml` | Hard | Challenging unlawful dismissal during martial law |
+| `property_dispute.yaml` | Hard | Property rights in unregistered partnership |
+
+## Data Sources
+
+- [EDRSR](https://reyestr.court.gov.ua/) -- 100M+ Ukrainian court decisions
+- [Verkhovna Rada](https://zakon.rada.gov.ua/) -- Ukrainian legislation
+- [overthelex/ua-case-outcome-6m](https://huggingface.co/datasets/overthelex/ua-case-outcome-6m) -- 6.7M court decisions dataset
+- [overthelex/ukrainian-court-decisions](https://huggingface.co/datasets/overthelex/ukrainian-court-decisions) -- 428K balanced benchmark
+
+## Related Papers
+
+- [Temporal Decay of Co-Citation Predictability](https://arxiv.org/abs/2605.17639)
+- [A Citation Graph from 100M Court Decisions](https://arxiv.org/abs/2605.15362)
+- [Tokenizer Fertility and Zero-Shot Performance on Ukrainian Legal Text](https://arxiv.org/abs/2605.14890)
+
+## License
+
+Apache-2.0

app.py

@@ -0,0 +1,343 @@
+"""Gradio app for the LegalIntern HuggingFace Space.
+
+Interactive demo of the multi-agent legal consultation pipeline.
+Shows the agent flow, state evolution, and final consultation.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+import gradio as gr
+
+from src.legal_intern.state.research_state import (
+    ConsultationState,
+    LegalEvidence,
+    LegalHypothesis,
+    LegalStrategy,
+)
+from src.legal_intern.rendering import render_state_md
+
+
+EXAMPLE_QUESTIONS = [
+    "Покупець не оплатив товар на 150 000 грн протягом 6 місяців. Як стягнути пеню, 3% річних та інфляційні?",
+    "Працівника звільнено під час воєнного стану без попередження. Чи є підстави для поновлення?",
+    "Чи може жінка претендувати на частку квартири після 8 років цивільного шлюбу?",
+    "Забудовник затримує введення будинку в експлуатацію на 2 роки. Які компенсації можна вимагати?",
+]
+
+ARCHITECTURE_MD = """
+## Архітектура LegalIntern
+
+Дев'ять спеціалізованих LLM-агентів працюють у циклі. Кожен агент починає з чистого контексту
+(без історії розмови). Весь стан зберігається у структурованому об'єкті `ConsultationState`.
+
+### Pipeline
+
+```
+Запит клієнта
+     │
+     ▼
+┌─────────────┐
+│  Surveyor   │  Огляд правового ландшафту
+└──────┬──────┘
+       ▼
+┌─────────────┐
+│   Planner   │  Стратегія дослідження
+└──────┬──────┘
+       ▼
+┌─────────────┐     ┌────────────┐
+│Orchestrator │────►│ Researcher │  Судова практика, НПА
+│ (dispatch)  │────►│  Analyst   │  Обчислення, строки
+└──────┬──────┘     └─────┬──────┘
+       │                  │
+       ▼                  ▼
+┌─────────────┐   ┌────────────┐
+│  Reviewer   │   │   Critic   │  Аудит стратегії
+│(верифікація)│   │ (periodic) │
+└──────┬──────┘   └─────┬──────┘
+       │                │
+       ▼                ▼
+┌─────────────┐  ┌──────────────┐
+│ Adjudicator │  │   Planner    │
+│  (арбітраж) │  │  (revision)  │
+└──────┬──────┘  └──────────────┘
+       ▼
+┌─────────────┐
+│  Formatter  │  Фінальна консультація
+└─────────────┘
+```
+
+### Агенти
+
+| Агент | Роль | Аналог в secondlayer-core |
+|-------|------|--------------------------|
+| **Surveyor** | Карта правового ландшафту | IntentClassifier + QueryPlanner |
+| **Planner** | Стратегія дослідження | Генерація ExecutionPlan |
+| **Orchestrator** | Координація та гіпотези | Агентний цикл ChatService |
+| **Researcher** | Пошук практики та НПА | Виклики інструментів |
+| **Analyst** | Обчислення строків, сум | Калькуляційні інструменти |
+| **Reviewer** | Верифікація доказів | CitationValidator + HallucinationGuard |
+| **Critic** | Аудит стратегії | *Нова можливість* |
+| **Adjudicator** | Арбітраж розбіжностей | *Нова можливість* |
+| **Formatter** | Оформлення консультації | Синтез відповіді |
+
+### Ключові принципи
+
+1. **Жоден агент не несе історію** -- кожен виклик починає з чистого контексту
+2. **Структурований стан** -- гіпотези, докази, зауваження зі зв'язками між ними
+3. **Git-версіонування** -- кожна ітерація = коміт, повна відтворюваність
+4. **SecondLayer MCP bridge** -- доступ до 100М+ рішень суду, законодавства, позицій ВС
+
+### Порівняння з PhysicsIntern
+
+| Аспект | PhysicsIntern | LegalIntern |
+|--------|--------------|-------------|
+| Домен | Теоретична фізика | Українське право |
+| Researcher | Аналітичні міркування | Пошук у ЄДРСР + НПА |
+| Computer | Виконання Python коду | Обчислення пені, строків |
+| Верифікація | Formal evaluation | Перевірка посилань |
+| Стан | ResearchState (hypotheses) | ConsultationState (правові позиції) |
+| Вихід | ANSWER.md | CONSULTATION.md |
+"""
+
+DEMO_STATE = ConsultationState(
+    client_question="Покупець не оплатив товар на 150 000 грн протягом 6 місяців. Як стягнути пеню?",
+    jurisdiction="civil",
+    title="Стягнення пені за прострочення оплати",
+    survey_summary="Питання стосується цивільно-правової відповідальності за порушення грошового зобов'язання...",
+    strategy=LegalStrategy(
+        approach="Стягнення на підставі ст. 549-552 ЦК (пеня), ст. 625 ЦК (3% річних + інфляційні)",
+        legal_domains=["цивільне право", "зобов'язальне право"],
+        key_questions=[
+            "Чи передбачена пеня договором?",
+            "Який розмір 3% річних та інфляційних?",
+            "Яка позиція ВС щодо одночасного стягнення?",
+        ],
+        relevant_legislation=["ст. 549-552 ЦК України", "ст. 625 ЦК України", "ст. 3 ЗУ 'Про відповідальність за несвоєчасне виконання грошових зобов'язань'"],
+    ),
+    iteration=5,
+)
+DEMO_STATE._hyp_counter = 2
+DEMO_STATE.hypotheses = [
+    LegalHypothesis(
+        id="H-001",
+        statement="Продавець має право на пеню за ст. 549 ЦК якщо це передбачено договором",
+        status="established",
+        supporting_evidence=["EV-001", "EV-003"],
+    ),
+    LegalHypothesis(
+        id="H-002",
+        statement="3% річних та інфляційні нараховуються незалежно від пені (ст. 625 ЦК)",
+        status="established",
+        supporting_evidence=["EV-002", "EV-004"],
+    ),
+]
+DEMO_STATE._ev_counter = 4
+DEMO_STATE.evidence = [
+    LegalEvidence(id="EV-001", type="legislation", source="rada", citation="ст. 549 ЦК України", summary="Неустойкою (штрафом, пенею) є грошова сума, яку боржник повинен передати кредиторові у разі порушення зобов'язання", confidence="high"),
+    LegalEvidence(id="EV-002", type="legislation", source="rada", citation="ст. 625 ЦК України", summary="Боржник зобов'язаний сплатити 3% річних та відшкодувати інфляційні втрати", confidence="high"),
+    LegalEvidence(id="EV-003", type="case_law", source="edrsr", citation="Справа №757/12345/22", summary="ВС: пеня нараховується з дня, наступного за останнім днем строку оплати", confidence="high"),
+    LegalEvidence(id="EV-004", type="case_law", source="edrsr", citation="ВП ВС, справа №910/5678/21", summary="Одночасне стягнення пені та 3% річних є правомірним, оскільки вони мають різну правову природу", confidence="high"),
+]
+
+
+def show_architecture():
+    return ARCHITECTURE_MD
+
+
+def show_demo_state():
+    return render_state_md(DEMO_STATE)
+
+
+def show_demo_json():
+    return json.dumps(DEMO_STATE.to_dict(), ensure_ascii=False, indent=2)
+
+
+def run_demo_consultation(question: str, progress=gr.Progress()):
+    """Simulate a consultation run (demo mode without real LLM calls)."""
+    if not question.strip():
+        return "Будь ласка, введіть правове питання.", "", ""
+
+    progress(0.1, desc="Surveyor: огляд правового ландшафту...")
+    progress(0.25, desc="Planner: розробка стратегії...")
+    progress(0.4, desc="Researcher: пошук судової практики...")
+    progress(0.55, desc="Analyst: обчислення сум...")
+    progress(0.7, desc="Reviewer: верифікація доказів...")
+    progress(0.85, desc="Critic: аудит стратегії...")
+    progress(0.95, desc="Formatter: оформлення консультації...")
+
+    demo_answer = f"""# ПРАВОВА КОНСУЛЬТАЦІЯ
+
+## 1. Питання клієнта
+{question}
+
+## 2. Правовий аналіз
+
+> Це демо-режим. У повній версії LegalIntern виконує реальний пошук
+> по 100М+ рішень суду в ЄДРСР та аналізує чинне законодавст��о.
+
+### 2.1. Застосовне законодавство
+- Цивільний кодекс України (ст. 549-552, 625)
+- Закон України "Про відповідальність за несвоєчасне виконання грошових зобов'язань"
+
+### 2.2. Судова практика
+- Позиція Верховного Суду щодо одночасного стягнення пені та 3% річних
+
+## 3. Висновок
+Для отримання повної консультації з реальними посиланнями на судову практику
+та обчисленнями, запустіть LegalIntern з API ключами SecondLayer та Anthropic.
+
+## 4. Рекомендації
+1. Встановіть `ANTHROPIC_API_KEY` та `SECONDLAYER_API_KEY`
+2. Запустіть: `legal-intern "{question[:50]}..."`
+
+---
+*Demo mode -- real consultations require API access to SecondLayer (legal.org.ua)*
+"""
+
+    state_md = f"""# Стан консультації (демо)
+- Питання: {question[:80]}...
+- Ітерацій: 5 (демо)
+- Гіпотез: 2 (встановлено: 2)
+- Доказів: 4 (спростовано: 0)
+"""
+
+    return demo_answer, state_md, "Demo completed"
+
+
+# Build Gradio UI
+with gr.Blocks(
+    title="LegalIntern -- Multi-Agent Legal Consultation",
+    theme=gr.themes.Soft(),
+    css="""
+    .main-header { text-align: center; margin-bottom: 1rem; }
+    .agent-flow { font-family: monospace; }
+    """,
+) as demo:
+    gr.Markdown(
+        """
+        # ⚖️ LegalIntern
+        ### Мульти-агентна система для складних правових консультацій
+
+        Дев'ять спеціалізованих LLM-агентів працюють разом для аналізу правових питань,
+        пошуку судової практики у 100М+ рішень ЄДРСР, та формування структурованої консультації.
+
+        *Натхнення: [PhysicsIntern](https://huggingface.co/spaces/huggingface/physics-intern) |
+        Дані: [SecondLayer](https://legal.org.ua) |
+        Код: [GitHub](https://github.com/overthelex/secondlayer-agents)*
+        """,
+        elem_classes="main-header",
+    )
+
+    with gr.Tabs():
+        with gr.Tab("Консультація (демо)"):
+            with gr.Row():
+                with gr.Column(scale=2):
+                    question_input = gr.Textbox(
+                        label="Правове питання",
+                        placeholder="Опишіть вашу правову ситуацію...",
+                        lines=4,
+                    )
+                    gr.Examples(
+                        examples=[[q] for q in EXAMPLE_QUESTIONS],
+                        inputs=question_input,
+                    )
+                    run_btn = gr.Button("Запустити консультацію", variant="primary")
+
+                with gr.Column(scale=1):
+                    status_output = gr.Textbox(label="Статус", interactive=False)
+
+            with gr.Row():
+                with gr.Column():
+                    consultation_output = gr.Markdown(label="Консультація")
+                with gr.Column():
+                    state_output = gr.Markdown(label="Стан дослідження")
+
+            run_btn.click(
+                run_demo_consultation,
+                inputs=[question_input],
+                outputs=[consultation_output, state_output, status_output],
+            )
+
+        with gr.Tab("Архітектура"):
+            gr.Markdown(ARCHITECTURE_MD)
+
+        with gr.Tab("ConsultationState (приклад)"):
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### Rendered Markdown")
+                    gr.Markdown(render_state_md(DEMO_STATE))
+                with gr.Column():
+                    gr.Markdown("### Raw JSON")
+                    gr.Code(
+                        json.dumps(DEMO_STATE.to_dict(), ensure_ascii=False, indent=2),
+                        language="json",
+                    )
+
+        with gr.Tab("Порівняння з PhysicsIntern"):
+            gr.Markdown("""
+## PhysicsIntern vs LegalIntern
+
+Обидві системи використовують однаковий патерн: 9 спеціалізованих агентів,
+структурований стан, git-версіонування, відсутність історії у агентів.
+
+| Компонент | PhysicsIntern | LegalIntern |
+|-----------|--------------|-------------|
+| **Домен** | Теоретична фізика, математика | Українське цивільне/господарське право |
+| **Surveyor** | Огляд наукового ландшафту | Огляд правового ландшафту |
+| **Researcher** | Аналіти��ні деривації | Пошук у ЄДРСР (100М+ рішень) |
+| **Computer** | Виконання Python коду | Обчислення пені, строків, інфляційних |
+| **Reviewer** | VERIFIED/REFUTED/INCONCLUSIVE | Верифікація посилань + галюцінацій |
+| **Critic** | Стратегія + когерентність | Повнота аналізу + контр-аргументи |
+| **State** | `ResearchState` (гіпотези, докази) | `ConsultationState` (правові позиції, докази) |
+| **Tools** | Python sandbox | SecondLayer MCP API |
+| **Output** | `ANSWER.md` | `CONSULTATION.md` |
+| **Benchmark** | CritPT (фізика) | UA Court Decisions (6.7M) |
+| **LLM** | Multi-provider (Anthropic, OpenAI, Gemini, HF) | Anthropic + OpenAI |
+
+### Що LegalIntern додає
+
+1. **SecondLayer MCP Bridge** -- прямий доступ до ЄДРСР, zakon.rada.gov.ua, ЄСПЛ
+2. **Юридична верифікація** -- перевірка існування справ, актуальності НПА
+3. **Обчислення** -- пеня (ст. 549-552 ЦК), 3% річних (ст. 625), інфляційні, строки
+4. **Українська мова** -- всі промпти та вихід українською
+
+### Що SecondLayer вже має (secondlayer-core)
+
+| Компонент | Опис |
+|-----------|------|
+| IntentClassifier | Класифікація запиту (LLM + regex fallback) |
+| QueryPlanner | Маршрутизація до доменів (court, npa, echr) |
+| ChatService | Агентний цикл з tool_use |
+| CitationValidator | Перевірка посилань на рішення суду |
+| HallucinationGuard | Виявлення фабрикованих номерів справ |
+| ShepardizationService | Перевірка актуальності правових позицій |
+| EvidenceExtractor | Витяг рішень, цитат, документів |
+
+LegalIntern переосмислює цей pipeline як мульти-агентну систему з
+експліцитним станом, критичним оглядом та арбітражем.
+            """)
+
+        with gr.Tab("Датасети"):
+            gr.Markdown("""
+## Пов'язані датасети на HuggingFace
+
+| Датасет | Розмір | Опис |
+|---------|--------|------|
+| [ua-case-outcome-6m](https://huggingface.co/datasets/overthelex/ua-case-outcome-6m) | 6.7M | Повний датасет рішень суду з темпоральними спліттами |
+| [ukrainian-court-decisions](https://huggingface.co/datasets/overthelex/ukrainian-court-decisions) | 428K | Збалансований бенчмарк для LEXTREME |
+| [ua-court-citation-graph](https://huggingface.co/datasets/overthelex/ua-court-citation-graph) | 2.3M | Граф ко-цитування з 99.5М рішень |
+| [ua-statute-retrieval](https://huggingface.co/datasets/overthelex/ua-statute-retrieval) | 396M citations | Бенчмарк пошуку законодавства |
+| [ua-temporal-drift](https://huggingface.co/datasets/overthelex/ua-temporal-drift) | 428K | Дані про темпоральний дрифт |
+
+## Пов'язані статті
+
+- [Temporal Decay of Co-Citation Predictability](https://arxiv.org/abs/2605.17639) (arXiv, 2025)
+- [A Citation Graph from 100M Court Decisions](https://arxiv.org/abs/2605.15362) (arXiv, 2025)
+- [Tokenizer Fertility on Ukrainian Legal Text](https://arxiv.org/abs/2605.14890) (arXiv, 2025)
+            """)
+
+if __name__ == "__main__":
+    demo.launch()

problems/consumer_penalty.yaml

@@ -0,0 +1,14 @@
+title: "Стягнення пені та 3% річних за прострочення оплати товару"
+question: |
+  Покупець придбав товар на суму 150 000 грн за договором купівлі-продажу від 15.01.2024.
+  Строк оплати -- 30 днів з моменту поставки. Товар поставлено 20.01.2024.
+  Станом на сьогодні оплата не здійснена.
+
+  Чи може продавець стягнути пеню, 3% річних та інфляційні втрати?
+  Як розрахувати суми? Які строки давності? Яка судова практика ВС?
+jurisdiction: civil
+difficulty: medium
+expected_tools:
+  - get_legislation  # ст. 549-552, 625 ЦК
+  - search_court_decisions  # практика ВС
+  - compute_penalty  # розрахунок пені

problems/labor_dismissal.yaml

@@ -0,0 +1,15 @@
+title: "Оскарження незаконного звільнення під час воєнного стану"
+question: |
+  Працівника звільнено з посади 10.03.2026 на підставі п. 1 ч. 1 ст. 40 КЗпП
+  (зміни в організації виробництва та праці) під час дії воєнного стану.
+  Працівник стверджує, що: (1) не було попередження за 2 місяці, (2) не запропоновано
+  іншу роботу, (3) не враховано переважне право на залишення на роботі.
+
+  Чи є підстави для поновлення на роботі? Які компенсації можна стягнути?
+  Як впливає воєнний стан на процедуру звільнення?
+jurisdiction: civil
+difficulty: hard
+expected_tools:
+  - get_legislation  # КЗпП, Закон про воєнний стан
+  - search_court_decisions  # практика щодо звільнення під час ВС
+  - search_supreme_court  # позиції ВС

problems/property_dispute.yaml

@@ -0,0 +1,15 @@
+title: "Визнання права власності на частку в квартирі (цивільне шлюбне партнерство)"
+question: |
+  Жінка проживала з чоловіком у фактичних шлюбних відносинах (без реєстрації шлюбу)
+  протягом 8 років (2016-2024). За цей час було придбано квартиру, оформлену на чоловіка.
+  Обидва брали участь у виплаті іпотечного кредиту (є документальне підтвердження).
+  Чоловік відмовляється визнати її права на частку.
+
+  Чи може жінка претендувати на частку? Яка процедура? Які шанси у суді?
+  Яка позиція ВС щодо майна в цивільних шлюбних партнерствах?
+jurisdiction: civil
+difficulty: hard
+expected_tools:
+  - get_legislation  # СК, ЦК (спільна часткова власність)
+  - search_court_decisions
+  - search_supreme_court  # ВП ВС щодо цивільного шлюбу

pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "legal-intern"
+version = "0.1.0"
+description = "Multi-agent scaffolding for complex legal consultations over Ukrainian court decisions"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [
+    { name = "Volodymyr Ovcharov", email = "mcvovkes@gmail.com" },
+]
+keywords = ["legal-nlp", "multi-agent", "legal-consultation", "ukraine", "court-decisions"]
+
+dependencies = [
+    "anthropic>=0.40.0",
+    "openai>=1.50.0",
+    "rich>=13.7",
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "tiktoken>=0.7",
+]
+
+[project.optional-dependencies]
+testing = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-asyncio>=0.23",
+]
+quality = [
+    "ruff>=0.5",
+]
+all-providers = [
+    "google-genai>=1.0",
+    "huggingface-hub>=0.25",
+]
+
+[project.scripts]
+legal-intern = "legal_intern.main:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

src/legal_intern/__init__.py

@@ -0,0 +1,3 @@
+"""LegalIntern -- multi-agent scaffolding for complex legal consultations."""
+
+__version__ = "0.1.0"

src/legal_intern/agents/__init__.py

@@ -0,0 +1,23 @@
+from .base import BaseAgent
+from .surveyor import SurveyorAgent
+from .planner import PlannerAgent
+from .orchestrator import OrchestratorAgent
+from .researcher import ResearcherAgent
+from .analyst import AnalystAgent
+from .reviewer import ReviewerAgent
+from .critic import CriticAgent
+from .adjudicator import AdjudicatorAgent
+from .formatter import FormatterAgent
+
+__all__ = [
+    "BaseAgent",
+    "SurveyorAgent",
+    "PlannerAgent",
+    "OrchestratorAgent",
+    "ResearcherAgent",
+    "AnalystAgent",
+    "ReviewerAgent",
+    "CriticAgent",
+    "AdjudicatorAgent",
+    "FormatterAgent",
+]

src/legal_intern/agents/adjudicator.py

@@ -0,0 +1,100 @@
+"""Adjudicator agent -- resolves disagreements between agents.
+
+Analogous to physics-intern's Adjudicator.
+Invoked when a critique challenges an established hypothesis or
+when reviewer and researcher disagree.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+ADJUDICATOR_SYSTEM_PROMPT = """\
+Ти -- Арбітр правового дослідження (Legal Adjudicator). Тебе викликають коли \
+є розбіжність між агентами або коли зауваження оскаржує встановлену позицію.
+
+Ти отримуєш:
+- Оскаржувану гіпотезу з її доказами
+- Зауваження, що її оскаржує
+- Контекст дослідження
+
+Ти маєш:
+1. Об'єктивно оцінити обидві сторони
+2. Вирішити, чи гіпотеза залишається "established" чи повертається у "working"
+3. Якщо зауваження обгрунтоване -- вказати, які додаткові дослідження потрібні
+
+Поверни JSON:
+{
+  "decision": "uphold" | "reopen" | "refute",
+  "reasoning": "обгрунтування рішення",
+  "additional_research": ["список додаткових питань"] | null
+}
+"""
+
+
+class AdjudicatorAgent(BaseAgent):
+    role = "adjudicator"
+    description = "Арбітраж розбіжностей між агентами"
+
+    async def run(
+        self,
+        state: ConsultationState,
+        hypothesis_id: str = "",
+        critique_id: str = "",
+        **kwargs: Any,
+    ) -> AgentResult:
+        from ..providers import call_llm
+        from ..state.research_state import CritiqueStatus, HypothesisStatus
+
+        context = self._build_state_context(state)
+
+        # Find the disputed hypothesis and critique
+        hyp = next((h for h in state.hypotheses if h.id == hypothesis_id), None)
+        crit = next((c for c in state.critiques if c.id == critique_id), None)
+
+        dispute_text = ""
+        if hyp:
+            supporting = [
+                ev for ev in state.evidence if ev.id in hyp.supporting_evidence and not ev.refuted
+            ]
+            dispute_text += f"\n# Оскаржувана позиція: {hyp.statement}\n"
+            dispute_text += f"Підтверджуючі докази: {', '.join(ev.citation for ev in supporting)}\n"
+        if crit:
+            dispute_text += f"\n# Зауваження: {crit.summary}\n{crit.details}"
+
+        user_msg = f"{context}\n{dispute_text}"
+
+        response = await call_llm(
+            self.config,
+            system=ADJUDICATOR_SYSTEM_PROMPT,
+            user=user_msg,
+            model_key="adjudicator",
+            json_mode=True,
+        )
+
+        result = response.parsed_json or {}
+        decision = result.get("decision", "uphold")
+
+        if hyp:
+            if decision == "refute":
+                hyp.status = HypothesisStatus.REFUTED
+            elif decision == "reopen":
+                hyp.status = HypothesisStatus.WORKING
+
+        if crit:
+            crit.status = CritiqueStatus.RESOLVED
+
+        for q in result.get("additional_research", []) or []:
+            state.add_question(q, iteration=state.iteration)
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Рішення: {decision} для {hypothesis_id}",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/analyst.py

@@ -0,0 +1,88 @@
+"""Analyst agent -- performs legal calculations and procedural verification.
+
+Analogous to physics-intern's Computer agent (code execution).
+In secondlayer-core this maps to: tool calls that compute statutory deadlines,
+calculate penalties (пеня, 3% річних, інфляційні), verify procedural requirements.
+
+This agent can execute Python code for precise calculations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+ANALYST_SYSTEM_PROMPT = """\
+Ти -- Правовий аналітик-обчислювач (Legal Analyst). Твоя роль -- виконувати \
+точні обчислення та процедурну верифікацію.
+
+Типи завдань:
+1. **Обчислення сум**: пеня (ст. 549-552 ЦК), 3% річних (ст. 625 ЦК), \
+   інфляційні втрати, держмито, судові витрати
+2. **Процесуальні строки**: обчислення строків подання позову, апеляції, \
+   касації з урахуванням вихідних, святкових, воєнного стану
+3. **Строки давності**: загальна (3р), спеціальна (1р, 5р, 10р) з урахуванням \
+   зупинення/переривання
+4. **Верифікація вимог**: перевірка процесуальних передумов (досудове врегулювання, \
+   підсудність, належний відповідач)
+
+Ти можеш писати та виконувати Python код для точних обчислень.
+
+Поверни JSON:
+{
+  "calculation_type": "penalty" | "deadline" | "limitation" | "verification",
+  "inputs": { ... },
+  "result": "точний результат",
+  "formula": "формула або норма, що застосована",
+  "code": "Python код (якщо використано)",
+  "notes": "застереження та умови"
+}
+"""
+
+
+class AnalystAgent(BaseAgent):
+    role = "analyst"
+    description = "Обчислення сум, строків, верифікація процедурних вимог"
+
+    async def run(
+        self,
+        state: ConsultationState,
+        task_description: str = "",
+        **kwargs: Any,
+    ) -> AgentResult:
+        from ..providers import call_llm
+
+        context = self._build_state_context(state)
+        user_msg = f"{context}\n\n# Завдання на обчислення\n{task_description}"
+
+        response = await call_llm(
+            self.config,
+            system=ANALYST_SYSTEM_PROMPT,
+            user=user_msg,
+            model_key="analyst",
+            json_mode=True,
+        )
+
+        result = response.parsed_json or {}
+
+        ev = state.add_evidence(
+            type="computation",
+            source="manual",
+            citation=result.get("formula", ""),
+            summary=result.get("result", response.content),
+            full_text=result.get("code", ""),
+            relevance=result.get("notes", ""),
+            confidence="high" if result.get("code") else "medium",
+            iteration=state.iteration,
+        )
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Обчислення: {result.get('calculation_type', '?')} = {result.get('result', '')[:60]}",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/base.py

@@ -0,0 +1,86 @@
+"""Base agent -- all agents inherit from this.
+
+Each agent call starts from a fresh context (no conversation history).
+The agent reads ConsultationState, performs its task, and mutates state via tools.
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core.config import Config
+    from ..core.workspace import WorkspaceManager
+    from ..state.research_state import ConsultationState
+
+
+@dataclass
+class AgentResult:
+    success: bool
+    agent: str
+    summary: str = ""
+    tokens_used: int = 0
+    duration_sec: float = 0.0
+    error: str = ""
+
+
+class BaseAgent(ABC):
+    """Base class for all LegalIntern agents."""
+
+    role: str = "base"
+    description: str = ""
+
+    def __init__(self, config: Config, workspace: WorkspaceManager) -> None:
+        self.config = config
+        self.workspace = workspace
+
+    @abstractmethod
+    async def run(self, state: ConsultationState, **kwargs: Any) -> AgentResult:
+        """Execute the agent's task and mutate state."""
+        ...
+
+    def _build_state_context(self, state: ConsultationState) -> str:
+        """Render current state as a text summary for the LLM prompt."""
+        parts = []
+        parts.append(f"# Запит клієнта\n{state.client_question}")
+
+        if state.jurisdiction:
+            parts.append(f"**Юрисдикція**: {state.jurisdiction}")
+
+        if state.survey_summary:
+            parts.append(f"# Огляд правового ландшафту\n{state.survey_summary}")
+
+        if state.strategy.approach:
+            parts.append(f"# Стратегія\n{state.strategy.approach}")
+            if state.strategy.key_questions:
+                parts.append("**Ключові питання**: " + "; ".join(state.strategy.key_questions))
+            if state.strategy.relevant_legislation:
+                parts.append(
+                    "**Релевантне законодавство**: "
+                    + "; ".join(state.strategy.relevant_legislation)
+                )
+
+        if state.hypotheses:
+            parts.append("# Правові позиції")
+            for h in state.hypotheses:
+                parts.append(f"- {h.short()}")
+
+        if state.evidence:
+            parts.append("# Зібрані докази")
+            for ev in state.evidence:
+                parts.append(f"- {ev.short()}")
+
+        if state.open_questions():
+            parts.append("# Відкриті питання")
+            for q in state.open_questions():
+                parts.append(f"- [{q.id}] {q.question}")
+
+        if state.active_critiques():
+            parts.append("# Активні зауваження")
+            for c in state.active_critiques():
+                parts.append(f"- [{c.id}] ({c.severity}) {c.summary}")
+
+        return "\n\n".join(parts)

src/legal_intern/agents/critic.py

@@ -0,0 +1,89 @@
+"""Critic agent -- senior legal advisor that audits strategy and coherence.
+
+Analogous to physics-intern's Deep Critic (periodic audit).
+In secondlayer-core this is a new capability -- currently there's no
+meta-level strategy review, only per-evidence validation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+CRITIC_SYSTEM_PROMPT = """\
+Ти -- Старший правовий радник (Senior Legal Advisor). Твоя роль -- періодично \
+перевіряти загальну стратегію та якість дослідження.
+
+Ти маєш оцінити:
+1. **Стратегія**: чи правильно обрано підхід? Чи немає кращої правової позиції?
+2. **Повнота**: чи всі ключові аспекти розглянуто? Чи немає прогалин?
+3. **Узгодженість**: чи не суперечать докази один одному? Чи послідовна аргументація?
+4. **Посилання**: чи достатньо підкріплені позиції судовою практикою та НПА?
+5. **Ризики**: чи враховані контр-аргументи опонента?
+
+Типи зауважень:
+- "strategy": стратегія потребує ревізії (маршрутизується до Planner)
+- "reasoning": помилка в міркуваннях (маршрутизується до Orchestrator)
+- "completeness": прогалина в дослідженні (генерує нові RQ)
+- "citation": проблема з посиланнями (маршрутизується до Researcher)
+
+Поверни JSON:
+{
+  "overall_assessment": "strong" | "adequate" | "weak",
+  "critiques": [
+    {
+      "type": "strategy" | "reasoning" | "completeness" | "citation",
+      "severity": "high" | "medium" | "low",
+      "summary": "коротке зауваження",
+      "details": "повне обгрунтування",
+      "target_hypothesis": "H-NNN" | null
+    }
+  ],
+  "can_proceed_to_answer": true | false
+}
+"""
+
+
+class CriticAgent(BaseAgent):
+    role = "critic"
+    description = "Аудит стратегії, повноти та узгодженості дослідження"
+
+    async def run(self, state: ConsultationState, **kwargs: Any) -> AgentResult:
+        from ..providers import call_llm
+
+        context = self._build_state_context(state)
+
+        response = await call_llm(
+            self.config,
+            system=CRITIC_SYSTEM_PROMPT,
+            user=context,
+            model_key="critic",
+        )
+
+        result = response.parsed_json or {}
+        critiques = result.get("critiques", [])
+
+        for c in critiques:
+            state.add_critique(
+                type=c.get("type", "reasoning"),
+                severity=c.get("severity", "medium"),
+                summary=c.get("summary", ""),
+                details=c.get("details", ""),
+                target_hypothesis=c.get("target_hypothesis", ""),
+                iteration=state.iteration,
+            )
+
+        can_proceed = result.get("can_proceed_to_answer", False)
+        assessment = result.get("overall_assessment", "unknown")
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Оцінка: {assessment}, зауважень: {len(critiques)}, "
+            f"можна завершувати: {can_proceed}",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/formatter.py

@@ -0,0 +1,102 @@
+"""Formatter agent -- produces the final consultation document.
+
+Analogous to physics-intern's Formatter (produces ANSWER.md).
+This agent takes the established hypotheses, verified evidence, and
+strategy to produce a structured legal consultation in Ukrainian.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+FORMATTER_SYSTEM_PROMPT = """\
+Ти -- Оформлювач правової консультації (Legal Consultation Formatter). Твоя роль -- \
+перетворити результати дослідження у структуровану правову консультацію для клієнта.
+
+Формат консультації:
+
+# ПРАВОВА КОНСУЛЬТАЦІЯ
+
+## 1. Питання клієнта
+(переформулювання питання юридичною мовою)
+
+## 2. Правовий аналіз
+### 2.1. Застосовне законодавство
+(перелік НПА та статей з коротким поясненням)
+
+### 2.2. Судова практика
+(ключові позиції ВС та інших судів з посиланнями на конкретні справи)
+
+### 2.3. Аналіз ситуації клієнта
+(застосування норм та практики до конкретних обставин)
+
+## 3. Висновок
+(чітка правова позиція з обгрунтуванням)
+
+## 4. Рекомендації
+(конкретні кроки, які клієнт має зробити)
+
+## 5. Ризики
+(потенційні слабкі сторони позиції та контр-аргументи)
+
+## 6. Додатки
+(обчислення сум, строків, якщо застосовно)
+
+---
+Посилання на джерела (кожне посилання має бути верифіковане):
+[1] ...
+
+ВИМОГИ:
+- Писати українською мовою
+- Кожне твердження підкріплювати посиланням на EV-NNN
+- Використовувати ТІЛЬКИ верифіковані (не refuted) докази
+- Обчислення мають бути з конкретними цифрами
+- Тон: професійний, але зрозумілий для клієнта
+"""
+
+
+class FormatterAgent(BaseAgent):
+    role = "formatter"
+    description = "Оформлення фінальної правової консультації"
+
+    async def run(self, state: ConsultationState, **kwargs: Any) -> AgentResult:
+        from ..providers import call_llm
+
+        context = self._build_state_context(state)
+
+        # Build evidence reference for the formatter
+        verified_evidence = [ev for ev in state.evidence if not ev.refuted]
+        ev_ref = "\n".join(
+            f"- {ev.id}: [{ev.type}] {ev.citation} -- {ev.summary}" for ev in verified_evidence
+        )
+
+        established = state.established_hypotheses()
+        hyp_ref = "\n".join(f"- {h.id}: {h.statement}" for h in established)
+
+        user_msg = (
+            f"{context}\n\n"
+            f"# Встановлені правові позиції\n{hyp_ref}\n\n"
+            f"# Верифіковані докази ({len(verified_evidence)})\n{ev_ref}\n\n"
+            f"Сформуй фінальну правову консультацію."
+        )
+
+        response = await call_llm(
+            self.config,
+            system=FORMATTER_SYSTEM_PROMPT,
+            user=user_msg,
+            model_key="formatter",
+        )
+
+        state.answer = response.content
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Консультація: {len(response.content)} символів",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/orchestrator.py

@@ -0,0 +1,85 @@
+"""Orchestrator agent -- dispatches research tasks to researcher or analyst.
+
+Analogous to physics-intern's Orchestrator: decides what to investigate next,
+dispatches to Researcher (case law / legislation lookup) or Analyst (calculations),
+and formulates working hypotheses from the evidence.
+
+In secondlayer-core this maps to the ChatService agentic loop that selects
+tool calls and routes between search, legislation, and analysis tools.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+ORCHESTRATOR_SYSTEM_PROMPT = """\
+Ти -- Оркестратор правового дослідження (Legal Research Orchestrator). Твоя роль -- \
+координувати хід дослідження, визначаючи наступні кроки.
+
+На основі поточного стану (стратегія, зібрані докази, відкриті питання, зауваження) \
+ти маєш:
+
+1. Обрати наступне питання для дослідження (або відповісти на зауваження)
+2. Визначити тип завдання:
+   - "research": пошук судової практики, аналіз законодавства, доктрини
+   - "analysis": обчислення (строки, суми, пеня, інфляція, 3% річних)
+3. Сформулювати конкретне завдання для агента-виконавця
+4. Оновити або сформулювати правову позицію (гіпотезу) на основі нових доказів
+
+Поверни JSON:
+{
+  "task_type": "research" | "analysis",
+  "question_id": "RQ-NNN" (якщо прив'язано до питання),
+  "task_description": "конкретне завдання",
+  "hypothesis_update": {  // optional
+    "id": "H-NNN" або null для нової,
+    "statement": "формулювання позиції"
+  },
+  "reasoning": "чому саме це завдання зараз"
+}
+"""
+
+
+class OrchestratorAgent(BaseAgent):
+    role = "orchestrator"
+    description = "Координація ходу дослідження та формулювання гіпотез"
+
+    async def run(self, state: ConsultationState, **kwargs: Any) -> AgentResult:
+        from ..providers import call_llm
+
+        context = self._build_state_context(state)
+
+        response = await call_llm(
+            self.config,
+            system=ORCHESTRATOR_SYSTEM_PROMPT,
+            user=context,
+            model_key="orchestrator",
+            json_mode=True,
+        )
+
+        dispatch = response.parsed_json or {}
+
+        # Update hypothesis if suggested
+        hyp_update = dispatch.get("hypothesis_update")
+        if hyp_update and hyp_update.get("statement"):
+            hyp_id = hyp_update.get("id")
+            if hyp_id:
+                for h in state.hypotheses:
+                    if h.id == hyp_id:
+                        h.statement = hyp_update["statement"]
+                        break
+            else:
+                state.add_hypothesis(hyp_update["statement"], iteration=state.iteration)
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Dispatch: {dispatch.get('task_type', '?')} -- "
+            f"{dispatch.get('task_description', '')[:60]}",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/planner.py

@@ -0,0 +1,88 @@
+"""Planner agent -- produces and revises the legal research strategy.
+
+Analogous to physics-intern's Planner: creates the initial strategy and
+revises it when critiques demand. In secondlayer-core this maps to the
+QueryPlanner + execution plan generation in ChatService.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+PLANNER_SYSTEM_PROMPT = """\
+Ти -- Стратег правової консультації (Legal Strategy Planner). Твоя роль -- \
+розробити план дослідження правового питання клієнта.
+
+На основі огляду правового ландшафту ти маєш:
+1. Сформулювати підхід до вирішення (стратегію)
+2. Визначити ключові правові питання, що потребують дослідження
+3. Пріоритезувати питання за важливістю
+4. Вказати, які джерела потрібно дослідити (судова практика, НПА, доктрина)
+5. Оцінити ризики обраної стратегії
+6. Визначити, які обчислення потрібні (строки, суми, пеня, інфляція)
+
+Якщо ти отримуєш зауваження від Senior Legal Advisor -- переглянь стратегію \
+відповідно до зауважень та поясни що змінилось.
+
+Поверни структуровану стратегію у форматі JSON з полями:
+- approach: str (опис підходу)
+- legal_domains: list[str]
+- key_questions: list[str]
+- relevant_legislation: list[str]
+- risk_factors: list[str]
+"""
+
+
+class PlannerAgent(BaseAgent):
+    role = "planner"
+    description = "Розробка та ревізія стратегії дослідження"
+
+    async def run(
+        self,
+        state: ConsultationState,
+        revision_critique: str = "",
+        **kwargs: Any,
+    ) -> AgentResult:
+        from ..providers import call_llm
+
+        context = self._build_state_context(state)
+        user_msg = context
+        if revision_critique:
+            user_msg += f"\n\n# Зауваження до стратегії (потребує ревізії)\n{revision_critique}"
+
+        response = await call_llm(
+            self.config,
+            system=PLANNER_SYSTEM_PROMPT,
+            user=user_msg,
+            model_key="planner",
+            json_mode=True,
+        )
+
+        strategy_data = response.parsed_json or {}
+        state.strategy.approach = strategy_data.get("approach", response.content)
+        state.strategy.legal_domains = strategy_data.get("legal_domains", [])
+        state.strategy.key_questions = strategy_data.get("key_questions", [])
+        state.strategy.relevant_legislation = strategy_data.get("relevant_legislation", [])
+        state.strategy.risk_factors = strategy_data.get("risk_factors", [])
+
+        if revision_critique:
+            state.strategy.revision_history.append(
+                f"Iteration {state.iteration}: revised due to critique"
+            )
+
+        for q in state.strategy.key_questions:
+            if not any(rq.question == q for rq in state.questions):
+                state.add_question(q, iteration=state.iteration)
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Стратегія: {len(state.strategy.key_questions)} питань, "
+            f"{len(state.strategy.relevant_legislation)} НПА",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/researcher.py

@@ -0,0 +1,147 @@
+"""Researcher agent -- finds and analyzes case law, legislation, doctrine.
+
+Analogous to physics-intern's Researcher (analytical reasoning).
+In secondlayer-core this maps to: tool calls for search_court_decisions,
+get_legislation, search_echr, plus the evidence extraction logic.
+
+This agent has access to SecondLayer MCP tools via the tool bridge.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+RESEARCHER_SYSTEM_PROMPT = """\
+Ти -- Правовий дослідник (Legal Researcher). Твоя роль -- знаходити та аналізувати \
+правові джерела для відповіді на конкретне дослідницьке питання.
+
+Ти маєш доступ до інструментів:
+- search_court_decisions: пошук рішень суду в ЄДРСР (100М+ документів)
+- get_legislation: отримання тексту НПА з zakon.rada.gov.ua
+- search_echr: пошук рішень ЄСПЛ
+- search_supreme_court: пошук правових позицій ВС
+
+Для кожного знайденого джерела ти маєш:
+1. Оцінити його релевантність до питання
+2. Витягнути ключову правову позицію або норму
+3. Сформулювати як це підтримує або спростовує робочу гіпотезу
+4. Надати точне посилання (номер справи, стаття закону)
+
+Поверни JSON з полями:
+{
+  "findings": [
+    {
+      "type": "case_law" | "legislation" | "doctrine" | "echr",
+      "source": "edrsr" | "rada" | "echr",
+      "citation": "точне посилання",
+      "summary": "ключовий висновок",
+      "relevance": "як стосується питання",
+      "supports_hypothesis": "H-NNN" | null,
+      "opposes_hypothesis": "H-NNN" | null,
+      "confidence": "high" | "medium" | "low"
+    }
+  ],
+  "conclusion": "загальний висновок з дослідження"
+}
+"""
+
+
+class ResearcherAgent(BaseAgent):
+    role = "researcher"
+    description = "Пошук та аналіз судової практики, законодавства, доктрини"
+
+    async def run(
+        self,
+        state: ConsultationState,
+        task_description: str = "",
+        question_id: str = "",
+        **kwargs: Any,
+    ) -> AgentResult:
+        from ..providers import call_llm
+
+        context = self._build_state_context(state)
+        user_msg = f"{context}\n\n# Поточне завдання\n{task_description}"
+        if question_id:
+            user_msg += f"\n(Питання: {question_id})"
+
+        response = await call_llm(
+            self.config,
+            system=RESEARCHER_SYSTEM_PROMPT,
+            user=user_msg,
+            model_key="researcher",
+            tools=self._get_tools(),
+            json_mode=True,
+        )
+
+        findings = (response.parsed_json or {}).get("findings", [])
+        for f in findings:
+            ev = state.add_evidence(
+                type=f.get("type", "case_law"),
+                source=f.get("source", "edrsr"),
+                citation=f.get("citation", ""),
+                summary=f.get("summary", ""),
+                relevance=f.get("relevance", ""),
+                confidence=f.get("confidence", "medium"),
+                iteration=state.iteration,
+            )
+            # Link evidence to hypotheses
+            if f.get("supports_hypothesis"):
+                for h in state.hypotheses:
+                    if h.id == f["supports_hypothesis"]:
+                        h.supporting_evidence.append(ev.id)
+            if f.get("opposes_hypothesis"):
+                for h in state.hypotheses:
+                    if h.id == f["opposes_hypothesis"]:
+                        h.opposing_evidence.append(ev.id)
+
+        # Resolve research question if assigned
+        if question_id:
+            for q in state.questions:
+                if q.id == question_id:
+                    q.answer = (response.parsed_json or {}).get("conclusion", "")
+                    q.evidence_ids = [ev.id for ev in state.evidence[-len(findings) :]]
+                    from ..state.research_state import RQStatus
+
+                    q.status = RQStatus.RESOLVED
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Знайдено {len(findings)} джерел",
+            tokens_used=response.tokens_used,
+        )
+
+    def _get_tools(self) -> list[dict]:
+        """Return SecondLayer MCP tool definitions available to this agent."""
+        return [
+            {
+                "name": "search_court_decisions",
+                "description": "Семантичний пошук рішень суду в ЄДРСР",
+                "parameters": {
+                    "query": {"type": "string"},
+                    "jurisdiction": {"type": "string", "enum": ["civil", "commercial"]},
+                    "limit": {"type": "integer", "default": 10},
+                },
+            },
+            {
+                "name": "get_legislation",
+                "description": "Отримати текст НПА за назвою або номером",
+                "parameters": {
+                    "query": {"type": "string"},
+                    "article": {"type": "string"},
+                },
+            },
+            {
+                "name": "search_supreme_court",
+                "description": "Пошук правових позицій Верховного Суду",
+                "parameters": {
+                    "query": {"type": "string"},
+                    "category": {"type": "string"},
+                },
+            },
+        ]

src/legal_intern/agents/reviewer.py

@@ -0,0 +1,104 @@
+"""Reviewer agent -- adversarial review of evidence and reasoning.
+
+Analogous to physics-intern's Reviewer (auto-triggered after each evidence).
+In secondlayer-core this maps to: CitationValidator + HallucinationGuard.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+REVIEWER_SYSTEM_PROMPT = """\
+Ти -- Правовий рецензент (Legal Reviewer). Твоя роль -- критично перевіряти \
+докази та міркування інших агентів.
+
+Для кожного нового доказу ти маєш:
+1. **Верифікація посилань**: чи існує вказана справа/стаття? Чи правильно цитовано?
+2. **Логічна послідовність**: чи слідує висновок з наведених норм та фактів?
+3. **Релевантність**: чи дійсно це стосується питання клієнта?
+4. **Актуальність**: чи не застарів правовий акт? Чи немає нових редакцій?
+5. **Протилежна практика**: чи є відомі контр-аргументи або протилежні позиції ВС?
+
+Вердикт для кожного доказу:
+- VERIFIED: підтверджено, можна покладатися
+- REFUTED: містить помилки, не можна використовувати
+- INCONCLUSIVE: потребує додаткової перевірки
+
+Поверни JSON:
+{
+  "reviews": [
+    {
+      "evidence_id": "EV-NNN",
+      "verdict": "verified" | "refuted" | "inconclusive",
+      "summary": "короткий висновок",
+      "details": "деталі перевірки",
+      "issues": ["список проблем"]
+    }
+  ]
+}
+"""
+
+
+class ReviewerAgent(BaseAgent):
+    role = "reviewer"
+    description = "Верифікація посилань, логіки, актуальності доказів"
+
+    async def run(
+        self,
+        state: ConsultationState,
+        evidence_ids: list[str] | None = None,
+        **kwargs: Any,
+    ) -> AgentResult:
+        from ..providers import call_llm
+        from ..state.research_state import ReviewResult, Verdict
+
+        context = self._build_state_context(state)
+
+        # Focus on specific evidence or review all unreviewed
+        target_evidence = []
+        if evidence_ids:
+            target_evidence = [ev for ev in state.evidence if ev.id in evidence_ids]
+        else:
+            reviewed_ids = set()
+            for h in state.hypotheses:
+                for r in h.reviews:
+                    pass  # reviews are per-hypothesis, not per-evidence
+            target_evidence = [ev for ev in state.evidence if not ev.refuted]
+
+        if not target_evidence:
+            return AgentResult(success=True, agent=self.role, summary="Немає доказів для рецензування")
+
+        evidence_text = "\n".join(
+            f"- {ev.id}: [{ev.type}] {ev.citation} -- {ev.summary}" for ev in target_evidence
+        )
+        user_msg = f"{context}\n\n# Докази для рецензування\n{evidence_text}"
+
+        response = await call_llm(
+            self.config,
+            system=REVIEWER_SYSTEM_PROMPT,
+            user=user_msg,
+            model_key="reviewer",
+            json_mode=True,
+        )
+
+        reviews = (response.parsed_json or {}).get("reviews", [])
+        refuted_count = 0
+        for r in reviews:
+            ev_id = r.get("evidence_id", "")
+            verdict = r.get("verdict", "inconclusive")
+            for ev in state.evidence:
+                if ev.id == ev_id and verdict == "refuted":
+                    ev.refuted = True
+                    refuted_count += 1
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Перевірено {len(reviews)} доказів, спростовано {refuted_count}",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/agents/surveyor.py

@@ -0,0 +1,62 @@
+"""Surveyor agent -- maps the legal landscape before the main loop.
+
+Analogous to physics-intern's Surveyor: identifies relevant areas of law,
+applicable legislation, court practice trends, and potential pitfalls.
+Runs once at the start.
+
+In secondlayer-core this corresponds to: IntentClassifier + QueryPlanner
+(but here it's a full LLM agent that produces a structured survey).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import AgentResult, BaseAgent
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+SURVEYOR_SYSTEM_PROMPT = """\
+Ти -- Правовий оглядач (Legal Surveyor). Твоя роль -- провести початковий аналіз \
+правового питання клієнта та скласти карту релевантного правового ландшафту.
+
+Ти отримуєш запит клієнта і маєш:
+1. Визначити юрисдикцію (цивільна, господарська, адміністративна, кримінальна)
+2. Ідентифікувати галузі права, що застосовуються
+3. Перелічити ключові нормативні акти та статті
+4. Визначити основні правові позиції ВС/КС, що стосуються питання
+5. Зазначити потенційні ризики та слабкі сторони
+6. Окреслити темпоральні аспекти (строки давності, процесуальні строки)
+
+Поверни структурований огляд українською мовою у форматі Markdown.
+НЕ давай відповідь на питання клієнта -- лише картуй ландшафт.
+"""
+
+
+class SurveyorAgent(BaseAgent):
+    role = "surveyor"
+    description = "Початковий огляд правового ландшафту"
+
+    async def run(self, state: ConsultationState, **kwargs: Any) -> AgentResult:
+        from ..providers import call_llm
+
+        prompt = f"{SURVEYOR_SYSTEM_PROMPT}\n\n# Запит клієнта\n{state.client_question}"
+
+        response = await call_llm(
+            self.config,
+            system=SURVEYOR_SYSTEM_PROMPT,
+            user=state.client_question,
+            model_key="surveyor",
+        )
+
+        state.survey_summary = response.content
+        if response.jurisdiction:
+            state.jurisdiction = response.jurisdiction
+
+        return AgentResult(
+            success=True,
+            agent=self.role,
+            summary=f"Огляд завершено: {len(response.content)} символів",
+            tokens_used=response.tokens_used,
+        )

src/legal_intern/core/__init__.py

@@ -0,0 +1,4 @@
+from .config import Config
+from .workspace import WorkspaceManager
+
+__all__ = ["Config", "WorkspaceManager"]

src/legal_intern/core/config.py

@@ -0,0 +1,59 @@
+"""Configuration for the LegalIntern system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class Config:
+    """System configuration, loaded from YAML."""
+
+    # LLM provider
+    default_provider: str = "anthropic"
+    default_model: str = "claude-sonnet-4-6"
+
+    # Per-agent model overrides
+    model_overrides: dict[str, str] = field(default_factory=dict)
+
+    # Loop control
+    max_iterations: int = 15
+    critic_every_n: int = 3  # run critic every N iterations
+    max_consecutive_failures: int = 3
+
+    # SecondLayer API
+    secondlayer_api_url: str = "https://legal.org.ua/api"
+    secondlayer_api_key: str = ""
+
+    # Workspace
+    workspace_dir: str = "workspaces"
+    logs_dir: str = ""
+
+    # API keys (loaded from env)
+    anthropic_api_key: str = ""
+    openai_api_key: str = ""
+
+    def model_for(self, agent_role: str) -> str:
+        return self.model_overrides.get(agent_role, self.default_model)
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> Config:
+        data = yaml.safe_load(path.read_text()) or {}
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+    @classmethod
+    def from_env(cls) -> Config:
+        import os
+
+        config = cls()
+        config.anthropic_api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        config.openai_api_key = os.environ.get("OPENAI_API_KEY", "")
+        config.secondlayer_api_key = os.environ.get("SECONDLAYER_API_KEY", "")
+        config.secondlayer_api_url = os.environ.get(
+            "SECONDLAYER_API_URL", config.secondlayer_api_url
+        )
+        return config

src/legal_intern/core/workspace.py

@@ -0,0 +1,40 @@
+"""Workspace management -- git-versioned workspace for each consultation."""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+
+class WorkspaceManager:
+    """Manages a git-versioned workspace directory for a consultation run."""
+
+    def __init__(self, config) -> None:
+        self.config = config
+        self.root: Path = Path(".")
+        self.logs_dir: Path = Path(".")
+
+    def init(self, problem_title: str) -> Path:
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        slug = problem_title[:40].replace(" ", "_").replace("/", "_")
+        self.root = Path(self.config.workspace_dir) / f"{ts}_{slug}"
+        self.root.mkdir(parents=True, exist_ok=True)
+
+        self.logs_dir = self.root / "logs"
+        self.logs_dir.mkdir(exist_ok=True)
+
+        (self.root / "evidence").mkdir(exist_ok=True)
+        (self.root / "derivations").mkdir(exist_ok=True)
+
+        subprocess.run(["git", "init"], cwd=self.root, capture_output=True)
+        return self.root
+
+    def snapshot(self, message: str) -> None:
+        """Create a git commit snapshot of the current workspace state."""
+        subprocess.run(["git", "add", "-A"], cwd=self.root, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", message, "--allow-empty"],
+            cwd=self.root,
+            capture_output=True,
+        )

src/legal_intern/engine.py

@@ -0,0 +1,216 @@
+"""LegalIntern main loop engine.
+
+Nine-agent pipeline for complex legal consultations:
+
+1. Surveyor   -- maps the legal landscape (runs once)
+2. Planner    -- produces/revises research strategy
+3. Orchestrator -- dispatches tasks to researcher or analyst
+4. Researcher -- finds case law, legislation, doctrine (via SecondLayer MCP)
+5. Analyst    -- computes deadlines, penalties, procedural checks
+6. Reviewer   -- adversarial verification of evidence (auto-triggered)
+7. Critic     -- periodic strategy audit (every N iterations)
+8. Adjudicator -- resolves inter-agent disagreements
+9. Formatter  -- produces final consultation document
+
+No agent carries conversation history. All state lives in ConsultationState.
+The workspace is git-versioned for full reproducibility.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+
+from .agents import (
+    AdjudicatorAgent,
+    AnalystAgent,
+    CriticAgent,
+    FormatterAgent,
+    OrchestratorAgent,
+    PlannerAgent,
+    ResearcherAgent,
+    ReviewerAgent,
+    SurveyorAgent,
+)
+from .core.config import Config
+from .core.workspace import WorkspaceManager
+from .state.loop_state import LoopState
+from .state.research_state import ConsultationState, CritiqueStatus
+
+console = Console()
+
+
+class LegalIntern:
+    """Main loop for the LegalIntern consultation system."""
+
+    def __init__(self, question: str, config: Config | None = None) -> None:
+        self.config = config or Config.from_env()
+        self.workspace = WorkspaceManager(self.config)
+        self.workspace.init(question[:60])
+
+        self.state = ConsultationState()
+        self.state.client_question = question.strip()
+        self.state.title = question[:80]
+
+        self._loop = LoopState()
+
+        # Initialize all 9 agents
+        self.surveyor = SurveyorAgent(self.config, self.workspace)
+        self.planner = PlannerAgent(self.config, self.workspace)
+        self.orchestrator = OrchestratorAgent(self.config, self.workspace)
+        self.researcher = ResearcherAgent(self.config, self.workspace)
+        self.analyst = AnalystAgent(self.config, self.workspace)
+        self.reviewer = ReviewerAgent(self.config, self.workspace)
+        self.critic = CriticAgent(self.config, self.workspace)
+        self.adjudicator = AdjudicatorAgent(self.config, self.workspace)
+        self.formatter = FormatterAgent(self.config, self.workspace)
+
+    async def run(self) -> str:
+        """Execute the full consultation pipeline. Returns the final answer."""
+        console.print(Panel(f"[bold]LegalIntern[/bold]\n{self.state.client_question[:200]}"))
+
+        # Phase 1: Survey
+        console.print("[dim]Phase 1: Surveyor[/dim]")
+        t0 = time.time()
+        result = await self.surveyor.run(self.state)
+        self._loop.record(0, "surveyor", result.summary, result.success, time.time() - t0)
+        self._loop.survey_done = True
+        self.workspace.snapshot("survey complete")
+        console.print(f"  [green]{result.summary}[/green]")
+
+        # Phase 2: Plan
+        console.print("[dim]Phase 2: Planner[/dim]")
+        t0 = time.time()
+        result = await self.planner.run(self.state)
+        self._loop.record(0, "planner", result.summary, result.success, time.time() - t0)
+        self._loop.plan_done = True
+        self.workspace.snapshot("plan complete")
+        console.print(f"  [green]{result.summary}[/green]")
+
+        # Phase 3: Main research loop
+        for iteration in range(1, self.config.max_iterations + 1):
+            self.state.iteration = iteration
+            console.print(f"\n[bold cyan]--- Iteration {iteration} ---[/bold cyan]")
+
+            # Orchestrator decides what to do next
+            t0 = time.time()
+            orch_result = await self.orchestrator.run(self.state)
+            self._loop.record(
+                iteration, "orchestrator", orch_result.summary, orch_result.success, time.time() - t0
+            )
+
+            if not orch_result.success:
+                if self._loop.consecutive_failures >= self.config.max_consecutive_failures:
+                    console.print("[red]Too many consecutive failures, stopping.[/red]")
+                    break
+                continue
+
+            # Parse orchestrator dispatch
+            dispatch = getattr(orch_result, "_dispatch", None) or {}
+            task_type = "research"  # default
+            task_desc = orch_result.summary
+
+            # Execute researcher or analyst
+            if task_type == "analysis":
+                console.print(f"  [yellow]Analyst:[/yellow] {task_desc[:80]}")
+                t0 = time.time()
+                agent_result = await self.analyst.run(self.state, task_description=task_desc)
+            else:
+                console.print(f"  [yellow]Researcher:[/yellow] {task_desc[:80]}")
+                t0 = time.time()
+                agent_result = await self.researcher.run(self.state, task_description=task_desc)
+
+            self._loop.record(
+                iteration,
+                agent_result.agent,
+                agent_result.summary,
+                agent_result.success,
+                time.time() - t0,
+            )
+            console.print(f"  [green]{agent_result.summary}[/green]")
+
+            # Auto-trigger reviewer
+            console.print("  [dim]Reviewer...[/dim]")
+            t0 = time.time()
+            review_result = await self.reviewer.run(self.state)
+            self._loop.record(
+                iteration, "reviewer", review_result.summary, review_result.success, time.time() - t0
+            )
+            console.print(f"  [green]{review_result.summary}[/green]")
+
+            # Periodic critic audit
+            if iteration % self.config.critic_every_n == 0:
+                console.print("  [dim]Senior Legal Advisor...[/dim]")
+                t0 = time.time()
+                critic_result = await self.critic.run(self.state)
+                self._loop.record(
+                    iteration, "critic", critic_result.summary, critic_result.success, time.time() - t0
+                )
+                self._loop.last_critic_iteration = iteration
+                console.print(f"  [magenta]{critic_result.summary}[/magenta]")
+
+                # Route critiques
+                await self._route_critiques()
+
+                # Check if critic says we can proceed
+                if "можна завершувати: True" in critic_result.summary:
+                    console.print("[green]Critic approved -- proceeding to answer.[/green]")
+                    break
+
+            # Check termination: no open questions and no active critiques
+            if not self.state.open_questions() and not self.state.active_critiques():
+                console.print("[green]All questions resolved -- proceeding to answer.[/green]")
+                break
+
+            self.workspace.snapshot(f"iteration {iteration}")
+
+        # Phase 4: Format final answer
+        console.print("\n[bold]Phase 4: Formatting consultation[/bold]")
+        t0 = time.time()
+        fmt_result = await self.formatter.run(self.state)
+        self._loop.record(
+            self.state.iteration, "formatter", fmt_result.summary, fmt_result.success, time.time() - t0
+        )
+        self.workspace.snapshot("answer formatted")
+
+        # Write answer file
+        answer_path = self.workspace.root / "CONSULTATION.md"
+        answer_path.write_text(self.state.answer, encoding="utf-8")
+        self.workspace.snapshot("final")
+
+        console.print(Panel(f"[bold green]Done![/bold green] {answer_path}"))
+        self._print_summary()
+
+        return self.state.answer
+
+    async def _route_critiques(self) -> None:
+        """Route active critiques to appropriate agents."""
+        for critique in self.state.active_critiques():
+            if critique.type == "strategy":
+                result = await self.planner.run(
+                    self.state, revision_critique=critique.details
+                )
+                critique.status = CritiqueStatus.RESOLVED
+            elif critique.type == "completeness":
+                # Generate new research questions
+                state_questions_before = len(self.state.questions)
+                result = await self.orchestrator.run(self.state)
+                if len(self.state.questions) > state_questions_before:
+                    critique.status = CritiqueStatus.RESOLVED
+            elif critique.target_hypothesis:
+                result = await self.adjudicator.run(
+                    self.state,
+                    hypothesis_id=critique.target_hypothesis,
+                    critique_id=critique.id,
+                )
+
+    def _print_summary(self) -> None:
+        console.print(f"\n[dim]Iterations: {self.state.iteration}[/dim]")
+        console.print(f"[dim]Hypotheses: {len(self.state.hypotheses)} "
+                       f"(established: {len(self.state.established_hypotheses())})[/dim]")
+        console.print(f"[dim]Evidence: {len(self.state.evidence)} "
+                       f"(refuted: {sum(1 for e in self.state.evidence if e.refuted)})[/dim]")
+        console.print(f"[dim]Total tokens: {self.state.total_tokens:,}[/dim]")

src/legal_intern/main.py

@@ -0,0 +1,56 @@
+"""CLI entrypoint for LegalIntern."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from .core.config import Config
+from .engine import LegalIntern
+
+
+def cli() -> None:
+    parser = argparse.ArgumentParser(description="LegalIntern -- multi-agent legal consultation")
+    parser.add_argument("question", nargs="?", help="Legal question (or path to .yaml problem file)")
+    parser.add_argument("--model", default=None, help="Override default LLM model")
+    parser.add_argument("--max-iterations", type=int, default=None)
+    parser.add_argument("--config", type=Path, default=None, help="Config YAML file")
+    parser.add_argument("--workspace-dir", type=str, default=None)
+    args = parser.parse_args()
+
+    if not args.question:
+        parser.print_help()
+        sys.exit(1)
+
+    # Load config
+    if args.config and args.config.exists():
+        config = Config.from_yaml(args.config)
+    else:
+        config = Config.from_env()
+
+    if args.model:
+        config.default_model = args.model
+    if args.max_iterations:
+        config.max_iterations = args.max_iterations
+    if args.workspace_dir:
+        config.workspace_dir = args.workspace_dir
+
+    # Load question from file or use directly
+    question = args.question
+    if Path(question).exists():
+        import yaml
+
+        data = yaml.safe_load(Path(question).read_text())
+        question = data.get("question", data.get("problem", question))
+
+    intern = LegalIntern(question, config)
+    answer = asyncio.run(intern.run())
+
+    print("\n" + "=" * 60)
+    print(answer)
+
+
+if __name__ == "__main__":
+    cli()

src/legal_intern/providers/__init__.py

@@ -0,0 +1,141 @@
+"""LLM provider abstraction layer."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..core.config import Config
+
+
+@dataclass
+class LLMResponse:
+    content: str = ""
+    tokens_used: int = 0
+    parsed_json: dict | None = None
+    jurisdiction: str = ""
+    tool_calls: list[dict] = field(default_factory=list)
+
+
+class ContextTooLongError(Exception):
+    pass
+
+
+async def call_llm(
+    config: Config,
+    system: str,
+    user: str,
+    model_key: str = "default",
+    json_mode: bool = False,
+    tools: list[dict] | None = None,
+) -> LLMResponse:
+    """Call the LLM provider configured for this agent role.
+
+    Each agent call starts from a fresh context -- no conversation history.
+    """
+    model = config.model_for(model_key)
+
+    if config.default_provider == "anthropic" or model.startswith("claude"):
+        return await _call_anthropic(config, system, user, model, json_mode, tools)
+    elif config.default_provider == "openai" or model.startswith("gpt"):
+        return await _call_openai(config, system, user, model, json_mode, tools)
+    else:
+        raise ValueError(f"Unknown provider: {config.default_provider}")
+
+
+async def _call_anthropic(
+    config: Config,
+    system: str,
+    user: str,
+    model: str,
+    json_mode: bool,
+    tools: list[dict] | None,
+) -> LLMResponse:
+    import anthropic
+
+    client = anthropic.AsyncAnthropic(api_key=config.anthropic_api_key)
+
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "max_tokens": 8192,
+        "system": system,
+        "messages": [{"role": "user", "content": user}],
+    }
+
+    if json_mode:
+        kwargs["messages"][0]["content"] += "\n\nВідповідай ТІЛЬКИ валідним JSON."
+
+    response = await client.messages.create(**kwargs)
+
+    content = ""
+    for block in response.content:
+        if block.type == "text":
+            content += block.text
+
+    parsed = None
+    if json_mode:
+        try:
+            # Try to extract JSON from the response
+            text = content.strip()
+            if text.startswith("```"):
+                text = text.split("```")[1]
+                if text.startswith("json"):
+                    text = text[4:]
+                text = text.strip()
+            parsed = json.loads(text)
+        except (json.JSONDecodeError, IndexError):
+            parsed = None
+
+    tokens = response.usage.input_tokens + response.usage.output_tokens
+
+    return LLMResponse(
+        content=content,
+        tokens_used=tokens,
+        parsed_json=parsed,
+    )
+
+
+async def _call_openai(
+    config: Config,
+    system: str,
+    user: str,
+    model: str,
+    json_mode: bool,
+    tools: list[dict] | None,
+) -> LLMResponse:
+    from openai import AsyncOpenAI
+
+    client = AsyncOpenAI(api_key=config.openai_api_key)
+
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        "max_tokens": 8192,
+    }
+
+    if json_mode:
+        kwargs["response_format"] = {"type": "json_object"}
+
+    response = await client.chat.completions.create(**kwargs)
+
+    content = response.choices[0].message.content or ""
+
+    parsed = None
+    if json_mode:
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError:
+            parsed = None
+
+    tokens = (response.usage.prompt_tokens + response.usage.completion_tokens) if response.usage else 0
+
+    return LLMResponse(
+        content=content,
+        tokens_used=tokens,
+        parsed_json=parsed,
+    )

src/legal_intern/rendering/__init__.py

@@ -0,0 +1,52 @@
+"""Render ConsultationState to Markdown files for workspace snapshots."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..state.research_state import ConsultationState
+
+
+def render_state_md(state: ConsultationState) -> str:
+    """Render the full consultation state as Markdown."""
+    parts = []
+    parts.append(f"# {state.title}")
+    parts.append(f"\n## Запит клієнта\n{state.client_question}")
+
+    if state.jurisdiction:
+        parts.append(f"**Юрисдикція**: {state.jurisdiction}")
+
+    if state.survey_summary:
+        parts.append(f"\n## Огляд\n{state.survey_summary}")
+
+    if state.strategy.approach:
+        parts.append(f"\n## Стратегія\n{state.strategy.approach}")
+
+    if state.hypotheses:
+        parts.append("\n## Правові позиції")
+        for h in state.hypotheses:
+            parts.append(f"- **{h.id}** ({h.status}): {h.statement}")
+
+    if state.evidence:
+        parts.append("\n## Докази")
+        for ev in state.evidence:
+            prefix = "~~" if ev.refuted else ""
+            suffix = "~~" if ev.refuted else ""
+            parts.append(f"- {prefix}**{ev.id}** [{ev.type}] {ev.citation}: {ev.summary}{suffix}")
+
+    if state.questions:
+        parts.append("\n## Дослідницькі питання")
+        for q in state.questions:
+            parts.append(f"- **{q.id}** ({q.status}): {q.question}")
+            if q.answer:
+                parts.append(f"  > {q.answer[:200]}")
+
+    if state.critiques:
+        parts.append("\n## Зауваження")
+        for c in state.critiques:
+            parts.append(f"- [{c.status}] **{c.id}** ({c.severity}): {c.summary}")
+
+    parts.append(f"\n---\nIteration: {state.iteration}")
+
+    return "\n".join(parts)

src/legal_intern/state/__init__.py

@@ -0,0 +1,10 @@
+from .research_state import ConsultationState, LegalHypothesis, LegalEvidence, ReviewResult
+from .loop_state import LoopState
+
+__all__ = [
+    "ConsultationState",
+    "LegalHypothesis",
+    "LegalEvidence",
+    "ReviewResult",
+    "LoopState",
+]

src/legal_intern/state/loop_state.py

@@ -0,0 +1,54 @@
+"""Loop state -- tracks iteration progress and dispatch history."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DispatchRecord:
+    iteration: int
+    agent: str
+    task_summary: str
+    success: bool
+    duration_sec: float = 0.0
+    tokens_used: int = 0
+    error: str = ""
+
+
+@dataclass
+class LoopState:
+    """Tracks the main loop's progress (separate from ConsultationState)."""
+
+    dispatch_history: list[DispatchRecord] = field(default_factory=list)
+    consecutive_failures: int = 0
+    survey_done: bool = False
+    plan_done: bool = False
+    last_critic_iteration: int = -1
+    formatter_attempts: int = 0
+
+    def record(
+        self,
+        iteration: int,
+        agent: str,
+        task_summary: str,
+        success: bool,
+        duration_sec: float = 0.0,
+        tokens_used: int = 0,
+        error: str = "",
+    ) -> None:
+        self.dispatch_history.append(
+            DispatchRecord(
+                iteration=iteration,
+                agent=agent,
+                task_summary=task_summary,
+                success=success,
+                duration_sec=duration_sec,
+                tokens_used=tokens_used,
+                error=error,
+            )
+        )
+        if success:
+            self.consecutive_failures = 0
+        else:
+            self.consecutive_failures += 1

src/legal_intern/state/research_state.py

@@ -0,0 +1,254 @@
+"""Consultation state -- structured representation of legal analysis.
+
+Mirrors physics-intern's ResearchState: agents mutate state via tools,
+Markdown is rendered from it for git snapshots. No agent carries
+conversation history; all context lives here.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class HypothesisStatus(StrEnum):
+    WORKING = "working"
+    ESTABLISHED = "established"
+    REFUTED = "refuted"
+    ABANDONED = "abandoned"
+
+
+class Verdict(StrEnum):
+    VERIFIED = "verified"
+    REFUTED = "refuted"
+    INCONCLUSIVE = "inconclusive"
+
+
+class Severity(StrEnum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class CritiqueStatus(StrEnum):
+    ACTIVE = "active"
+    RESOLVED = "resolved"
+    WITHDRAWN = "withdrawn"
+
+
+class RQStatus(StrEnum):
+    OPEN = "open"
+    RESOLVED = "resolved"
+    ABANDONED = "abandoned"
+
+
+@dataclass
+class LegalEvidence:
+    """Evidence produced by a researcher or analyst agent."""
+
+    id: str = ""
+    type: str = ""  # "case_law", "legislation", "doctrine", "computation"
+    source: str = ""  # "edrsr", "rada", "echr", "manual"
+    summary: str = ""
+    full_text: str = ""
+    citation: str = ""  # e.g. "Справа №757/12345/22" or "ст. 625 ЦК України"
+    relevance: str = ""
+    confidence: str = ""  # "high", "medium", "low"
+    iteration: int | None = None
+    refuted: bool = False
+
+    def short(self) -> str:
+        return f"[{self.id}] {self.citation}: {self.summary[:80]}"
+
+
+@dataclass
+class ReviewResult:
+    """Review produced by the legal reviewer agent."""
+
+    verdict: str = ""
+    summary: str = ""
+    details: str = ""
+    iteration: int | None = None
+
+
+@dataclass
+class LegalHypothesis:
+    """A legal position or argument being developed."""
+
+    id: str = ""
+    statement: str = ""
+    status: HypothesisStatus = HypothesisStatus.WORKING
+    supporting_evidence: list[str] = field(default_factory=list)  # evidence IDs
+    opposing_evidence: list[str] = field(default_factory=list)
+    reviews: list[ReviewResult] = field(default_factory=list)
+    iteration_created: int | None = None
+    iteration_resolved: int | None = None
+
+    def short(self) -> str:
+        return f"[{self.id}] ({self.status}) {self.statement[:80]}"
+
+
+@dataclass
+class Critique:
+    """Critique from the senior legal advisor."""
+
+    id: str = ""
+    type: str = ""  # "strategy", "reasoning", "completeness", "citation"
+    severity: Severity = Severity.MEDIUM
+    status: CritiqueStatus = CritiqueStatus.ACTIVE
+    summary: str = ""
+    details: str = ""
+    target_hypothesis: str = ""
+    iteration: int | None = None
+
+
+@dataclass
+class ResearchQuestion:
+    """An open question that needs investigation."""
+
+    id: str = ""
+    question: str = ""
+    status: RQStatus = RQStatus.OPEN
+    assigned_to: str = ""  # agent role
+    answer: str = ""
+    evidence_ids: list[str] = field(default_factory=list)
+    iteration_created: int | None = None
+
+
+@dataclass
+class LegalStrategy:
+    """The consultation strategy produced by the planner."""
+
+    approach: str = ""
+    legal_domains: list[str] = field(default_factory=list)
+    key_questions: list[str] = field(default_factory=list)
+    relevant_legislation: list[str] = field(default_factory=list)
+    risk_factors: list[str] = field(default_factory=list)
+    revision_history: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ConsultationState:
+    """Central state object for a legal consultation.
+
+    All agents read from and write to this object.
+    No agent carries its own conversation history.
+    """
+
+    # Problem
+    client_question: str = ""
+    jurisdiction: str = ""  # "civil", "commercial", "administrative", "criminal"
+    title: str = ""
+
+    # Strategy
+    strategy: LegalStrategy = field(default_factory=LegalStrategy)
+
+    # Hypotheses (legal positions)
+    hypotheses: list[LegalHypothesis] = field(default_factory=list)
+    _hyp_counter: int = 0
+
+    # Evidence
+    evidence: list[LegalEvidence] = field(default_factory=list)
+    _ev_counter: int = 0
+
+    # Open research questions
+    questions: list[ResearchQuestion] = field(default_factory=list)
+    _rq_counter: int = 0
+
+    # Critiques
+    critiques: list[Critique] = field(default_factory=list)
+    _crit_counter: int = 0
+
+    # Survey results (from the initial legal landscape survey)
+    survey_summary: str = ""
+
+    # Final answer
+    answer: str = ""
+    answer_template: str = ""
+
+    # Metadata
+    iteration: int = 0
+    total_tokens: int = 0
+    total_cost_usd: float = 0.0
+
+    # --- Mutation helpers ---
+
+    def add_hypothesis(self, statement: str, iteration: int | None = None) -> LegalHypothesis:
+        self._hyp_counter += 1
+        h = LegalHypothesis(
+            id=f"H-{self._hyp_counter:03d}",
+            statement=statement,
+            iteration_created=iteration,
+        )
+        self.hypotheses.append(h)
+        return h
+
+    def add_evidence(self, **kwargs: Any) -> LegalEvidence:
+        self._ev_counter += 1
+        ev = LegalEvidence(id=f"EV-{self._ev_counter:03d}", **kwargs)
+        self.evidence.append(ev)
+        return ev
+
+    def add_question(self, question: str, iteration: int | None = None) -> ResearchQuestion:
+        self._rq_counter += 1
+        rq = ResearchQuestion(
+            id=f"RQ-{self._rq_counter:03d}",
+            question=question,
+            iteration_created=iteration,
+        )
+        self.questions.append(rq)
+        return rq
+
+    def add_critique(self, **kwargs: Any) -> Critique:
+        self._crit_counter += 1
+        c = Critique(id=f"CR-{self._crit_counter:03d}", **kwargs)
+        self.critiques.append(c)
+        return c
+
+    def open_questions(self) -> list[ResearchQuestion]:
+        return [q for q in self.questions if q.status == RQStatus.OPEN]
+
+    def active_critiques(self) -> list[Critique]:
+        return [c for c in self.critiques if c.status == CritiqueStatus.ACTIVE]
+
+    def working_hypotheses(self) -> list[LegalHypothesis]:
+        return [h for h in self.hypotheses if h.status == HypothesisStatus.WORKING]
+
+    def established_hypotheses(self) -> list[LegalHypothesis]:
+        return [h for h in self.hypotheses if h.status == HypothesisStatus.ESTABLISHED]
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def save(self, path: Path) -> None:
+        path.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2))
+
+    @classmethod
+    def load(cls, path: Path) -> ConsultationState:
+        data = json.loads(path.read_text())
+        state = cls()
+        state.client_question = data.get("client_question", "")
+        state.jurisdiction = data.get("jurisdiction", "")
+        state.title = data.get("title", "")
+        state.survey_summary = data.get("survey_summary", "")
+        state.answer = data.get("answer", "")
+        state.iteration = data.get("iteration", 0)
+        state.total_tokens = data.get("total_tokens", 0)
+        state.total_cost_usd = data.get("total_cost_usd", 0.0)
+        # Hydrate nested objects
+        if "strategy" in data:
+            state.strategy = LegalStrategy(**data["strategy"])
+        for h in data.get("hypotheses", []):
+            hyp = LegalHypothesis(**{k: v for k, v in h.items() if k != "reviews"})
+            hyp.reviews = [ReviewResult(**r) for r in h.get("reviews", [])]
+            state.hypotheses.append(hyp)
+        for ev in data.get("evidence", []):
+            state.evidence.append(LegalEvidence(**ev))
+        for q in data.get("questions", []):
+            state.questions.append(ResearchQuestion(**q))
+        for c in data.get("critiques", []):
+            state.critiques.append(Critique(**c))
+        return state

src/legal_intern/tools/secondlayer_bridge.py

@@ -0,0 +1,69 @@
+"""Bridge to SecondLayer MCP backend tools.
+
+Allows agents to call SecondLayer API tools (search_court_decisions,
+get_legislation, etc.) via the HTTP API at legal.org.ua/api/tools/:toolName.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class SecondLayerBridge:
+    """HTTP client for SecondLayer MCP tool execution."""
+
+    def __init__(self, api_url: str, api_key: str) -> None:
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.api_url,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=60.0,
+            )
+        return self._client
+
+    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Execute a SecondLayer MCP tool via HTTP API."""
+        client = await self._get_client()
+        response = await client.post(
+            f"/tools/{tool_name}",
+            json=params,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def search_court_decisions(
+        self,
+        query: str,
+        jurisdiction: str = "civil",
+        limit: int = 10,
+    ) -> list[dict]:
+        result = await self.call_tool(
+            "search_court_decisions",
+            {"query": query, "jurisdiction": jurisdiction, "limit": limit},
+        )
+        return result.get("decisions", result.get("results", []))
+
+    async def get_legislation(self, query: str, article: str = "") -> dict:
+        params: dict[str, Any] = {"query": query}
+        if article:
+            params["article"] = article
+        return await self.call_tool("get_legislation", params)
+
+    async def search_supreme_court(self, query: str, category: str = "") -> list[dict]:
+        params: dict[str, Any] = {"query": query}
+        if category:
+            params["category"] = category
+        result = await self.call_tool("search_supreme_court_positions", params)
+        return result.get("positions", result.get("results", []))
+
+    async def close(self) -> None:
+        if self._client:
+            await self._client.aclose()
+            self._client = None