hyperforge 1.0.0.post19__py3-none-any.whl

hyperforge/standalone/settings.py

@@ -0,0 +1,133 @@
+"""
+Runtime settings for the standalone arag deployment.
+
+All values can be supplied via:
+  - Environment variables (prefixed with ARAG_, e.g. ARAG_EXTERNAL_NUA_API_KEY)
+  - A .env file
+  - CLI arguments when using the pydantic-settings CLI integration
+
+The agent pipeline definition (drivers, workflows, etc.) lives separately in
+a JSON config file pointed to by ``agents_config``.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from pydantic import AliasChoices, Field
+from pydantic_settings import BaseSettings
+
+
+class StandaloneSettings(BaseSettings):
+    # ------------------------------------------------------------------
+    # Agent config file
+    # ------------------------------------------------------------------
+
+    agents_config: Path = Field(
+        default=Path("agents_config.yaml"),
+        description="Path to the JSON file containing agent definitions.",
+    )
+
+    # ------------------------------------------------------------------
+    # HTTP server
+    # ------------------------------------------------------------------
+
+    host: str = Field(default="0.0.0.0", description="Listen host.")
+    port: int = Field(default=8080, description="Listen port.")
+    log_level: str = Field(default="INFO", description="Log level (uvicorn + app).")
+    debug: bool = Field(default=False, description="Enable debug mode.")
+
+    # ------------------------------------------------------------------
+    # Agent runner
+    # ------------------------------------------------------------------
+
+    question_timeout_seconds: int = Field(
+        default=300,
+        description="Maximum seconds allowed to answer a single question.",
+    )
+    pubsub_keepalive_seconds: float = Field(
+        default=20,
+        description="Interval between keepalive pings on the answer stream.",
+    )
+    broker_redis_dsn: Optional[str] = Field(
+        default=None,
+        description=(
+            "Redis DSN for the Pub/Sub broker. If not set, an in-memory broker is used, "
+            "which is not suitable for production but fine for local testing and development."
+        ),
+    )
+    broker_redis_activate_subject: str = Field(
+        default="arag:activations",
+        description="Redis stream subject for agent activations (only used if broker_redis_dsn is set).",
+    )
+    broker_redis_cluster_mode: bool = Field(
+        default=False,
+        description="Whether to use Redis Cluster mode (only used if broker_redis_dsn is set).",
+    )
+
+    # ------------------------------------------------------------------
+    # NUA / predict engine
+    # ------------------------------------------------------------------
+
+    external_nua_api_key: Optional[str] = Field(
+        default=None,
+        description=(
+            "NUA API key from https://nuclia.cloud/user/keys. "
+            "Required unless internal_nua=true or local_openai is set."
+        ),
+        # also allow external_nua_api_key and nua_api_key
+        # for backward compatibility with older env var names
+        validation_alias=AliasChoices(
+            "EXTERNAL_NUA_API_KEY",
+            "external_nua_api_key",
+            "NUA_API_KEY",
+            "nua_api_key",
+        ),
+    )
+    internal_nua: bool = Field(
+        default=False,
+        description="Connect to an internal NUA service instead of nuclia.cloud.",
+    )
+    internal_nua_api: str = Field(
+        default="http://predict.learning.svc.cluster.local:8080",
+        description="Internal NUA service address (only used when internal_nua=true).",
+    )
+    local_openai: Optional[str] = Field(
+        default=None,
+        description=(
+            "Base URL of a local OpenAI-compatible inference server "
+            "(e.g. http://localhost:11434/v1). "
+            "When set, requests are routed there instead of nuclia.cloud."
+        ),
+    )
+
+    in_memory_cache_size: int = 3000
+
+    cors_allow_origin: list[str] = Field(
+        default_factory=lambda: ["*"],
+        description=(
+            "List of allowed origins for CORS. Defaults to ['*'] which allows all origins. "
+            "In production, it's recommended to set this to the specific origins that should be allowed."
+        ),
+    )
+
+    load_modules: list[str] = []
+    # ------------------------------------------------------------------
+    # Pluggable module classes
+    # ------------------------------------------------------------------
+
+    session_cache_class: str | None = Field(
+        default=None,
+        description="Dotted-name of the session cache class to use.",
+    )
+    session_cache_size: int = Field(
+        default=3000,
+        description="Size of the session cache when using a custom session cache class.",
+    )
+    agent_manager_class: str = Field(
+        default="hyperforge.standalone.agent.StaticAgentManager",
+        description="Dotted-name of the AgentManager class to use.",
+    )
+    standalone_application_class: str = Field(
+        default="hyperforge.standalone.app.StandaloneApplication",
+        description="Dotted-name of the StandaloneApplication class to use.",
+    )

hyperforge/standalone/ui_router.py

@@ -0,0 +1,241 @@
+"""
+UI API router for the standalone ARAG deployment.
+
+Provides endpoints consumed exclusively by the built-in frontend:
+  GET  /api/v1/ui/schema   — all registered agent/driver schemas
+  GET  /api/v1/ui/config   — current in-memory agent config (full JSON)
+  PUT  /api/v1/ui/config   — replace config, persist to AGENTS_CONFIG file
+  GET  /api/v1/ui/models   — list of known model IDs for model_select widget
+
+No authentication is required (the OpenAuthBackend already grants all roles
+in standalone mode, and the UI is local-only by design).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import yaml
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from hyperforge.standalone.config import StandaloneConfig
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Schema — expose the registered agent/driver registry so the UI can build
+# the "add agent" palette and the config form for each agent type.
+# ---------------------------------------------------------------------------
+
+
+# Properties that link to other agents (subagents). The frontend renders these
+# as edges/child nodes on the canvas instead of inline form fields.
+CONNECTABLE_KEYS: list[str] = [
+    "fallback",
+    "next_agent",
+    "then",
+    "else_",
+    "agents",
+    "registered_agents",
+]
+
+
+def _merge_defs(target: dict[str, Any], source: dict[str, Any]) -> None:
+    """Merge `source["$defs"]` into target without overwriting existing keys."""
+    defs = source.get("$defs") or {}
+    for name, schema in defs.items():
+        target.setdefault(name, schema)
+
+
+def _module_to_def_name(config_schema: dict[str, Any]) -> str | None:
+    """Return the $defs key name for an agent config schema (= its `title`)."""
+    return config_schema.get("title")
+
+
+@router.get("/api/v1/ui/schema", response_class=JSONResponse)
+async def get_schema() -> dict[str, Any]:
+    """Return all registered agent and driver schemas plus a merged $defs map.
+
+    Payload shape:
+        {
+          "preprocess": { module_id: AgentSchema, ... },
+          "context":    { ... },
+          "generation": { ... },
+          "postprocess":{ ... },
+          "drivers":    { provider_id: DriverSchema, ... },
+          "$defs":      { ClassName: JsonSchema, ... },   # merged from all agents
+          "connectable_keys": [...],
+          "agent_module_to_def": { module_id: ClassName, ... }
+        }
+    """
+    from hyperforge.configure import (
+        get_context_agent_schemas,
+        get_driver_agent_schemas,
+        get_generation_agent_schemas,
+        get_postprocess_agent_schemas,
+        get_preprocess_agent_schemas,
+    )
+
+    stages = {
+        "preprocess": get_preprocess_agent_schemas(),
+        "context": get_context_agent_schemas(),
+        "generation": get_generation_agent_schemas(),
+        "postprocess": get_postprocess_agent_schemas(),
+    }
+    drivers = get_driver_agent_schemas()
+
+    # Merge all $defs into a single top-level map so the frontend can resolve
+    # `$ref: "#/$defs/<ClassName>"` across stages/drivers.
+    merged_defs: dict[str, Any] = {}
+    agent_module_to_def: dict[str, str] = {}
+
+    for stage_agents in stages.values():
+        for module_id, agent_schema in stage_agents.items():
+            cfg = agent_schema.get("config_schema") or {}
+            _merge_defs(merged_defs, cfg)
+            # The top-level config schema itself is also exposed under $defs so
+            # nested oneOf/discriminator chains can resolve it.
+            def_name = _module_to_def_name(cfg)
+            if def_name:
+                merged_defs.setdefault(def_name, cfg)
+                agent_module_to_def[module_id] = def_name
+
+    for driver_schema in drivers.values():
+        cfg = driver_schema.get("config_schema") or {}
+        _merge_defs(merged_defs, cfg)
+
+    return {
+        **stages,
+        "drivers": drivers,
+        "$defs": merged_defs,
+        "connectable_keys": CONNECTABLE_KEYS,
+        "agent_module_to_def": agent_module_to_def,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Config — read / write the full agent config
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/v1/ui/config", response_class=JSONResponse)
+async def get_config(request: Request) -> dict[str, Any]:
+    """Return the current in-memory config as a JSON-serialisable dict."""
+    agent_manager = request.app.agent_manager
+    return {
+        agent_id: agent_cfg.model_dump(mode="json")
+        for agent_id, agent_cfg in agent_manager._config.items()
+    }
+
+
+@router.put("/api/v1/ui/config", response_class=JSONResponse)
+async def put_config(request: Request) -> dict[str, Any]:
+    """
+    Replace the in-memory config and persist it to the config file on disk.
+
+    The request body must be a JSON object whose structure matches the
+    standalone config format (same as AGENTS_CONFIG).
+    """
+    try:
+        body = await request.json()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid JSON: {exc}") from exc
+
+    # Validate through the Pydantic model so we get clear error messages.
+    try:
+        new_config = StandaloneConfig.validate_python(body)
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    # Update the live in-memory config.
+    agent_manager = request.app.agent_manager
+    agent_manager._config = new_config
+
+    # Persist to disk so the change survives a restart.
+    settings = request.app._standalone_settings
+    config_path = settings.agents_config
+    try:
+        serialised = {
+            agent_id: agent_cfg.model_dump(mode="json")
+            for agent_id, agent_cfg in new_config.items()
+        }
+        if config_path.suffix in (".yaml", ".yml"):
+            config_path.write_text(yaml.dump(serialised, allow_unicode=True))
+        else:
+            config_path.write_text(json.dumps(serialised, indent=2, ensure_ascii=False))
+        logger.info("Config persisted to %s", config_path)
+    except Exception as exc:
+        # Non-fatal — in-memory update already succeeded.
+        logger.warning("Could not persist config to %s: %s", config_path, exc)
+
+    return {"status": "ok", "agents": list(new_config.keys())}
+
+
+# ---------------------------------------------------------------------------
+# Models — return a list of known model IDs for the model_select widget.
+# Collects defaults from all registered agent config schemas where the field
+# carries widget="model_select", then merges with a hard-coded baseline list.
+# ---------------------------------------------------------------------------
+
+_BASELINE_MODELS: list[str] = [
+    "chatgpt-azure-4o-mini",
+    "chatgpt-azure-4o",
+    "chatgpt4o",
+    "chatgpt-4.1",
+    "chatgpt-5",
+    "chatgpt-o3-mini",
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+    "gemini-3-flash-preview",
+    "claude-4-5-haiku",
+    "claude-4-5-sonnet",
+    "gcp-claude-4-5-haiku",
+    "gcp-claude-4-5-sonnet",
+]
+
+
+def _collect_model_defaults() -> list[str]:
+    """Walk all agent config schemas and harvest model field defaults."""
+    from hyperforge.configure import (
+        get_context_agent_schemas,
+        get_driver_agent_schemas,
+        get_generation_agent_schemas,
+        get_postprocess_agent_schemas,
+        get_preprocess_agent_schemas,
+    )
+
+    seen: set[str] = set(_BASELINE_MODELS)
+
+    all_schemas = [
+        *get_preprocess_agent_schemas().values(),
+        *get_context_agent_schemas().values(),
+        *get_generation_agent_schemas().values(),
+        *get_postprocess_agent_schemas().values(),
+        *get_driver_agent_schemas().values(),
+    ]
+
+    for agent_schema in all_schemas:
+        config_schema = agent_schema.get("config_schema", {})
+        for _field_name, field_schema in config_schema.get("properties", {}).items():
+            if field_schema.get("widget") == "model_select":
+                default = field_schema.get("default")
+                if isinstance(default, str) and default:
+                    seen.add(default)
+
+    # Return baseline first (preserves a sensible order), then extras
+    result = list(_BASELINE_MODELS)
+    for m in sorted(seen - set(_BASELINE_MODELS)):
+        result.append(m)
+    return result
+
+
+@router.get("/api/v1/ui/models", response_class=JSONResponse)
+async def get_models() -> list[str]:
+    """Return a sorted list of known model IDs for the model_select widget."""
+    return _collect_model_defaults()

hyperforge/trace.py

@@ -0,0 +1,42 @@
+import functools
+import os
+
+import nucliadb_telemetry
+import nucliadb_telemetry.metrics
+from nucliadb_telemetry.utils import get_telemetry
+from opentelemetry import trace
+
+SERVICE_NAME = os.environ.get("RAO_SERVICE_NAME", "hyperforge")
+
+
+def tracer(service_name: str = SERVICE_NAME):
+    provider = get_telemetry(service_name)
+    if provider:
+        return provider.get_tracer(__name__)
+    else:
+        return trace.NoOpTracer()
+
+
+agent_observer = nucliadb_telemetry.metrics.Observer(
+    "hyperforge_agent", labels={"agent": ""}
+)
+
+
+# Decorator to trace agent executions
+def trace_agent(func):
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        self = args[0]
+        agent_name = f"{self.__class__.__name__}.{func.__name__}"
+        try:
+            attributes = {"agent_id": self.config.id}
+        except:
+            attributes = {}
+
+        with (
+            tracer().start_as_current_span(agent_name, attributes=attributes),
+            agent_observer({"agent": agent_name}),
+        ):
+            return await func(*args, **kwargs)
+
+    return wrapper

hyperforge/utils/__init__.py

@@ -0,0 +1,112 @@
+import ipaddress
+import socket
+import urllib.parse
+from collections.abc import Iterable
+from enum import Enum
+from typing import Any, Dict, Optional, Tuple
+
+import aiodns
+from nuclia_models.predict.generative_responses import GenerativeFullResponse
+
+
+def iterate_tools_resp(
+    resp: GenerativeFullResponse,
+) -> Iterable[Tuple[str, Dict[str, Any]]]:
+    if resp.tools is not None:
+        for _, tools_calls in resp.tools.items():
+            for tool in tools_calls:
+                if tool.function.name:
+                    used_params = tool.function.arguments
+                    yield tool.function.name, used_params
+
+
+def sync_check_dns(url: str) -> Optional[str]:
+    parsed_url = urllib.parse.urlparse(url)
+    error = None
+    try:
+        if parsed_url.hostname is None:
+            hostname = parsed_url.path
+        else:
+            hostname = parsed_url.hostname
+        addr = socket.gethostbyname_ex(hostname)
+        for addres in addr[2]:
+            if ipaddress.ip_address(addres).is_private:
+                error = "Its a private address"
+    except aiodns.error.DNSError:
+        error = "Could not find this URL"
+    return error
+
+
+def sync_dns_validation(url: str) -> str:
+    error = sync_check_dns(url)
+    if error is not None:
+        raise ValueError(error)
+    return url
+
+
+async def check_dns(url: str) -> str:
+    parsed_url = urllib.parse.urlparse(url)
+    resolver = aiodns.DNSResolver()
+    error = None
+    try:
+        if parsed_url.hostname is None:
+            hostname = parsed_url.path
+        else:
+            hostname = parsed_url.hostname
+        addr = await resolver.gethostbyname(hostname, socket.AF_INET)
+        for addres in addr.addresses:
+            if ipaddress.ip_address(addres).is_private:
+                error = "Its a private address"
+    except aiodns.error.DNSError:
+        error = "Could not find this URL"
+
+    if error is not None:
+        raise ValueError(error)
+    return url
+
+
+class WidgetType(str, Enum):
+    """
+    Enumeration of available widget types for form field rendering.
+    These correspond to the frontend component mappings.
+    """
+
+    # Model and AI-related widgets
+    MODEL_SELECT = "model_select"
+    """Dropdown selector for AI models (LLM, embedding, etc.)"""
+
+    # Driver and source selection widgets
+    DRIVER_SELECT = "driver_select"
+    """Selector for data source drivers (databases, APIs, etc.)"""
+
+    FILTERED_SOURCE_SELECT = "filtered_source_select"
+    """Source selector with filtering capabilities based on transport type"""
+
+    # Code and text input widgets
+    CODE_EDITOR = "code_editor"
+    """Code editor with syntax highlighting, supports multiple languages"""
+
+    EXPANDABLE_TEXTAREA = "expandable_textarea"
+    """Multi-line text input that can expand/resize"""
+
+    # Specialized field widgets
+    TRANSPORT_FIELD = "transport_field"
+    """Selector for transport/protocol types (HTTP, gRPC, etc.)"""
+
+    RULES_FIELD = "rules_field"
+    """Complex rules configuration interface"""
+
+    KEY_VALUE_FIELD = "key_value_field"
+    """Key-value pairs input (like environment variables)"""
+
+    # Basic form widgets
+    ARRAY_STRING_FIELD = "array_string_field"
+    """Input for arrays of string values"""
+
+    ENUM_SELECT = "enum_select"
+    """Dropdown for predefined enumeration values"""
+
+    # Extra for RAO
+
+    NOT_SHOWN = "not_show"
+    """Field is not shown in the node config UI"""

hyperforge/utils/http.py

@@ -0,0 +1,48 @@
+import ipaddress
+import socket
+
+import aiodns
+from httpx import AsyncClient, AsyncHTTPTransport
+
+
+class PrivateUrlError(Exception):
+    pass
+
+
+class SafeTransport(AsyncHTTPTransport):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    @staticmethod
+    async def is_private_address(hostname: str) -> bool:
+        resolver = aiodns.DNSResolver()
+        addr = await resolver.gethostbyname(hostname, socket.AF_INET)
+        for address in addr.addresses:
+            if ipaddress.ip_address(address).is_private:
+                return True
+            if (
+                not ipaddress.ip_address(address).is_private
+                and not ipaddress.ip_address(address).is_global
+            ):
+                # Matches shared address space (100.64.0.0/10 range) that should be non-routeable and
+                # not be used for public internet. Let's consider it internal
+                return True
+        return False
+
+    async def handle_async_request(self, request):
+        url = request.url
+        try:
+            hostname = url.host if url.host is not None else url.path
+            if await self.is_private_address(hostname):
+                raise PrivateUrlError("Cannot access private network resources")
+        except aiodns.error.DNSError:
+            raise PrivateUrlError("Could not lookup hostname")
+
+        return await super().handle_async_request(request)
+
+
+def safe_http_client(timeout=30, transport_verify: bool = True):
+    return AsyncClient(
+        timeout=timeout,
+        transport=SafeTransport(verify=transport_verify),
+    )

hyperforge/workflows.py

@@ -0,0 +1,44 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from hyperforge.models import Rules
+
+
+class WorkflowData(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    id: str
+    name: str
+    description: str | None
+    parameters: dict[str, Any] | None
+    rules: Rules | None = Field(default_factory=Rules)
+    required: list[str] = Field(default_factory=list)
+
+
+class WorkflowInput(BaseModel):
+    id: str
+    name: str
+    description: str | None = None
+    parameters: dict[str, Any] | None = None
+    rules: Rules = Field(default_factory=Rules)
+    required: list[str] = Field(default_factory=list)
+
+
+class WorkflowUpdate(BaseModel):
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    required: list[str] = Field(default_factory=list)
+    rules: Rules | None = Field(default_factory=Rules)
+
+
+class RetrievalAgent(BaseModel):
+    account: str
+    agent_id: str
+    memory: dict[str, Any] | None = None
+    description: str | None = None
+    title: str | None = None
+    instructions: str | None = None
+    created: datetime
+    modified: datetime | None = None