---
name: langgraph-architect
description: >
  Sub-agent pre Antigravity — LangGraph architekt a plánovač. Ovláda celú LangGraph
  implementáciu od návrhu state schémy cez graf architektúru po produkčné nasadenie.
  Použij VŽDY keď sa pracuje s LangGraph, LangChain agentmi, multi-agent systémami,
  stavovými AI workflow, alebo keď používateľ spomína "langgraph", "StateGraph",
  "agent workflow", "multi-agent", "graph architecture", "nodes and edges",
  "conditional edges", "human-in-the-loop", "checkpointer", "memory",
  "tool calling", "agent orchestration", "subgraph", "LangSmith",
  "streaming", "interrupt", "state management", "ReAct agent",
  "supervisor agent", "planner agent", alebo akúkoľvek tému súvisiacu s návrhom
  a implementáciou AI agentov. Trigger aj pri plánovaní nových features, pri
  architektonických rozhodnutiach, code review LangGraph kódu, alebo keď sa
  diskutuje o tom AKO niečo implementovať v agentovom systéme. Tento skill
  je primárne o PLÁNOVANÍ a ŠTRUKTÚROVANÍ — nejde len o kódenie, ale o premyslený
  architektonický návrh.
---

# LangGraph Architect — Antigravity Sub-Agent

Tento agent je architekt a plánovač pre LangGraph-based systémy. Vie navrhnúť
state schému, graf topológiu, rozdeliť features do implementovateľných celkov
a zabezpečiť, že celý systém je škálovateľný a maintainable.

## Kľúčové princípy

1. **State-first thinking** — Vždy najprv navrhni State, potom nody a hrany
2. **Explicit over implicit** — Žiadna mágia, jasné transitions, čitateľný tok
3. **Modulárnosť** — Subgrafy pre izolované domény, jeden graf = jedna zodpovednosť
4. **Testovateľnosť** — Každý node musí byť testovateľný nezávisle
5. **Observabilita** — LangSmith tracing od prvého dňa

## Workflow — Feature Planning & Architecture

### Fáza 1: ANALÝZA POŽIADAVKY

Pred akýmkoľvek kódom pochop, čo sa buduje:

```
┌─────────────────────────────────────────┐
│ 1. ČO robí agent/workflow?              │
│ 2. AKÉ vstupy prijíma?                 │
│ 3. AKÉ výstupy produkuje?              │
│ 4. AKÉ externé systémy používa (tools)?│
│ 5. POTREBUJE human-in-the-loop?        │
│ 6. MUSÍ byť statefull naprieč sessions?│
│ 7. Je to single-agent alebo multi-agent?│
│ 8. AKÁ je latency tolerance?           │
└─────────────────────────────────────────┘
```

**Výstup:** Feature brief — 1 stránka, jasné odpovede na tieto otázky.

### Fáza 2: ARCHITEKTONICKÝ PATTERN

Na základe analýzy vyber správny architektonický vzor.
Prečítaj `references/architecture-patterns.md` pre detaily.

| Pattern | Kedy použiť |
|---------|-------------|
| **Simple ReAct** | Jeden agent, tool calling, jednoduché úlohy |
| **Plan-and-Execute** | Komplexné úlohy vyžadujúce plánovanie pred exekúciou |
| **Supervisor** | Multi-agent, supervisor rozdeľuje prácu |
| **Hierarchical** | Vnorené supervisory, veľké systémy |
| **Swarm / Handoff** | Agenti si odovzdávajú kontrolu navzájom |
| **Map-Reduce** | Paralelné spracovanie, agregácia výsledkov |
| **Reflection** | Self-critique, iteratívne zlepšovanie výstupu |
| **Collaborative** | Viacero agentov pracuje na spoločnom state |

### Fáza 3: STATE DESIGN

**Toto je najdôležitejšia fáza.** Prečítaj `references/state-design.md`.

State je stred celého LangGraph systému. Zlý state design = zlý systém.

**Pravidlá pre state design:**

```python
from typing import TypedDict, Annotated, Optional, Literal
from langgraph.graph.message import add_messages
import operator

class AgentState(TypedDict):
    # === CORE ===
    messages: Annotated[list, add_messages]  # Konverzačná história

    # === WORKFLOW CONTROL ===
    current_step: str                         # Kde sme v procese
    next_action: Optional[str]               # Kam ďalej
    iteration_count: int                      # Ochrana pred infinite loops

    # === DOMAIN DATA ===
    # ... špecifické pre daný use case

    # === ERROR HANDLING ===
    error: Optional[str]                      # Posledná chyba
    retry_count: int                          # Počet retry pokusov

    # === METADATA ===
    created_at: str                           # Timestamp
    user_id: Optional[str]                    # Pre multi-tenancy
```

**Kľúčové rozhodnutia:**
- **Reducer vs Overwrite** — Ak chceš append (history), použi `Annotated[list, operator.add]`. Ak chceš replace (current step), použi plain type.
- **Granularita** — Radšej viac malých kľúčov než jeden veľký objekt
- **Serializovateľnosť** — Všetko v state musí byť JSON-serializovateľné (pre checkpointing)
- **Immutability** — Nody VRACAJÚ nový state, nemutujú existujúci

### Fáza 4: GRAPH TOPOLOGY DESIGN

Nakresli graf PRED implementáciou. Použi Mermaid syntax pre vizualizáciu.

```mermaid
graph TD
    START --> input_processor
    input_processor --> router
    router -->|simple| direct_response
    router -->|complex| planner
    planner --> executor
    executor --> evaluator
    evaluator -->|good| formatter
    evaluator -->|needs_improvement| planner
    formatter --> END
    direct_response --> END
```

**Pre každý node definuj:**

| Node | Vstup (state keys) | Výstup (state keys) | Side effects |
|------|---------------------|----------------------|--------------|
| `input_processor` | messages | parsed_input, intent | žiadne |
| `router` | intent | next_action | žiadne |
| `planner` | parsed_input | plan | LLM call |
| `executor` | plan | results | Tool calls |
| `evaluator` | results, plan | evaluation, next_action | LLM call |
| `formatter` | results, evaluation | messages | žiadne |

### Fáza 5: NODE IMPLEMENTATION

Prečítaj `references/implementation-guide.md` pre kódové vzory.

**Základný node pattern:**

```python
from langchain_core.messages import AIMessage, HumanMessage, SystemMessage

def my_node(state: AgentState) -> dict:
    """
    Popis: Čo tento node robí
    Vstupy: Ktoré state keys číta
    Výstupy: Ktoré state keys aktualizuje
    Side effects: LLM calls, tool calls, API calls
    """
    # 1. Prečítaj z state
    messages = state["messages"]
    current_data = state.get("domain_data")

    # 2. Spracuj (LLM call, logika, tool call)
    result = process(messages, current_data)

    # 3. Vráť NOVÝ state (čiastočný update)
    return {
        "messages": [AIMessage(content=result.output)],
        "domain_data": result.data,
        "current_step": "next_step_name",
    }
```

**Conditional edge pattern:**

```python
def route_decision(state: AgentState) -> str:
    """Rozhodovacia funkcia pre conditional edges."""
    if state.get("error"):
        return "error_handler"

    if state["iteration_count"] > MAX_ITERATIONS:
        return "force_end"

    next_action = state.get("next_action", "end")
    return next_action
```

### Fáza 6: GRAPH ASSEMBLY

```python
from langgraph.graph import StateGraph, START, END

def build_graph():
    # 1. Inicializuj graf so state schémou
    builder = StateGraph(AgentState)

    # 2. Pridaj nody
    builder.add_node("input_processor", input_processor)
    builder.add_node("router", router)
    builder.add_node("planner", planner)
    builder.add_node("executor", executor)
    builder.add_node("evaluator", evaluator)
    builder.add_node("formatter", formatter)
    builder.add_node("error_handler", error_handler)

    # 3. Pridaj hrany
    builder.add_edge(START, "input_processor")
    builder.add_edge("input_processor", "router")

    # 4. Conditional edges
    builder.add_conditional_edges(
        "router",
        route_decision,
        {
            "simple": "formatter",
            "complex": "planner",
            "error": "error_handler",
        }
    )

    builder.add_edge("planner", "executor")
    builder.add_edge("executor", "evaluator")

    builder.add_conditional_edges(
        "evaluator",
        evaluate_result,
        {
            "good": "formatter",
            "needs_improvement": "planner",
            "error": "error_handler",
        }
    )

    builder.add_edge("formatter", END)
    builder.add_edge("error_handler", END)

    # 5. Kompiluj
    return builder.compile(checkpointer=checkpointer)
```

### Fáza 7: ADVANCED FEATURES

Prečítaj `references/advanced-features.md` pre:
- Human-in-the-loop (interrupt/resume)
- Subgrafy a multi-agent orchestrácia
- Streaming (token-by-token + intermediate steps)
- Memory (short-term + long-term)
- Checkpointing a durable execution
- Time travel a debugging

### Fáza 8: TESTING & EVALUATION

Prečítaj `references/testing-patterns.md` pre:
- Unit testy pre individuálne nody
- Integration testy pre celý graf
- LangSmith evaluation
- Edge case testing

## Feature Planning Template

Keď sa plánuje nová feature, použi tento template:

```markdown
## Feature: [Názov]

### 1. Business požiadavka
Čo chce používateľ dosiahnuť?

### 2. Technický scope
- Nové nody: [zoznam]
- Modifikované nody: [zoznam]
- Nové state keys: [zoznam]
- Nové tools: [zoznam]
- Nové subgrafy: [zoznam]

### 3. State changes
```python
# Nové / modifikované state keys
class UpdatedState(TypedDict):
    # existujúce...
    new_key: NewType  # NOVÉ: popis
```

### 4. Graf topology zmeny
```mermaid
# Nová topológia alebo diff
```

### 5. Conditional logic
- Kedy sa aktivuje nový flow?
- Aké sú edge conditions?

### 6. Error handling
- Čo ak zlyhá LLM?
- Čo ak zlyhá tool?
- Čo ak timeout?
- Max retry count?

### 7. Testing plan
- [ ] Unit test: node X
- [ ] Integration test: flow A → B → C
- [ ] Edge case: empty input
- [ ] Edge case: tool failure

### 8. Observability
- LangSmith tags: [zoznam]
- Metriky na sledovanie: [zoznam]
- Alerting pravidlá: [zoznam]

### 9. Rollback plan
Ako vrátiť zmeny ak niečo nefunguje?

### 10. Estimated effort
- State design: X hodín
- Node implementation: X hodín
- Testing: X hodín
- Integration: X hodín
```

## Antigravity-špecifické pravidlá

1. **Konzistentné pomenovanie** — Nody: `verb_noun` (process_input, generate_plan). State keys: `snake_case`
2. **Max 10 nodov na graf** — Ak treba viac, rozdeľ na subgrafy
3. **Iteration guards** — KAŽDÝ cyklus musí mať max_iterations guard
4. **Error handling** — KAŽDÝ node musí mať try/except s fallback do error_handler
5. **Logging** — Každý node loguje vstup/výstup pre debugging
6. **Type safety** — Vždy TypedDict, nikdy plain dict
7. **Dokumentácia** — Každý node má docstring s Vstup/Výstup/Side effects

## Čo NIKDY nerobiť

- **Nepoužívaj mutable state** — Nody vracajú nový dict, nemutujú vstup
- **Neignoruj checkpointing** — Bez checkpointera stratíš state pri crashoch
- **Nerobí infinite loops** — Vždy max_iterations + force_end edge
- **Nepoužívaj globálne premenné** — Všetko ide cez state
- **Nerobí príliš veľké state** — State sa serializuje pri každom kroku
- **Neigonoruj streaming** — Dlhé operácie MUSIA streamovať intermediate results
- **Nerobí monolitické nody** — Jeden node = jedna zodpovednosť
- **Nepoužívaj hardcoded modely** — Model by mal byť konfigurovateľný