Metadata-Version: 2.4
Name: hydra-agents
Version: 1.0.1
Summary: Dynamic multi-agent orchestration framework powered by litellm
License: MIT
Project-URL: Homepage, https://github.com/Metalheadache/Hydra
Project-URL: Repository, https://github.com/Metalheadache/Hydra
Project-URL: Issues, https://github.com/Metalheadache/Hydra/issues
Keywords: ai,agents,orchestration,llm,litellm,multi-agent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: litellm!=1.82.7,!=1.82.8,>=1.40.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: jsonschema>=4.22.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: python-pptx>=1.0.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: Jinja2>=3.1.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: python-multipart>=0.0.14
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"

# Hydra 🐍

**Dynamic Multi-Agent Orchestration Framework**

Hydra decomposes complex tasks into sub-tasks, dynamically generates specialized AI agents at runtime, executes them via a hybrid DAG (parallel + sequential), and synthesizes results — with real-time streaming of every step.

Unlike CrewAI or AutoGen where agents are pre-defined, Hydra's Brain **generates agent specifications on the fly** — roles, tools, constraints, and personas are tailored to each specific task.

---

## Features

- 🧠 **Brain (Planner)** — Automatic task decomposition + agent generation via structured LLM call
- 🤖 **Dynamic Agents** — Each agent gets a tailored role, goal, backstory, and tool set — generated at runtime, not pre-built
- ⚡ **Hybrid DAG Execution** — Independent tasks run in parallel; dependent tasks wait automatically
- 📡 **Real-time Streaming** — Token-by-token LLM output, tool call visibility, and full pipeline progress via `.stream()`
- 🖥️ **Web UI** — Glassmorphism chat interface with live orchestration view, agent cards, quality scores, and result export
- 🔄 **Retry + Quality Gate** — Failed agents retry with exponential backoff; LLM quality scoring (1-10) with automatic re-dispatch
- 🔀 **Provider-Agnostic** — Works with Anthropic, OpenAI, Ollama, Azure, Gemini, DeepSeek, and [100+ providers via litellm](https://docs.litellm.ai/docs/providers)
- 📎 **File Upload** — Attach PDFs, DOCX, XLSX, PPTX, code files — text auto-extracted for agent context (30+ formats)
- 🔧 **30+ Built-in Tools** — Document generation, file reading (.doc/.docx/.xlsx/.csv/.pptx/.pdf/code), file management, research, data analysis, code execution, memory, translation, templates, PDF operations, validation
- 📎 **Smart File Handling** — Uploaded files auto-extracted for context; agents can re-read originals with reader tools for full structured access (tables, headings, metadata)
- 🛡️ **Human-in-the-Loop** — Tools with `requires_confirmation` pause for user approval with risk badges, keyboard shortcuts, auto-timeout, and confirmation queue
- 📋 **Audit Logging** — Every LLM call, tool execution, and state mutation logged as structured JSON Lines
- 🌐 **FastAPI Backend** — REST + WebSocket API with task history, file upload, optional auth token

---

## Quick Start

### Option 1: pip install (recommended)

```bash
pip install hydra-agents
hydra-agents serve
# → Auto-opens http://localhost:8000
```

Configure your LLM provider in the Settings panel (gear icon), then type a task and watch the agents work.

### Option 2: From source (for development)

```bash
git clone https://github.com/Metalheadache/Hydra.git
cd Hydra
pip install -e ".[dev]"

# Build frontend
cd frontend && npm install && npx vite build && cd ..

# Start server (auto-opens browser)
hydra-agents serve
```

### Option 3: Python API

```python
import asyncio
from hydra_agents import Hydra

async def main():
    hydra = Hydra()
    result = await hydra.run(
        "Research the current state of AI agents and write a 3-section summary report."
    )
    print(result["output"])
    print(f"Files: {result['files_generated']}")
    print(f"Tokens: {result['execution_summary']['total_tokens']}")

asyncio.run(main())
```

### Option 4: Streaming API

```python
async def main():
    hydra = Hydra()
    
    async for event in hydra.stream("Analyze the AI market and create a report"):
        if event.type == "agent_token":
            print(event.data, end="", flush=True)
        elif event.type == "agent_start":
            print(f"\n🤖 Agent started: {event.agent_id}")
        elif event.type == "agent_tool_call":
            print(f"  🔧 Tool: {event.data['tool']}")
        elif event.type == "quality_score":
            print(f"  📊 Score: {event.data['score']}/10")
        elif event.type == "pipeline_complete":
            print(f"\n✅ Done!")

asyncio.run(main())
```

### Option 5: With File Attachments

```python
result = await hydra.run(
    "Summarize these reports and compare findings",
    files=["report.pdf", "data.xlsx", "notes.md"]
)
```

### Option 6: Callbacks

```python
hydra = Hydra()
hydra.on_agent_start(lambda e: print(f"🤖 {e.agent_id} started"))
hydra.on_agent_complete(lambda e: print(f"✅ {e.agent_id} done"))
hydra.on_tool_call(lambda e: print(f"🔧 {e.data['tool']}"))

result = await hydra.run("Write a market analysis")
```

---

## Web UI

The built-in web interface provides a real-time view of the multi-agent pipeline:

```
┌─────────────────────────────────────────────────┐
│  Task: "Analyze the AI market..."    [⏹ Cancel] │
├─────────────────────────────────────────────────┤
│  🧠 Brain: 4 sub-tasks, 2 groups               │
│                                                  │
│  ⚡ Group 1 — Parallel                           │
│  ┌──────────────┐ ┌──────────────┐              │
│  │ 🔍 Researcher│ │ 📊 Analyst   │              │
│  │ ████████░░   │ │ ██████████ ✅│              │
│  │ 🔧 web_search│ │ Score: 8/10  │              │
│  └──────────────┘ └──────────────┘              │
│                                                  │
│  ⚡ Group 2 — Waiting...                         │
│  ┌──────────────┐                                │
│  │ ✍️ Writer     │                                │
│  │ ⏳ Pending    │                                │
│  └──────────────┘                                │
│                                                  │
│  📝 Synthesis: streaming output...               │
├─────────────────────────────────────────────────┤
│  ⏱ 45s | 🪙 12,450 tokens | 💰 ~$0.03          │
└─────────────────────────────────────────────────┘
```

**Features:**
- Live agent cards with status, tool calls, token preview, quality scores
- Streaming synthesis output token-by-token
- Result view with markdown rendering, agent breakdown, file downloads
- Export: clipboard (with metadata), PDF (print stylesheet), DOCX (server-generated)
- Task history with search and re-run
- Human-in-the-loop confirmation modals with risk badges, queue, auto-timeout, keyboard shortcuts
- Confirmation timeline log tracking all approval decisions
- Connection state monitoring with error banners and toast notifications
- Dark/light mode with glassmorphism design
- Works without backend (mock mode for demo)

---

## API Server

Hydra includes a FastAPI backend for web deployment:

```bash
hydra-agents serve --host 0.0.0.0 --port 8000
```

### REST Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/` | Serve web UI |
| `GET` | `/api/config` | Current config (API key redacted) |
| `POST` | `/api/config` | Update config at runtime |
| `GET` | `/api/tools` | List registered tools |
| `GET` | `/api/models` | Suggested model list |
| `POST` | `/api/upload` | Upload files for processing |
| `POST` | `/api/task` | Run task (REST, non-streaming) |
| `POST` | `/api/export/docx` | Export result as DOCX |
| `GET` | `/api/history` | List past task runs |
| `GET` | `/api/history/{id}` | Full result for a past run |
| `DELETE` | `/api/history/{id}` | Delete a history entry |

### WebSocket

`WS /ws/task` — Real-time streaming endpoint

```json
// Client sends (auth optional)
{"type": "auth", "token": "your-server-token"}
{"type": "start_task", "task": "...", "files": ["upload_id"]}

// Server streams HydraEvents
{"type": "brain_start", "timestamp": 1234567890}
{"type": "agent_start", "agent_id": "agent_abc", "data": {"role": "Researcher"}}
{"type": "agent_token", "agent_id": "agent_abc", "data": "The market"}
{"type": "pipeline_complete", "data": {"output": "...", "files_generated": [...]}}

// Client can send during execution
{"type": "confirmation_response", "confirmation_id": "conf_123", "approved": true}
{"type": "cancel"}
```

---

## Configuration

All settings use the `HYDRA_` environment variable prefix:

| Variable | Default | Description |
|---|---|---|
| `HYDRA_API_KEY` | `""` | LLM provider API key |
| `HYDRA_DEFAULT_MODEL` | `deepseek/deepseek-chat` | Default model (litellm format) |
| `HYDRA_BRAIN_MODEL` | `deepseek/deepseek-chat` | Model for task planning |
| `HYDRA_POST_BRAIN_MODEL` | `deepseek/deepseek-chat` | Model for synthesis |
| `HYDRA_API_BASE` | `None` | Custom API endpoint |
| `HYDRA_MAX_CONCURRENT_AGENTS` | `5` | Max parallel agents |
| `HYDRA_PER_AGENT_TIMEOUT_SECONDS` | `300` | Timeout per agent |
| `HYDRA_TOTAL_TASK_TIMEOUT_SECONDS` | `1200` | Total pipeline timeout |
| `HYDRA_TOTAL_TOKEN_BUDGET` | `1000000` | Token budget (abort if exceeded) |
| `HYDRA_OUTPUT_DIRECTORY` | `./hydra_output` | File output directory |
| `HYDRA_MIN_QUALITY_SCORE` | `5.0` | Minimum score before retry |
| `HYDRA_SERVER_TOKEN` | `""` | Optional API auth token |
| `HYDRA_CORS_ORIGINS` | `*` | CORS allowed origins |
| `HYDRA_SEARCH_BACKEND` | `brave` | Web search provider |
| `HYDRA_SEARCH_API_KEY` | `""` | Search API key |

### Provider Examples

```bash
# Anthropic
HYDRA_API_KEY=sk-ant-...
HYDRA_DEFAULT_MODEL=anthropic/claude-sonnet-4-6

# OpenAI
HYDRA_API_KEY=sk-...
HYDRA_DEFAULT_MODEL=gpt-4o

# DeepSeek
HYDRA_API_KEY=sk-...
HYDRA_DEFAULT_MODEL=deepseek/deepseek-chat
HYDRA_BRAIN_MODEL=deepseek/deepseek-reasoner  # R1 for planning

# Ollama (local, free)
HYDRA_API_BASE=http://localhost:11434
HYDRA_DEFAULT_MODEL=ollama/llama3

# Azure OpenAI
HYDRA_API_KEY=<azure-key>
HYDRA_API_BASE=https://<resource>.openai.azure.com
HYDRA_DEFAULT_MODEL=azure/gpt-4o

# Google Gemini
HYDRA_API_KEY=<gemini-key>
HYDRA_DEFAULT_MODEL=gemini/gemini-2.5-flash
```

---

## Architecture

```
User Task + Files
    │
    ▼
┌─────────┐
│  Brain   │  → Decomposes task → TaskPlan (sub-tasks + agent specs + DAG)
└────┬─────┘
     │
     ▼
┌──────────────┐
│ AgentFactory │  → Instantiates agents with tools, state manager, event bus
└──────┬───────┘
       │
       ▼
┌──────────────────┐
│ ExecutionEngine   │  → DAG execution: parallel groups, retries, semaphore
│                   │
│  [Group 1: A, B]  │  ← Run in parallel
│  [Group 2: C]     │  ← Waits for A and B
└──────┬────────────┘
       │
       ▼
┌──────────────┐
│  Post-Brain  │  → Quality gate → LLM scoring → Retry → Synthesis
└──────────────┘
       │
       ▼
   Final Result + Files + Metadata
```

### How Context Flows

Upstream agent outputs are automatically injected into downstream agent prompts with sanitization:

```
Agent A (Research)  → StateManager → Agent C (Analysis)
Agent B (Data)      → StateManager ↗
                                      ↓
                                Agent D (Report Writer)
```

Token budgeting prevents context overflow. Long outputs are truncated with references to full versions in shared memory. Output sanitization strips prompt injection patterns before injection.

---

## Built-in Tools

### 📄 File Writing
| Tool | Description |
|---|---|
| `write_markdown` | Write `.md` files |
| `write_json` | Write `.json` with pretty-printing |
| `write_csv` | Write `.csv` from rows |
| `write_code` | Write source code (any extension) |

### 📑 Document Generation
| Tool | Description |
|---|---|
| `write_docx` | Word documents (headings, bullets, bold/italic) |
| `write_xlsx` | Excel (multi-sheet, auto-width, freeze, filters) |
| `write_pptx` | PowerPoint (title/content/blank slides, speaker notes) |
| `read_pdf` | Extract text from PDF files |

### 📖 File Reading
| Tool | Description |
|---|---|
| `read_docx` | Read Word documents (.docx + legacy .doc) — text, tables, headings, metadata |
| `read_xlsx` | Read Excel workbooks — structured data, column stats, multi-sheet |
| `read_csv` | Read CSV/TSV — auto-detect encoding (utf-8/gb18030) and delimiter |
| `read_pptx` | Read PowerPoint presentations — slides, speaker notes, tables, metadata |
| `read_code` | Read source code — line numbers, language detection, structure map |

### 🗂️ File Management
| Tool | Description |
|---|---|
| `file_manager` | List, tree, info, find, copy, zip, unzip, mkdir |
| `file_move` | Move/rename files (requires confirmation) |
| `file_delete` | Delete files/dirs (requires confirmation) |

### 🔍 Research & Web
| Tool | Description |
|---|---|
| `web_search` | Search the web (Brave/Tavily/SerpAPI) |
| `web_fetch` | Fetch URL → clean text |
| `http_request` | Generic HTTP client (GET/POST/PUT/DELETE) with SSRF prevention |

### 🧮 Data & Analysis
| Tool | Description |
|---|---|
| `json_validator` | Validate JSON against schema |
| `chart_generator` | Bar/line/pie/scatter charts → PNG |
| `data_transform` | Filter, sort, group_by, select, limit pipelines |

### 💻 Code Execution
| Tool | Description |
|---|---|
| `run_python` | Python execution (temp dir, credential-stripped env, requires confirmation) |
| `run_shell` | Whitelisted shell commands only |

### 🗂️ Memory
| Tool | Description |
|---|---|
| `memory_store` | Write to shared agent memory |
| `memory_retrieve` | Read from shared memory |

### 🌐 Language
| Tool | Description |
|---|---|
| `translate` | LLM-powered translation (any language pair, 16K tokens) |
| `summarize` | Summarize text (bullets/paragraph/executive, 8K tokens) |

### 📝 Templates
| Tool | Description |
|---|---|
| `template_render` | Jinja2 template rendering with sandbox security |

### 📑 PDF Operations
| Tool | Description |
|---|---|
| `pdf_merge` | Merge multiple PDFs with page ranges and bookmarks |
| `pdf_split` | Split PDF by pages, chunks, or one-per-page |

### ✅ Validation
| Tool | Description |
|---|---|
| `output_validator` | Validate data against JSON Schema |
| `quality_scorer` | LLM-based quality scoring (1-10) |

---

## Streaming Events

When using `hydra.stream()` or the WebSocket endpoint, you receive real-time events:

| Event Type | When | Data |
|---|---|---|
| `pipeline_start` | Pipeline begins | Task description |
| `brain_start` | Brain planning begins | — |
| `brain_complete` | Plan ready | Sub-task count, groups |
| `group_start` | Parallel group begins | Group index, agent IDs |
| `agent_start` | Agent begins execution | Agent ID, role |
| `agent_token` | LLM generates a token | Token text |
| `agent_tool_call` | Agent calls a tool | Tool name, arguments |
| `agent_tool_result` | Tool returns | Success/error, data |
| `agent_complete` | Agent finishes | Output, tokens used |
| `agent_error` | Agent failed | Error message |
| `agent_retry` | Agent retrying | Attempt number |
| `group_complete` | All agents in group done | Results |
| `quality_start` | Quality scoring begins | — |
| `quality_score` | Per-agent score | Score (1-10), feedback |
| `quality_retry` | Low-score agent re-running | Agent ID |
| `synthesis_start` | Final synthesis begins | — |
| `synthesis_token` | Synthesis LLM token | Token text |
| `synthesis_complete` | Final output ready | Output, files |
| `file_processed` | Uploaded file processed | File info |
| `confirmation_required` | Tool needs approval | Tool name, args |
| `confirmation_response` | User approved/rejected | Result |
| `pipeline_complete` | Everything done | Full result |
| `pipeline_error` | Pipeline failed | Error details |

---

## Security

Hydra runs LLM-generated code and tool calls. Here's what's protected and what's not:

**What's hardened:**
- **Shell execution**: Whitelist-only (`ls`, `cat`, `head`, `wc`, `grep`, `find`, `jq`). Metacharacters blocked. Uses `subprocess_exec` (no shell interpretation).
- **Python execution**: Runs in temp directory. Cloud credentials stripped from env (`AWS_*`, `OPENAI_API_KEY`, etc.). Requires user confirmation by default.
- **Path traversal**: All file tools validate paths with `Path.is_relative_to()`. PDF reader has `allowed_dirs` restriction.
- **SSRF prevention**: Private IPs blocked (RFC 1918, link-local, loopback, AWS metadata). Redirects disabled. DNS resolution checked.
- **Prompt injection**: Upstream agent outputs sanitized — role markers, XML injection tags, `[INST]`/`<<SYS>>` patterns stripped. Context wrapped in XML delimiters.
- **API auth**: Optional `HYDRA_SERVER_TOKEN` for all endpoints. WebSocket auth via first message (not query params).
- **File upload**: Size limits, file count limits, null byte rejection, chunked reads.
- **Audit logging**: Every LLM call, tool execution, and state mutation logged as JSON Lines with thread-safe writes.
- **Tool isolation**: Stateful tools get per-agent instances. No shared mutable state between concurrent runs.

**What's NOT sandboxed (be honest with yourself):**
- **Python execution**: Has full network access and filesystem read. For real isolation, wrap Hydra in Docker with `--network none`. We don't pretend otherwise.
- **LLM prompt injection**: Defense-in-depth sanitization helps but isn't a guarantee against sophisticated attacks.

**For production deployment**, run Hydra inside a container with restricted network and filesystem access.

---

## File Upload

Hydra extracts text from 30+ file formats for agent context:

**Documents:** `.pdf`, `.docx`, `.xlsx`, `.pptx`
**Text:** `.txt`, `.md`, `.csv`, `.json`, `.yaml`, `.xml`, `.html`, `.log`, `.ini`, `.toml`
**Code:** `.py`, `.js`, `.ts`, `.java`, `.cpp`, `.c`, `.go`, `.rs`, `.rb`, `.php`, `.swift`, `.kt`

- Max 20 files per task, 50MB per file
- 50K character extraction limit per file (truncated with marker)
- Unsupported formats: filepath available for agents to reference directly

---

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
# 270+ tests covering core pipeline, security, streaming, events, server, history
```

---

## Custom Tools

```python
from hydra_agents.tools.base import BaseTool
from hydra_agents.models import ToolResult

class MyTool(BaseTool):
    name = "my_tool"
    description = "Does something useful"
    parameters = {
        "type": "object",
        "properties": {
            "input": {"type": "string", "description": "The input"}
        },
        "required": ["input"],
    }
    requires_confirmation = False  # Set True for human-in-the-loop

    async def execute(self, input: str) -> ToolResult:
        try:
            result = do_something(input)
            return ToolResult(success=True, data=result)
        except Exception as e:
            return ToolResult(success=False, error=str(e))

# Register it
hydra = Hydra()
hydra.tool_registry.register(MyTool())
```

---

## Roadmap

**Phase 4 ✅ COMPLETE:**
- [x] Connection error handling (state machine, banners, toasts)
- [x] Export: clipboard + PDF + DOCX
- [x] Security hardening (WS timeouts, SSRF, path traversal, EventBus fixes, config validation)
- [x] Human-in-the-loop confirmation modal (queue, risk badges, auto-timeout, timeline)
- [x] Tool expansion: 22 → 33 tools (readers, file manager, templates, PDF ops)
- [x] Settings: search config, test connection, validation, backend sync
- [x] Advanced controls: brain strategy presets, custom prompt override, cost toggle
- [x] Responsive polish (mobile/tablet/desktop)

**Phase 5 (Build & Deploy) — IN PROGRESS:**
- [x] PyPI package (`pip install hydra-agents`)
- [x] CLI entry point (`hydra-agents serve` / `hydra-agents run`)
- [x] Auto-open browser on launch
- [x] Frontend bundled in wheel
- [ ] Docker image (multi-stage build)
- [ ] CI/CD (GitHub Actions → PyPI on tag)
- [ ] Standalone executable (PyInstaller, Windows)

**Phase 6 (Future):**
- [ ] MCP (Model Context Protocol) tool integration
- [ ] Vector store / RAG tool
- [ ] Data classification / sensitivity routing
- [ ] Docker `--network none` sandboxing for code tools
- [ ] Webhook triggers

---

## License

MIT
