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

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.post323
File	Size	Uploaded
hyperforge-1.0.0.post323.tar.gz	302.9 kB	Sep 7, 2026	Details

Built distribution (wheel)

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

Total release size: 655.4 kB

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

Download URL	hyperforge-1.0.0.post323.tar.gz
Size	302.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`3c33f9ff46eda9b4cb16667297b8eb0c1236c1aa045f73dfae0fd6d450866a4d`
BLAKE2b-256 checksum How to use checksums	`cda1fe2bcc0932eea671aa3a8815e2964b9c2cd3b9e54b110b909cc30b1aff0b`
Upload date	Sep 7, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/hyperforge
Publishing commit: github.com/nuclia/hyperforge/tree/90d91e6a8660d183f2e2625d08032a699f7add1c

Workflow

Publishing configuration: github.com/nuclia/hyperforge/blob/90d91e6a8660d183f2e2625d08032a699f7add1c/.github/workflows/hyperforge_workflow.yaml
Publishing logs: github.com/nuclia/hyperforge/actions/runs/34094643965/attempts/1

Artifact

Subject: hyperforge-1.0.0.post323.tar.gz
SHA-256 checksum: 3c33f9ff46eda9b4cb16667297b8eb0c1236c1aa045f73dfae0fd6d450866a4d Verifying attestations

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

Download URL	hyperforge-1.0.0.post323-py3-none-any.whl
Size	352.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`631ab2f86809d4d513b0165f6e7dd73739bc23eac4d000c345a04d252831c9c1`
BLAKE2b-256 checksum How to use checksums	`3c35908814aa775bb620ba4254112d2b101e15c6a7b6472c34aa33fa60127726`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/hyperforge
Publishing commit: github.com/nuclia/hyperforge/tree/90d91e6a8660d183f2e2625d08032a699f7add1c

Workflow

Publishing configuration: github.com/nuclia/hyperforge/blob/90d91e6a8660d183f2e2625d08032a699f7add1c/.github/workflows/hyperforge_workflow.yaml
Publishing logs: github.com/nuclia/hyperforge/actions/runs/34094643965/attempts/1

Artifact

Subject: hyperforge-1.0.0.post323-py3-none-any.whl
SHA-256 checksum: 631ab2f86809d4d513b0165f6e7dd73739bc23eac4d000c345a04d252831c9c1 Verifying attestations