Metadata-Version: 2.4
Name: hyperflow-ai
Version: 1.0.0
Summary: A self-improving agent framework built on LangChain and LangGraph
Author-email: Muhammad Umer Farooq <umer@lablnet.com>
License: MIT
Project-URL: Homepage, https://github.com/lablnet/HyperFlow
Project-URL: Bug Reports, https://github.com/lablnet/HyperFlow/issues
Project-URL: Source, https://github.com/lablnet/HyperFlow
Project-URL: Changelog, https://github.com/lablnet/HyperFlow/blob/main/CHANGELOG.md
Keywords: agent,self-improving,meta-learning,langchain,langgraph,evolutionary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain>=0.3
Requires-Dist: langchain-core>=0.3
Requires-Dist: langgraph>=0.4
Requires-Dist: langchain-openai>=0.3
Requires-Dist: langchain-anthropic>=0.3
Requires-Dist: langchain-google-genai>=2.1
Requires-Dist: langchain-ollama>=0.3
Requires-Dist: docker>=7.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: gitpython>=3.1
Requires-Dist: pydantic>=2.0
Requires-Dist: click>=8.1
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# HyperFlow (Python)

Self-improving agent framework powered by LangChain and LangGraph.

Inspired by [HyperAgents](https://github.com/facebookresearch/HyperAgents) (Meta Research, 2026) -- ported to Python with a generic, pluggable architecture.

## What it does

HyperAgents runs an evolutionary self-improvement loop where a **MetaAgent** rewrites a **TaskAgent's** code to make it better at solving tasks. Each generation:

1. Select a parent agent from the archive
2. MetaAgent reads past evaluation scores and edits the source code
3. The modified TaskAgent is evaluated on domain tasks
4. Score + code diff are saved to the archive
5. Repeat

The TaskAgent gets better over generations without manual intervention.

> **New here?** Read [docs/concepts.md](docs/concepts.md) for a detailed explanation of every concept with examples.

## Installation

```bash
# Install from PyPI
pip install hyperflow

# Or install from source for development
pip install -e .
```

### Requirements

- Python 3.11+
- At least one LLM provider API key (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)

## Quick Start

```bash
# Set your API key
export OPENAI_API_KEY="sk-..."

# Run the bash example (single eval)
cd examples/bash
python run.py

# Run with evolutionary loop
python run.py evolve
```

## Project Structure

```
hyperflow/
  __init__.py           # Public API re-exports
  agent/
    base_agent.py       # Abstract AgentSystem base class
    llm.py              # Multi-provider LLM factory
    llm_with_tools.py   # LangGraph ReAct chat loop
    meta_agent.py       # MetaAgent (mutation operator)
    task_agent.py       # TaskAgent (task solver)
    tool_registry.py    # Tool registration
  core/
    ensemble.py         # Best-of-archive ensemble
    generate_loop.py    # Main evolutionary loop
    select_parent.py    # Parent selection strategies
  domains/
    base.py             # Domain/DomainTask/EvalResult interfaces
    evaluators.py       # Static, LLM judge, human evaluators
    harness.py          # Evaluation harness
    report.py           # Report generation
  prompts/
    llm_judge.py        # LLM judge prompt template
    meta_agent.py       # MetaAgent prompt template
    task_agent.py       # TaskAgent prompt template
  tools/
    __init__.py         # get_framework_tools()
    bash.py             # Bash shell tool
    editor.py           # File editor tool
  utils/
    archive.py          # JSONL archive CRUD
    common.py           # JSON extraction, file helpers
    constants.py        # Shared constants
    docker.py           # Docker container management
    executor.py         # Local/Docker execution
    git.py              # Git operations
examples/
  bash/                 # Bash command generation
  calculator/           # Buggy tool fix demo
  factcheck/            # True/false classification
  git_evolution/        # Git-based evolution with patches
  paper_review/         # Paper accept/reject prediction
  scoring/              # Math grading self-improvement
```

## Supported Models

```python
from hyperflow import MODELS

# Available model presets
MODELS["OPENAI_GPT4O"]       # "openai/gpt-4o"
MODELS["OPENAI_GPT4O_MINI"]  # "openai/gpt-4o-mini"
MODELS["OPENAI_O3"]          # "openai/o3"
MODELS["OPENAI_O4_MINI"]     # "openai/o4-mini"
MODELS["CLAUDE_SONNET"]      # "anthropic/claude-sonnet-4-5-20250929"
MODELS["GEMINI_PRO"]         # "gemini/gemini-2.5-pro"
MODELS["OLLAMA_LLAMA3"]      # "ollama/llama3"
```

Or use any `"provider/model-name"` string.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `GOOGLE_API_KEY` | Google Gemini API key |
| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |
| `HYPERFLOW_MODEL` | Default model for examples (e.g. `openai/gpt-4o`) |

## Examples

### Single Evaluation

```bash
cd examples/bash && python run.py
cd examples/factcheck && python run.py
cd examples/paper_review && python run.py
```

### Evolutionary Self-Improvement

```bash
cd examples/bash && python run.py evolve
cd examples/factcheck && python run.py evolve
cd examples/scoring && python run.py
cd examples/calculator && python run.py
cd examples/git_evolution && python run.py
```

### Git-Based Evolution (with patches)

```bash
cd examples/git_evolution && python run.py        # 2 generations
cd examples/git_evolution && python run.py 5      # 5 generations
cd examples/git_evolution && python run.py --reset # start over
```

## License

MIT
