Metadata-Version: 2.4
Name: hyperforge
Version: 1.0.0.post48
Summary: Agentic Framework for Orchestrated Runtime, Governance, and Execution
Author: AI Data Team
Author-email: AI Data Team <learning@nuclia.com>
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: alembic
Requires-Dist: pydantic
Requires-Dist: nuclia>=4.9.25
Requires-Dist: nuclia-models>=0.52.1
Requires-Dist: nucliadb-models>=6.13.1.post6414
Requires-Dist: nucliadb-sdk>=6.13.1.post6414
Requires-Dist: nucliadb-telemetry[otel]
Requires-Dist: pydantic-settings
Requires-Dist: mcp>=1.26.0
Requires-Dist: prometheus-client
Requires-Dist: mrflagly>=0.2.11
Requires-Dist: aiodns
Requires-Dist: httpx
Requires-Dist: jinja2
Requires-Dist: databases[asyncpg]
Requires-Dist: sqlalchemy
Requires-Dist: cryptography
Requires-Dist: mmh3
Requires-Dist: psycopg2
Requires-Dist: tenacity
Requires-Dist: websockets
Requires-Dist: redis[hiredis]>=6.4.0
Requires-Dist: types-redis>=4.6.0.20241004
Requires-Dist: ruff>=0.15.10
Requires-Dist: lru-dict
Requires-Dist: sentry-sdk
Requires-Dist: fastapi
Requires-Dist: starlette>1.0.0
Requires-Python: >=3.10
Project-URL: Progress, https://progress.com
Project-URL: Github, https://github.com/nuclia/hyperforge
Project-URL: API Reference, https://docs.rag.progress.cloud
Description-Content-Type: text/markdown

# Hyperforge

Hyperforge is an **Agentic Framework for Orchestrated Runtime, Governance, and Execution** — the core runtime powering AI agent workflows at Nuclia. It provides the infrastructure for defining, deploying, and running agentic pipelines backed by NucliaDB for memory and retrieval, Redis/Valkey for pub/sub and session state, PostgreSQL for persistence, and a FastAPI HTTP/WebSocket API surface.

## Architecture Overview

```
hyperforge/
├── api/          # FastAPI application, REST + WebSocket endpoints, OAuth
├── broker/       # Pub/sub backends (Redis, local)
├── context/      # Execution context passed through agent runs
├── db/           # SQLAlchemy models and Alembic migrations
├── memory/       # Session memory backed by NucliaDB
├── retrieval/    # Retrieval agent and config
├── server/       # Long-running server process
├── standalone/   # Single-process standalone mode
├── agent.py      # Base Agent and AgentConfig abstractions
├── engine.py     # Initialization and state wiring
├── manager.py    # Agent lifecycle manager
├── workflows.py  # Workflow data models
└── settings.py   # Pydantic settings (env-driven)
```

Key components:

- **Agent / AgentConfig** — abstract base classes for building typed, configurable agents
- **Engine** — initializes agent state, loads external modules, wires LLM connections and memory
- **Manager** — handles agent lifecycle within a session
- **Memory** — session-scoped memory stored in NucliaDB (`SessionMemory`, `QuestionMemory`)
- **Broker** — pub/sub layer (Redis or in-process) for streaming workflow events
- **API** — FastAPI app exposing REST and WebSocket endpoints for agents, workflows, sessions, MCP, and OAuth
- **Workflows** — structured workflow definitions with parameters, rules, and required fields

## Install

From the workspace root:

```bash
uv sync
```

## Running

### API server

```bash
uv run hyperforge-api
```

### Other entry points

| Command | Description |
|---|---|
| `hyperforge-api` | Main HTTP API server |
| `hyperforge-server` | Background server process |
| `hyperforge-sandbox` | Sandbox execution environment |
| `hyperforge-standalone` | All-in-one single-process mode |
| `hyperforge-downloads-cronjob` | Downloads cleanup cron job |
| `hyperforge-workflows-cleanup-cronjob` | Stale workflow cleanup cron job |
| `hyperforge-extract-openapi` | Extract OpenAPI schema to file |

### Health and observability endpoints

- `GET /health/ready` — readiness probe
- `GET /health/alive` — liveness probe
- `GET /metrics` — Prometheus metrics

## Configuration

All settings are provided through environment variables consumed by Pydantic `BaseSettings`.

| Variable | Description |
|---|---|
| `HTTP_HOST` | Bind host (default `0.0.0.0`) |
| `HTTP_PORT` | Bind port (default `8080`) |
| `MEMORY_READER_NUCLIADB` | NucliaDB read endpoint |
| `MEMORY_WRITER_NUCLIADB` | NucliaDB write endpoint |
| `MEMORY_SEARCH_NUCLIADB` | NucliaDB search endpoint |
| `MEMORY_APIKEY_NUCLIADB` | NucliaDB API key |
| `VALKEY_URL` | Redis/Valkey connection URL |
| `LOAD_MODULES` | Comma-separated list of agent package modules to load at startup |
| `NUCLIA_ZONE` | Nuclia zone (default `arag`) |
| `NUCLIA_PUBLIC_URL` | Public Nuclia URL template (default `https://{zone}.nuclia.com`) |

## Loading Agent Packages

Hyperforge supports dynamically loading external agent packages at startup. Set the `LOAD_MODULES` environment variable to a comma-separated list of Python module names. Each module is scanned for agent and configuration definitions and registered in the global registry.

```bash
LOAD_MODULES=hyperforge_rephrase,my_custom_agent uv run hyperforge-api
```

## Development

Run tests from the workspace root:

```bash
uv run pytest hyperforge
```

Run a specific test file:

```bash
uv run pytest hyperforge/tests/test_engine.py
```

Format and lint:

```bash
make fmt
make lint
```

## License

Apache 2.0 — see [LICENSE](../LICENSE).
