Content
# ZP-2025 — platforma agentov a nástrojov
Tento repozitár obsahuje agenta na generovanie kódu, revíziu a spúšťanie v Dockeri, register nástrojov, MCP server, Streamlit UI a experimentálne pipeline. Hlavná logika sa nachádza v `src/`, UI v `UI/`, experimenty v `experiments/`.
## Rýchly štart
1. Nainštalujte závislosti:
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
2. Spustite Docker (potrebný na vykonávanie kódu).
3. Spustite UI:
```
streamlit run UI/StreamLitLangChain.py
```
## Architektonický diagram
```mermaid
sequenceDiagram
actor User
participant UI as Streamlit UI
participant Client as MCPClient
participant Server as MCPToolServer
participant Orchestrator as AgentOrchestrator
participant Dev as DeveloperAgent
participant Conv as ConversationAgent
participant Review as ReviewerAgent
participant Exec as ExecutorAgent
participant Registry as ToolRegistry
participant Tool as GeneratedScriptTool
participant Docker as DockerExecutor
participant LLM as UnifiedLLMClient
User->>UI: Send prompt
alt Conversational prompt
UI->>Client: chat(message, reset?)
Client->>Server: chat(message, reset?)
Server->>Orchestrator: chat(message, reset?)
Orchestrator->>Conv: Build reply from history + user message
Conv->>LLM: chat(messages)
LLM-->>Conv: assistant text
Conv-->>Orchestrator: response
Orchestrator-->>Server: response
Server-->>Client: response
Client-->>UI: stream/render text
else Code / tool / external-fact prompt
UI->>Client: run_pipeline(prompt, mode="chat")
Client->>Server: run_agent_pipeline(prompt, mode="chat")
Server->>Orchestrator: run_pipeline(prompt, mode="chat")
Orchestrator->>Registry: load_tool_instances()
Registry-->>Orchestrator: enabled saved tools
Orchestrator->>Dev: run(prompt, tools_info)
Dev->>LLM: chat(system+user messages)
LLM-->>Dev: ReAct output or Python code
Dev-->>Orchestrator: raw output
alt ReAct selected a saved tool
Orchestrator->>Tool: run(params)
Tool->>Docker: execute(tool script with TOOL_INPUT)
Docker-->>Tool: tool output
Tool-->>Orchestrator: observation
Orchestrator->>Conv: final answer from observation
Conv->>LLM: chat(messages)
LLM-->>Conv: final answer
Conv-->>Orchestrator: response
else No tool selected, generate code
Orchestrator->>Review: run(code)
Review->>LLM: chat(review prompt)
LLM-->>Review: fixed code
Review-->>Orchestrator: reviewed code
Orchestrator->>Exec: validate(code)
Exec->>LLM: chat(validation prompt)
LLM-->>Exec: final code
Exec-->>Orchestrator: validated code
Orchestrator->>Docker: execute(validated code)
Docker-->>Orchestrator: runtime output
end
opt UI can save reusable generated code
UI->>Client: save_tool(code, task_description)
Client->>Server: save_tool(code, task_description)
Server->>Registry: save_tool(code, task_description)
Registry-->>Server: saved file path + enabled flag
Server-->>Client: result
Client-->>UI: success / error
end
end
```
Toto je presnejšia mapa skutočného behu: UI nie vždy ide cez pipeline — pri bežnom dialógu môže streamovať odpoveď priamo cez `chat()`. Celý pipeline sa spúšťa iba pre technické, kódové alebo nástrojové požiadavky.
## Stavový diagram (UML State Machine)
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> ClassifyIntent: user prompt
ClassifyIntent --> ConversationResponse: no code/tool/external intent
ClassifyIntent --> DeveloperStep: pipeline required
DeveloperStep --> ToolExecution: ReAct tool selected
DeveloperStep --> CodePipeline: no tool selected
ConversationResponse --> Finalize
ToolExecution --> Finalize
CodePipeline --> Finalize
Finalize --> Idle: ready for next prompt
```
## Hlavné komponenty
| Komponent | Cesta | Úloha |
| --- | --- | --- |
| MCP stdio server | `src/mcp/mcp_stdio_server.py` | MCP server na stdio s nástrojmi a promptmi |
| MCP server (in-process) | `src/mcp/server.py` | Server pre volania z UI/CLI cez Python API |
| MCP klient | `src/mcp/client.py` | Klient na správu nástrojov a spúšťanie pipeline |
| Orchestrátor agentov | `src/langchain_module/lc_agent.py` | Výber nástrojov, ReAct, generovanie kódu, vykonávanie |
| Agenti | `src/langchain_module/agents/*.py` | Developer, Reviewer, Executor, Conversation |
| Register nástrojov | `src/tools/registry.py` | Ukladanie, povolenie a indexovanie nástrojov |
| Generované nástroje | `src/generated_tools/` | Súbory vygenerovaného kódu podľa kategórií |
| Docker exekútor | `src/executors/docker_executor.py` | Bezpečné vykonávanie kódu |
| UI | `UI/StreamLitLangChain.py` | Streamlit rozhranie |
## Ako funguje Auto Agent Chat
Režim „Auto Agent Chat" v UI používa `MCPClient.run_pipeline(..., mode="chat")`. Správanie určuje `AgentOrchestrator`:
1. Ak požiadavka vyzerá ako bežný dialóg, UI môže ísť priamo do `client.stream_chat()` alebo `client.chat()` bez pipeline.
2. Ak je požiadavka technická, obsahuje kódové zámery, externé fakty alebo sa podobá existujúcemu nástroju, spustí sa `run_pipeline(..., mode="chat")`.
3. `DeveloperAgent` buď vráti ReAct `Action`, alebo vygeneruje blok Python kódu.
4. Ak sa nájde `Action`, vybraný uložený nástroj sa vykoná cez `GeneratedScriptTool` a `DockerExecutor`.
5. Ak nebol vybraný žiadny nástroj, kód prejde cez `ReviewerAgent` → `ExecutorAgent.validate()` → `DockerExecutor.execute()`.
6. Ak je vykonávanie úspešné a kód vyzerá ako znovupoužiteľný `def` alebo `class`, UI zobrazí formulár na uloženie nového nástroja.
## Formát ReAct a parsovanie
Developer agent musí odpovedať v jednom z formátov:
```
Thought: ...
Action: tool_name
Action Input: {"key": "value"}
```
alebo kódom v blokoch ` ```python ``` `. Parsovanie prebieha v `src/utils/react_parsing.py`.
## Nástroje a register
### Kde sú nástroje uložené
Nástroje sú uložené v `src/generated_tools/` s podkategóriami: `Date/`, `Math/`, `Logic/`, `General/` atď. Stav povolenia je uložený v `src/generated_tools/.enabled_tools.json`.
### Formát nástroja
Súbor nástroja je Python súbor s docstringom na začiatku. Register číta docstring a dostupné funkcie, aby zostavil metadáta.
### Vstupné parametre nástroja
`GeneratedScriptTool` odovzdáva vstup do premennej `TOOL_INPUT`. Vstup môže byť:
- reťazec (jednoduchý hovor),
- slovník (ReAct s parametrami).
### Ako povoliť alebo zakázať nástroj
1. Cez UI (sekcia „Saved tools").
2. Cez MCP klienta:
```
from src.mcp.client import create_client
client = create_client(provider="openrouter", model="google/gemma-4-26b-a4b-it:free")
client.enable_tool("Date/tool_current_time_and_data")
```
## MCP servery
### MCP stdio server
`src/mcp/mcp_stdio_server.py` je postavený na FastMCP a exponuje:
| Nástroj | Účel |
| --- | --- |
| `generate_code` | Generovanie kódu cez Developer agenta |
| `review_code` | Revízia kódu |
| `execute_code` | Validácia a spustenie v Dockeri |
| `run_full_pipeline` | Celý reťazec generate → review → execute |
| `chat_with_agent` | Dialóg s kontextom |
| `list_tools` | Zoznam nástrojov |
| `toggle_tool` | Povoliť/zakázať nástroj |
| `save_new_tool` | Uložiť nový nástroj |
MCP prompty:
- `solve_task`: krokový scenár
- `full_pipeline`: jednorazové spustenie celého pipeline
### MCP in-process server
`src/mcp/server.py` — server na prácu z Python kódu (UI/CLI). Má rovnaké možnosti, ale bez stdio transportu.
### Konfigurácia MCP
Súbor `mcp_config.json` opisuje, ako spustiť MCP server:
```
{
"mcpServers": {
"zp-agents": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/src/mcp/mcp_stdio_server.py"],
"env": {
"LLM_PROVIDER": "openrouter",
"LLM_MODEL": "google/gemma-3-27b-it:free"
}
}
}
}
```
## Poskytovatelia a modely
Podporovaní: `azure`, `openai`, `groq`, `openrouter`, `gemini`, `ollama`, `huggingface`.
| Poskytovateľ | Kľúčové premenné prostredia |
| --- | --- |
| Azure | `AZURE_OPENAI_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT`, `AZURE_OPENAI_API_VERSION` |
| OpenAI | `OPENAI_API_KEY` |
| Groq | `GROQ_API_KEY`, `GROQ_BASE_URL` (voliteľné) |
| OpenRouter | `GEMINI_GEMMA_4` alebo `OPENROUTER_API_KEY`, `OPENROUTER_BASE_URL`, `OPENROUTER_REFERER`, `OPENROUTER_TITLE` |
| Gemini | `GEMINI_API_KEY2` alebo `GEMINI_API_KEY`, `GEMINI_BASE_URL` |
| Ollama | `OLLAMA_BASE_URL` |
| HuggingFace | `HUGGINGFACE_TOKEN` (pre gated modely) |
OpenRouter má fallback: pri chybe 429 môže prepnúť na Groq alebo Ollama.
## HuggingFace Direct
Režim „HuggingFace Direct" v UI obchádza agentský pipeline a volá lokálne modely HuggingFace priamo:
- `bigcode/tiny_starcoder_py` (~200 MB)
- `microsoft/CodeGPT-small-py` (~500 MB)
- `Salesforce/codegen-350M-mono` (~700 MB)
Tento režim vracia iba vygenerovaný kód bez vykonávania a bez uloženia do registra.
## UI (Streamlit)
UI sa nachádza v `UI/StreamLitLangChain.py`.
Funkcie UI:
- chat s agentom,
- spustenie pipeline,
- prepínanie poskytovateľa a modelu,
- prezeranie a povolenie nástrojov,
- návrh na uloženie nového nástroja po úspešnom vykonaní.
Režimy interakcie:
| Režim | Čo sa deje |
| --- | --- |
| Auto Agent Chat | Rozhovory sa streamujú, technické požiadavky idú do pipeline |
| HuggingFace Direct | Okamžité generovanie kódu cez HF |
## Docker vykonávanie
Vykonávanie kódu prebieha cez `DockerExecutor`:
- sieť je vypnutá,
- prístup k súborom iba na čítanie,
- limit pamäte 256 MB,
- CPU 1 jadro,
- predvolený timeout 30 sekúnd.
Docker obraz sa zostavuje z `Dockerfile` ako `python-executor:latest`.
## Spustenie z CLI
### LangChain + Ollama
```
python src/runners/lc_main.py
```
### AutoGPT (experiment)
```
PYTHONPATH=experiments python src/runners/autogpt_main.py
```
### CrewAI (experiment)
```
PYTHONPATH=experiments python src/runners/cw_main.py
```
### Príklad priameho volania MCP klienta
```
python run_task.py
```
## Experimenty
`experiments/` obsahuje prototypy pipeline:
- `autoGpt_module` — plánovač, kóder, kritik + TaskManager
- `crewai_module` — Agent + Task + Crew
Tieto moduly nie sú predvolene napojené na hlavné UI.
## Štruktúra adresárov
```
UI/ Streamlit UI
src/ Hlavná logika
src/mcp/ MCP server a klient
src/langchain_module/ Agenti, orchestrátor, pipeline
src/tools/ Register a obaly nástrojov
src/generated_tools/ Uložené nástroje
src/executors/ Docker vykonávanie
experiments/ Prototypy
test/ Testy
test/experiments_archive/ Archív experimentov — výsledky testovania modelov
```
## Testy
```
make test
make test-unit
make test-integration
```
Integračné testy vyžadujú skutočné API kľúče a prístup k sieti.
## Bežné problémy
| Príznak | Príčina | Riešenie |
| --- | --- | --- |
| `Execution unavailable: Docker executor is not initialized` | Docker nie je spustený | Spustite Docker |
| `Missing ... API key` | Chýba kľúč v `.env` | Pridajte príslušnú premennú |
| 429 od OpenRouter | Limit alebo kvóta | Skontrolujte kľúč alebo počkajte, existuje fallback |
| HF model sa nenačítava | Chýba token alebo miesto na disku | Pridajte `HUGGINGFACE_TOKEN` a skontrolujte voľné miesto |
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available