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:
uv sync
Running
API server
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 probeGET /health/alive— liveness probeGET /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.
LOAD_MODULES=hyperforge_rephrase,my_custom_agent uv run hyperforge-api
Development
Run tests from the workspace root:
uv run pytest hyperforge
Run a specific test file:
uv run pytest hyperforge/tests/test_engine.py
Format and lint:
make fmt
make lint
License
Apache 2.0 — see LICENSE.
Release files for hyperforge 1.0.0.post288
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hyperforge-1.0.0.post288.tar.gz | 288.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hyperforge-1.0.0.post288-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 622.6 kB
Release files / hyperforge-1.0.0.post288.tar.gz
| Download URL | hyperforge-1.0.0.post288.tar.gz |
|---|---|
| Size | 288.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4de67c827aab74841a203845af7e530ba78ecf74dbc1d60db10d36206129c61e
|
|
BLAKE2b-256 checksum How to use checksums |
401bd1b3b0657004d6228ee94f247b7b9f05460a0747833a8acf8182cce46c36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / hyperforge-1.0.0.post288-py3-none-any.whl
| Download URL | hyperforge-1.0.0.post288-py3-none-any.whl |
|---|---|
| Size | 334.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c67cb5ebb657d703c27f9e94f13a2d364121871006c51c7347b81da8b695700e
|
|
BLAKE2b-256 checksum How to use checksums |
dbdaa795a28e24a704420b196db0b4d3a3cb0a54b17bafe2a6dfcf7bbcfb24d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency log
