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 Jul 29, 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:
Newer release available (1.0.0.post282)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: AI Data Team

GitHub Statistics

Data verified by PyPI on Jul 29, 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.post199.tar.gz (253.7 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.post199-py3-none-any.whl (291.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: hyperforge-1.0.0.post199.tar.gz
  • Upload date:
  • Size: 253.7 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.post199.tar.gz
Algorithm Hash digest
SHA256 cd1836f2bbefe28c56f069842da14a56f4a6c69306301d322f21c5f0898120ea
MD5 888dfebc96b487c4d810b992b6122414
BLAKE2b-256 cdb624ce36e9b36d9f46ba50fde4194197b7369c2a786ef9c146d93e99256c40

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyperforge-1.0.0.post199.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.post199-py3-none-any.whl.

File metadata

File hashes

Hashes for hyperforge-1.0.0.post199-py3-none-any.whl
Algorithm Hash digest
SHA256 0f0bda611dd6aca6ea9ac9f7196c24792e9b322d85c77d314e65a0b691eeab4c
MD5 c4153f0154e8e018a88a9016e0cefacd
BLAKE2b-256 969871bf7694e5e7e034f3451303cf909036a57bdf512bc3b738724b6907e2b4

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyperforge-1.0.0.post199-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

1.0.0.post282

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

This release

1.0.0.post199 This release

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