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 8, 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 8, 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.10

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.post88.tar.gz (244.3 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.post88-py3-none-any.whl (280.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: hyperforge-1.0.0.post88.tar.gz
  • Upload date:
  • Size: 244.3 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.post88.tar.gz
Algorithm Hash digest
SHA256 dde1a74ccc2f53050bbe5ab562da1f889663d8509d6f0d119c07cde8e4e050df
MD5 d8129a50d293e2f565f44981d266b375
BLAKE2b-256 aba6fef1556f02a2da6974cd3deeaa8ab8cab7f29d05556e4fe022c77508aa7e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hyperforge-1.0.0.post88-py3-none-any.whl
Algorithm Hash digest
SHA256 7d1cace0e74a6279e8be27d1726c4b42695277dd7fa7896a00933371d97d0590
MD5 285dad47d0ffdd0414f3d888a52497f9
BLAKE2b-256 871fa0c51446440025f1b2ce76c56f370a60aaf159eba40761817bf9a0e7cff4

See more details on using hashes here.

Provenance

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

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

This release

1.0.0.post88 This release

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