hyperforge 1.0.0.post19__tar.gz

hyperforge-1.0.0.post19/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hyperforge
+Version: 1.0.0.post19
+Summary: Agentic Framework for Orchestrated Runtime, Governance, and Execution
+Author-email: AI Data Team <learning@nuclia.com>
+License-Expression: Apache-2.0
+Project-URL: Progress, https://progress.com
+Project-URL: Github, https://github.com/nuclia/forge
+Project-URL: API Reference, https://docs.rag.progress.cloud
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: alembic
+Requires-Dist: pydantic
+Requires-Dist: nuclia>=4.9.25
+Requires-Dist: nuclia-models>=0.52.1
+Requires-Dist: nucliadb-models>=6.13.1.post6414
+Requires-Dist: nucliadb-sdk>=6.13.1.post6414
+Requires-Dist: nucliadb-telemetry[otel]
+Requires-Dist: pydantic_settings
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: prometheus_client
+Requires-Dist: mrflagly>=0.2.11
+Requires-Dist: aiodns
+Requires-Dist: httpx
+Requires-Dist: jinja2
+Requires-Dist: databases[asyncpg]
+Requires-Dist: sqlalchemy
+Requires-Dist: cryptography
+Requires-Dist: mmh3
+Requires-Dist: psycopg2
+Requires-Dist: tenacity
+Requires-Dist: websockets
+Requires-Dist: redis[hiredis]>=6.4.0
+Requires-Dist: types-redis>=4.6.0.20241004
+Requires-Dist: ruff>=0.15.10
+Requires-Dist: lru-dict
+Requires-Dist: sentry_sdk
+Requires-Dist: fastapi
+
+# Hyperforge
+
+Hyperforge is the core agentic workflow framework in this repository. It
+provides the runtime, HTTP API, workflow orchestration, broker integration,
+persistence layer, and support for loading Hyperforge agent packages.
+
+## Install
+
+From the workspace root:
+
+```bash
+uv sync
+```
+
+## Run
+
+Start the API service:
+
+```bash
+uv run hyperforge-api
+```
+
+Useful endpoints:
+
+- `/health/ready`
+- `/health/alive`
+- `/metrics`
+
+## Configuration
+
+Runtime configuration is provided through environment variables consumed by
+Pydantic settings. Common settings include:
+
+- `HTTP_HOST` and `HTTP_PORT`
+- `MEMORY_READER_NUCLIADB`, `MEMORY_WRITER_NUCLIADB`, and
+  `MEMORY_SEARCH_NUCLIADB`
+- `MEMORY_APIKEY_NUCLIADB`
+- `VALKEY_URL`
+- `LOAD_MODULES`
+
+## Development
+
+Run the package tests from the workspace root:
+
+```bash
+uv run pytest hyperforge
+```
+
+Format and lint with the root `Makefile`:
+
+```bash
+make fmt
+make lint
+```

hyperforge-1.0.0.post19/README.md

@@ -0,0 +1,54 @@
+# Hyperforge
+
+Hyperforge is the core agentic workflow framework in this repository. It
+provides the runtime, HTTP API, workflow orchestration, broker integration,
+persistence layer, and support for loading Hyperforge agent packages.
+
+## Install
+
+From the workspace root:
+
+```bash
+uv sync
+```
+
+## Run
+
+Start the API service:
+
+```bash
+uv run hyperforge-api
+```
+
+Useful endpoints:
+
+- `/health/ready`
+- `/health/alive`
+- `/metrics`
+
+## Configuration
+
+Runtime configuration is provided through environment variables consumed by
+Pydantic settings. Common settings include:
+
+- `HTTP_HOST` and `HTTP_PORT`
+- `MEMORY_READER_NUCLIADB`, `MEMORY_WRITER_NUCLIADB`, and
+  `MEMORY_SEARCH_NUCLIADB`
+- `MEMORY_APIKEY_NUCLIADB`
+- `VALKEY_URL`
+- `LOAD_MODULES`
+
+## Development
+
+Run the package tests from the workspace root:
+
+```bash
+uv run pytest hyperforge
+```
+
+Format and lint with the root `Makefile`:
+
+```bash
+make fmt
+make lint
+```

hyperforge-1.0.0.post19/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools >= 64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperforge"
+version = "1.0.0.post19"
+authors = [{ name = "AI Data Team", email = "learning@nuclia.com" }]
+description = "Agentic Framework for Orchestrated Runtime, Governance, and Execution"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "Apache-2.0"
+dependencies = [
+    "alembic",
+    "pydantic",
+    "nuclia>=4.9.25",
+    "nuclia-models>=0.52.1",
+    "nucliadb-models>=6.13.1.post6414",
+    "nucliadb-sdk>=6.13.1.post6414",
+    "nucliadb-telemetry[otel]",
+    "pydantic_settings",
+    "mcp>=1.26.0",
+    "prometheus_client",
+    "mrflagly>=0.2.11",
+    "aiodns",
+    "httpx",
+    "jinja2",
+    "databases[asyncpg]",
+    "sqlalchemy",
+    "cryptography",
+    "mmh3",
+    "psycopg2",
+    "tenacity",
+    "websockets",
+    "redis[hiredis]>=6.4.0",
+    "types-redis>=4.6.0.20241004",
+    "ruff>=0.15.10",
+    "lru-dict",
+    "sentry_sdk",
+    "fastapi",
+]
+
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-mock",
+    "pytest-benchmark",
+    "pytest-docker-fixtures>=1.4.2",
+    "pytest-lazy-fixtures",
+    "httpx[http2]",
+    "hyperforge_rephrase",
+    "inline_snapshot",
+    "sqlalchemy_utils",
+]
+
+[tool.setuptools.packages.find]
+where = ["src/"]
+
+[tool.setuptools.package-data]
+hyperforge = ["frontend/dist/*"]
+
+[project.urls]
+"Progress" = "https://progress.com"
+"Github" = "https://github.com/nuclia/forge"
+"API Reference" = "https://docs.rag.progress.cloud"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+
+[project.scripts]
+hyperforge-api = "hyperforge.api:commands.run"
+hyperforge-server = "hyperforge.server:run.run"
+hyperforge-sandbox = "hyperforge.sandbox:run.run"
+hyperforge-extract-openapi = "hyperforge.api.commands:extract_openapi"
+hyperforge-downloads-cronjob = "hyperforge.downloads.command:run"
+hyperforge-workflows-cleanup-cronjob = "hyperforge.agents.workflow_cleanup:run"
+hyperforge-standalone = "hyperforge.standalone:run.run"

hyperforge-1.0.0.post19/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hyperforge-1.0.0.post19/src/hyperforge/__init__.py

@@ -0,0 +1,16 @@
+import logging
+
+import fire  # type: ignore
+import jinja2
+
+# Jinja vulnerability is not a concern since this is used to format a string prompt, not to render HTML
+PROMPT_ENVIRONMENT = jinja2.Environment()  # nosemgrep
+
+
+logger = logging.getLogger("hyperforge")
+
+
+def cli():
+    from hyperforge.arag import ARAG
+
+    fire.Fire(ARAG)

hyperforge-1.0.0.post19/src/hyperforge/agent.py

@@ -0,0 +1,81 @@
+import abc
+import uuid
+from typing import Any, Generic, List, Optional, Self, TypeVar
+
+from pydantic import BaseModel, Field
+
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import QuestionMemory
+from hyperforge.utils import WidgetType
+
+
+class AgentConfig(BaseModel):
+    id: Optional[str] = Field(default_factory=lambda: str(uuid.uuid4()))
+    title: str = "agent"
+    rules: Optional[List[str]] = Field(
+        default=None,
+        title="Agent rules",
+        description="List of rules to follow when executing this agent",
+        json_schema_extra={
+            "widget": WidgetType.NOT_SHOWN,
+        },
+    )
+    max_retries: int = 1
+    module: Any = Field(
+        ..., title="Agent module", description="Module/type of the agent"
+    )
+
+    def subagent_configure(self, config: dict):
+        pass
+
+
+T_Config = TypeVar("T_Config", bound=AgentConfig)
+
+
+class Agent(Generic[T_Config]):
+    __root_agent__: bool = False
+    agent_id: str
+    config: T_Config
+
+    def __init__(self, config: T_Config, agent_id: Optional[str] = None):
+        self.config: T_Config = config
+        self.agent_id: str = (
+            agent_id
+            if agent_id is not None
+            else config.id
+            if hasattr(config, "id") and config.id is not None
+            else str(uuid.uuid4())
+        )
+
+    @abc.abstractmethod
+    async def inner_from_config(self, config: T_Config, agent_id: Optional[str] = None):
+        """Initialize the agent from the config. This is where you should put any
+        async initialization code that needs to run when the agent is created.
+        """
+        pass
+
+    @classmethod
+    async def from_config(
+        cls, config: T_Config, agent_id: Optional[str] = None
+    ) -> Self:
+        instance = cls(config=config, agent_id=agent_id)
+        await instance.inner_from_config(config, agent_id)
+        return instance
+
+    def step_title(self, description: str) -> str:
+        """Format a step title as '<agent title>: <description>'.
+
+        Uses the user-configured instance title if set, otherwise falls back to
+        the Pydantic model_config title (e.g. 'MCP', 'SQL query') which describes
+        the agent type.
+        """
+        config = self.config  # type: ignore[attr-defined]
+        title = type(config).model_config.get("title") or config.title  # type: ignore[attr-defined]
+        return f"{title}: {description}"
+
+    async def __call__(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+    ):
+        raise NotImplementedError()

hyperforge-1.0.0.post19/src/hyperforge/api/__init__.py

@@ -0,0 +1,20 @@
+import logging
+
+logger = logging.getLogger("hyperforge.api")
+
+SERVICE_NAME = "hyperforge_api"
+
+
+# Define the filter
+class EndpointFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        return (
+            record.args is not None
+            and len(record.args) >= 3
+            and record.args[2]  # type: ignore
+            not in ("/", "/metrics", "/health/alive", "/health/ready")
+        )
+
+
+# Add filter to the logger
+logging.getLogger("uvicorn.access").addFilter(EndpointFilter())

hyperforge-1.0.0.post19/src/hyperforge/api/app.py

@@ -0,0 +1,155 @@
+from typing import Any, Optional, Tuple
+
+import prometheus_client  # type: ignore
+from fastapi import APIRouter, FastAPI
+from lru import LRU
+from mcp.server.lowlevel.server import Server as MCPServer
+from mcp.server.streamable_http import (
+    StreamableHTTPServerTransport,
+)
+from nucliadb_sdk.v2.sdk import NucliaDBAsync
+from nucliadb_telemetry.logs import setup_logging
+from nucliadb_telemetry.settings import LogLevel, LogSettings
+from nucliadb_telemetry.utils import clean_telemetry, setup_telemetry
+from prometheus_client import CONTENT_TYPE_LATEST  # type: ignore
+from starlette.middleware.authentication import AuthenticationMiddleware
+from starlette.responses import PlainTextResponse
+
+from hyperforge.api import SERVICE_NAME, internal, logger, v1
+from hyperforge.api.authentication import RaoAuthenticationBackend
+from hyperforge.api.logging import set_sentry
+from hyperforge.api.settings import Settings
+from hyperforge.broker import Broker
+from hyperforge.broker.redis import RedisBroker
+from hyperforge.configure import GLOBAL_REGISTRY, load_all_configurations, scan
+from hyperforge.db.agents import AgentManager
+from hyperforge.db.settings import DataManagerSettings
+from hyperforge.feature_flag import get_flag_service
+
+router = APIRouter()
+
+
+@router.get("/metrics")
+async def serve_metrics():  # pragma: no cover
+    output = prometheus_client.exposition.generate_latest()
+    return PlainTextResponse(
+        output.decode("utf8"), headers={"Content-Type": CONTENT_TYPE_LATEST}
+    )
+
+
+@router.get("/health/ready")
+async def health_ready():
+    return {"status": "ok"}
+
+
+@router.get("/health/alive")
+async def health_alive():
+    return {"status": "ok"}
+
+
+class HTTPApplication(FastAPI):
+    agent_manager: AgentManager
+    arag_search: NucliaDBAsync
+    arag_writer: NucliaDBAsync
+    arag_reader: NucliaDBAsync
+    broker: Broker
+    extra_middlewares: Optional[list[Any]] = None
+
+    def __init__(
+        self,
+        settings: Settings,
+        data_manager_settings: DataManagerSettings,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self.settings = settings
+        self.data_manager_settings = data_manager_settings
+        self.include_router(internal.router)
+        self.include_router(v1.router)
+        self.include_router(router)
+        self.add_middleware(
+            AuthenticationMiddleware,
+            backend=RaoAuthenticationBackend(),
+        )
+        if self.extra_middlewares is not None:
+            for extra_middleware in self.extra_middlewares:
+                self.add_middleware(extra_middleware)
+        self.add_event_handler("startup", self.startup)
+        self.add_event_handler("shutdown", self.shutdown)
+
+    async def startup(self) -> None:
+        GLOBAL_REGISTRY.clear()
+        await setup_telemetry(SERVICE_NAME)
+        setup_logging(
+            settings=LogSettings(
+                debug=self.settings.debug,
+                log_level=LogLevel(self.settings.log_level),
+                logger_levels={
+                    "uvicorn.error": LogLevel.ERROR,
+                    "nucliadb_telemetry": LogLevel.ERROR,
+                    "mcp.client.streamable_http": LogLevel.WARNING,
+                    "mcp.server.lowlevel.server": LogLevel.WARNING,
+                    "hyperforge.configure": LogLevel.WARNING,
+                },
+            )
+        )
+        if self.settings.sentry_url is not None:
+            set_sentry(
+                self.settings.zone,
+                self.settings.running_environment,
+                self.settings.sentry_url,
+            )
+
+        get_flag_service()  # precache the flag service
+
+        if self.settings.memory_apikey_nucliadb is None:
+            api_key = None
+            headers = {"X-NUCLIADB-ROLES": "WRITER;READER"}
+        else:
+            api_key = self.settings.memory_apikey_nucliadb
+            headers = None
+
+        self.arag_writer = NucliaDBAsync(
+            url=self.settings.memory_writer_nucliadb,
+            api_key=api_key,
+            headers=headers,
+        )
+        self.arag_reader = NucliaDBAsync(
+            url=self.settings.memory_reader_nucliadb,
+            api_key=api_key,
+            headers=headers,
+        )
+        self.arag_search = NucliaDBAsync(
+            url=self.settings.memory_search_nucliadb,
+            api_key=api_key,
+            headers=headers,
+        )
+
+        self.broker = RedisBroker.from_url(
+            url=self.settings.valkey_url,
+            activate_subject=self.settings.activate_subject,
+            keepalive_ms=int(self.settings.pubsub_keepalive_seconds * 1000),
+            cluster_mode=self.settings.valkey_cluster_mode,
+        )
+
+        self.sses: LRU[Tuple[str, str], StreamableHTTPServerTransport] = LRU(size=100)
+        self.mcp_servers: LRU[str, MCPServer] = LRU(size=100)
+
+        self.agent_manager = await AgentManager.from_settings(
+            settings=self.data_manager_settings
+        )
+        await self.agent_manager.initialize()
+
+        for load_module in self.settings.load_modules:
+            try:
+                scan(load_module)
+                load_all_configurations(load_module)
+            except ImportError:
+                logger.error(f"Module {load_module} could not be loaded")
+
+    async def shutdown(self) -> None:
+        await self.agent_manager.finalize()
+        await self.broker.finalize()
+        await clean_telemetry(SERVICE_NAME)
+        GLOBAL_REGISTRY.clear()