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 13, 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 13, 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.post134.tar.gz (245.1 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.post134-py3-none-any.whl (281.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: hyperforge-1.0.0.post134.tar.gz
  • Upload date:
  • Size: 245.1 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.post134.tar.gz
Algorithm Hash digest
SHA256 fd39424674b9ba0b9d60900bc3a71376a4ff39f5c88d633596b711c2bff63504
MD5 f33f2326452f9a8f7326f048c41fa081
BLAKE2b-256 3bc6b87ed33c7597c21fd1d305200128ef36f620f3e367a51d3efbc2e5ef30ff

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hyperforge-1.0.0.post134-py3-none-any.whl
Algorithm Hash digest
SHA256 7daf019ec5855cfa9f429ae8d17de5968ae72f159a4e68f11eb60f1e12b4c465
MD5 20aa4933cfc9753e84302b052b8ee5e1
BLAKE2b-256 98cfac024aac30899bb2d5a3c2bbc610f378edf69b35bc3ea5e2afac6bf900b1

See more details on using hashes here.

Provenance

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

This release

1.0.0.post134 This release

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