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 27, 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 27, 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.post188.tar.gz (251.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.post188-py3-none-any.whl (288.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: hyperforge-1.0.0.post188.tar.gz
  • Upload date:
  • Size: 251.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.post188.tar.gz
Algorithm Hash digest
SHA256 e0a44e955ecde09db5e2bf4f55aa9fd315bbbf14c916ece5e1fa01116795bc09
MD5 b584bb19b7991cfd9a2b5baaf7a3861b
BLAKE2b-256 f52e20d5a1cb3ece0b57eec44e1d25903799ab5ec47412af02fafe352238bfcd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hyperforge-1.0.0.post188-py3-none-any.whl
Algorithm Hash digest
SHA256 ded1d979c2420e83a941cea867c60d0310173b95fe93ce30390c96726dc4f8df
MD5 b724e4d718a7d80bb8149118d8122f5f
BLAKE2b-256 b8f610e8908aa9ef7a8881541b1ea6f0f771b46b79d45a8e9941bfe1e6bf1195

See more details on using hashes here.

Provenance

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

1.0.0.post199

2 files

1.0.0.post195

2 files

1.0.0.post190

2 files

This release

1.0.0.post188 This release

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