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

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.

Project links

Data verified by PyPI on Sep 1, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: AI Data Team

GitHub Statistics

Data verified by PyPI on Sep 1, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hyperforge-1.0.0.post282.tar.gz (258.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hyperforge-1.0.0.post282-py3-none-any.whl (295.3 kB view details)

Uploaded Python 3

File details

Details for the file hyperforge-1.0.0.post282.tar.gz.

File metadata

  • Download URL: hyperforge-1.0.0.post282.tar.gz
  • Upload date:
  • Size: 258.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for hyperforge-1.0.0.post282.tar.gz
Algorithm Hash digest
SHA256 434b83c82d323726762fa33069d0b7436c22ab8a273e906e1fa4344b884277fa
MD5 f57e8ab2ce475bfa6a3397daaef02c82
BLAKE2b-256 bc87c1dd07c918a9816faf6f1f6eb159df625dcc9293d8170719c70ed6aa40e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyperforge-1.0.0.post282.tar.gz:

Publisher: hyperforge_workflow.yaml on nuclia/hyperforge

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hyperforge-1.0.0.post282-py3-none-any.whl.

File metadata

File hashes

Hashes for hyperforge-1.0.0.post282-py3-none-any.whl
Algorithm Hash digest
SHA256 dc7018d034ab73169b2053825e5dbf287a4cc34a29257f1e991e38462b6f9b0e
MD5 bcccf408c507227eaa0c98c1d8229533
BLAKE2b-256 85e96392571ff8d15fe73245d1deda269c62532d1af85ded731fd5be5f120e04

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyperforge-1.0.0.post282-py3-none-any.whl:

Publisher: hyperforge_workflow.yaml on nuclia/hyperforge

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.0.post282 This release

2 files

1.0.0.post281

2 files

1.0.0.post245

2 files

1.0.0.post243

2 files

1.0.0.post237

2 files

1.0.0.post235

2 files

1.0.0.post228

2 files

1.0.0.post226

2 files

1.0.0.post222

2 files

1.0.0.post199

2 files

1.0.0.post195

2 files

1.0.0.post190

2 files

1.0.0.post188

2 files

1.0.0.post184

2 files

1.0.0.post182

2 files

1.0.0.post179

2 files

1.0.0.post170

2 files

1.0.0.post158

2 files

1.0.0.post156

2 files

1.0.0.post148

2 files

1.0.0.post145

2 files

1.0.0.post134

2 files

1.0.0.post132

2 files

1.0.0.post124

2 files

1.0.0.post119

2 files

1.0.0.post116

2 files

1.0.0.post88

2 files

1.0.0.post80

2 files

1.0.0.post76

2 files

1.0.0.post70

2 files

1.0.0.post68

2 files

1.0.0.post66

2 files

1.0.0.post64

2 files

1.0.0.post62

2 files

1.0.0.post60

2 files

1.0.0.post57

2 files

1.0.0.post56

2 files

1.0.0.post55

2 files

1.0.0.post50

2 files

1.0.0.post48

2 files

1.0.0.post46

2 files

1.0.0.post44

2 files

1.0.0.post39

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page