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.

Metadata

Release files for hyperforge 1.0.0.post414

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

Built distribution (wheel)

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

Total release size: 723.9 kB

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

Download URL	hyperforge-1.0.0.post414.tar.gz
Size	335.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`b9807709fefac4984f8f13130d5dd9562e459089df4bf0b1bb93be0d7b8ee5ad`
BLAKE2b-256 checksum How to use checksums	`0daf0cffc2884922ddcc7133401e7cf80762fd44b7a5f2af2c622aad25474c19`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/2140b158941372cc0790e19cc60fa3b3c83fdc88

Workflow

Publishing configuration: github.com/nuclia/hyperforge/blob/2140b158941372cc0790e19cc60fa3b3c83fdc88/.github/workflows/hyperforge_workflow.yaml
Publishing logs: github.com/nuclia/hyperforge/actions/runs/36531348798/attempts/1

Artifact

Subject: hyperforge-1.0.0.post414.tar.gz
SHA-256 checksum: b9807709fefac4984f8f13130d5dd9562e459089df4bf0b1bb93be0d7b8ee5ad Verifying attestations

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

Download URL	hyperforge-1.0.0.post414-py3-none-any.whl
Size	388.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`02732550172a23feece824ea690b9fed24306a9cb802f0a9eeaafbf51529737e`
BLAKE2b-256 checksum How to use checksums	`f99bf585802cc1d0118e27a972ba2356b6f530ee3e22d1e48b0b5a7a5e936740`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/hyperforge
Publishing commit: github.com/nuclia/hyperforge/tree/2140b158941372cc0790e19cc60fa3b3c83fdc88

Workflow

Publishing configuration: github.com/nuclia/hyperforge/blob/2140b158941372cc0790e19cc60fa3b3c83fdc88/.github/workflows/hyperforge_workflow.yaml
Publishing logs: github.com/nuclia/hyperforge/actions/runs/36531348798/attempts/1

Artifact

Subject: hyperforge-1.0.0.post414-py3-none-any.whl
SHA-256 checksum: 02732550172a23feece824ea690b9fed24306a9cb802f0a9eeaafbf51529737e Verifying attestations