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 HTTP, MCP, and optional A2A gRPC mode
`hyperforge-a2a-grpc`	Database-backed SaaS A2A gRPC server
`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`)

Standalone A2A

Standalone can expose its configured static agent over A2A from the same hyperforge-standalone process. It requires a Redis/Valkey broker because A2A task state and cross-instance feedback are durable Redis stores; the default in-memory broker remains suitable only for HTTP/MCP local development.

BROKER_REDIS_DSN=redis://valkey:6379 \
A2A_ENABLED=true \
A2A_ACCOUNT=local \
A2A_AGENT_ID=venue \
A2A_GRPC_HOST=0.0.0.0 \
A2A_GRPC_PORT=8034 \
A2A_PUBLIC_URL=venue.example.test:8034 \
uv run hyperforge-standalone

Use distinct BROKER_REDIS_ACTIVATE_SUBJECT and A2A_TASK_STORE_PREFIX values for independent Standalone installations sharing one Valkey cluster. TLS and mTLS use the A2A_TLS_* variables supported by the SaaS A2A server. If the owner process restarts while a task awaits feedback, the client must resend the request; Redis keeps protocol task visibility but does not serialize live workflow continuations.

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.post365

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hyperforge 1.0.0.post365
File	Size	Uploaded
hyperforge-1.0.0.post365.tar.gz	305.5 kB	Sep 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hyperforge 1.0.0.post365
File	Interpreter	ABI	Platform	Reset
hyperforge-1.0.0.post365-py3-none-any.whl 355.3 kB Sep 16, 2026	Python 3	none	any	Details

Total release size: 660.8 kB

Release files / hyperforge-1.0.0.post365.tar.gz

Download URL	hyperforge-1.0.0.post365.tar.gz
Size	305.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`da917ad19882f93eea62641159ce11035b02269d310bc8331654a86b7122dcc3`
BLAKE2b-256 checksum How to use checksums	`c33cf0a7bed57bff3a90d60602b3f2e65f0d5ef184f4d87badb0e597f6b2ab8c`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/hyperforge
Publishing commit: github.com/nuclia/hyperforge/tree/4825a4cad15dc62446f4c8cc72b62c666a130081

Workflow

Publishing configuration: github.com/nuclia/hyperforge/blob/4825a4cad15dc62446f4c8cc72b62c666a130081/.github/workflows/hyperforge_workflow.yaml
Publishing logs: github.com/nuclia/hyperforge/actions/runs/35098548076/attempts/1

Artifact

Subject: hyperforge-1.0.0.post365.tar.gz
SHA-256 checksum: da917ad19882f93eea62641159ce11035b02269d310bc8331654a86b7122dcc3 Verifying attestations

Release files / hyperforge-1.0.0.post365-py3-none-any.whl

Download URL	hyperforge-1.0.0.post365-py3-none-any.whl
Size	355.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9ec234953b1383feaf804a46dbbba5e33178a2a4e653c1d56cda3427cc92107a`
BLAKE2b-256 checksum How to use checksums	`18d7a3ee47ef5866a2b5e379e8d0e6c13ba913b24146d62c5d029839cdb9fdb4`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/hyperforge
Publishing commit: github.com/nuclia/hyperforge/tree/4825a4cad15dc62446f4c8cc72b62c666a130081

Workflow

Publishing configuration: github.com/nuclia/hyperforge/blob/4825a4cad15dc62446f4c8cc72b62c666a130081/.github/workflows/hyperforge_workflow.yaml
Publishing logs: github.com/nuclia/hyperforge/actions/runs/35098548076/attempts/1

Artifact

Subject: hyperforge-1.0.0.post365-py3-none-any.whl
SHA-256 checksum: 9ec234953b1383feaf804a46dbbba5e33178a2a4e653c1d56cda3427cc92107a Verifying attestations