hyperforge 1.0.0.post19__py3-none-any.whl

hyperforge/standalone/agent.py

@@ -0,0 +1,189 @@
+"""
+StaticAgentManager — a drop-in replacement for AgentManager that serves agent
+configuration from an in-memory StandaloneConfig rather than a PostgreSQL database.
+
+Only the methods actually called at runtime (by SessionManager and the MCP/interaction
+endpoints) are implemented.  Management mutations (add/delete/patch) intentionally
+raise NotImplementedError — the standalone deployment is read-only with respect to
+agent configuration.
+"""
+
+import datetime
+from typing import Any, List
+
+from hyperforge.db import exceptions
+from hyperforge.models import MemoryConfig, Rules
+from hyperforge.prompts import PromptConfig
+from hyperforge.retrieval.config import RetrievalAgentConfig
+from hyperforge.standalone.config import StandAloneAgentConfig
+from hyperforge.workflows import RetrievalAgent, WorkflowData
+
+_EPOCH = datetime.datetime.now()
+
+
+class StaticAgentManager:
+    _config: dict[str, StandAloneAgentConfig]
+
+    def __init__(self, config: dict[str, StandAloneAgentConfig]) -> None:
+        self._config = config
+
+    # ------------------------------------------------------------------
+    # Lifecycle (no-ops — nothing to connect/disconnect)
+    # ------------------------------------------------------------------
+
+    async def initialize(self) -> None:
+        pass
+
+    async def finalize(self) -> None:
+        pass
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_agent(self, agent_id: str) -> StandAloneAgentConfig:
+        agent_config = self._config.get(agent_id)
+        if not agent_config:
+            raise exceptions.NotFoundError(f"Agent '{agent_id}' not found")
+        return agent_config
+
+    async def ensure_workflow_active(
+        self, account: str, agent_id: str, workflow_id: str
+    ) -> None:
+        agent_config = self._get_agent(agent_id)
+        if workflow_id not in agent_config.workflows:
+            raise exceptions.NotFoundError("Workflow not found")
+
+    def _build_retrieval_config(
+        self, agent_config: StandAloneAgentConfig, workflow_id: str = "default"
+    ) -> RetrievalAgentConfig:
+        """Merge StandAloneAgentConfig + WorkflowConfig into a RetrievalAgentConfig."""
+        workflow = agent_config.workflows.get(workflow_id)
+        if workflow is None:
+            raise exceptions.NotFoundError(
+                f"Workflow '{workflow_id}' not found in agent"
+            )
+        workflow_data = workflow.as_workflow_data(workflow_id)
+        # Merge agent-level rules with workflow-level rules (workflow takes precedence).
+        merged_rules = workflow.rules if workflow.rules.rules else agent_config.rules
+        return RetrievalAgentConfig(
+            drivers=agent_config.drivers,
+            rules=merged_rules,
+            memory=MemoryConfig(),
+            workflow=workflow_data,
+            preprocess=workflow.preprocess,
+            context=workflow.context,
+            generation=workflow.generation,
+            postprocess=workflow.postprocess,
+        )
+
+    # ------------------------------------------------------------------
+    # Methods used by SessionManager (session.py)
+    # ------------------------------------------------------------------
+
+    async def get_driver(self, account: str, agent_id: str, driver: str) -> Any:
+        agent_config = self._get_agent(agent_id)
+        for drv in agent_config.drivers:
+            if drv.identifier == driver:
+                return drv
+        raise exceptions.NotFoundError(
+            f"Driver '{driver}' not found in agent '{agent_id}'"
+        )
+
+    async def get_drivers(self, account: str, agent_id: str) -> List[Any]:
+        agent_config = self._get_agent(agent_id)
+        return list(agent_config.drivers)
+
+    async def workflows_list(self, account: str, agent_id: str) -> List[WorkflowData]:
+        agent_config = self._get_agent(agent_id)
+        return [
+            workflow.as_workflow_data(workflow_id)
+            for workflow_id, workflow in agent_config.workflows.items()
+        ]
+
+    async def get_agent_config_basic(
+        self, account: str, agent_id: str
+    ) -> RetrievalAgent:
+        agent_config = self._get_agent(agent_id)
+        # Use the default workflow for description/title fallbacks.
+        default_workflow = agent_config.workflows.get("default")
+        description = agent_config.description or (
+            default_workflow.description if default_workflow else None
+        )
+        title = agent_config.title or agent_id
+        return RetrievalAgent(
+            account=account,
+            agent_id=agent_id,
+            memory=None,
+            description=description,
+            title=title,
+            instructions=agent_config.instructions,
+            created=_EPOCH,
+            modified=_EPOCH,
+        )
+
+    async def get_agent_config(
+        self,
+        account: str,
+        agent_id: str,
+        internal_nucliadb_url: str | None = None,
+        default_memory: bool = False,
+        workflow_id: str = "default",
+    ) -> RetrievalAgentConfig:
+        agent_config = self._get_agent(agent_id)
+        return self._build_retrieval_config(agent_config, workflow_id)
+
+    async def get_prompt(
+        self, agent_id: str, account: str, prompt_id: str
+    ) -> PromptConfig:
+        agent_config = self._get_agent(agent_id)
+        for prompt in agent_config.prompts:
+            if prompt.prompt_id == prompt_id:
+                return prompt
+        raise exceptions.NotFoundError(
+            f"Prompt '{prompt_id}' not found in agent '{agent_id}'"
+        )
+
+    async def get_prompts(self, agent_id: str, account: str) -> List[PromptConfig]:
+        agent_config = self._get_agent(agent_id)
+        return list(agent_config.prompts)
+
+    async def get_rules(self, account: str, agent_id: str) -> Rules:
+        agent_config = self._get_agent(agent_id)
+        return agent_config.rules
+
+    async def get_preprocess(
+        self, account: str, agent_id: str, workflow_id: str = "default"
+    ) -> list:
+        agent_config = self._get_agent(agent_id)
+        workflow = agent_config.workflows.get(workflow_id)
+        if workflow is None:
+            return []
+        return workflow.preprocess or []
+
+    async def get_context(
+        self, account: str, agent_id: str, workflow_id: str = "default"
+    ) -> list:
+        agent_config = self._get_agent(agent_id)
+        workflow = agent_config.workflows.get(workflow_id)
+        if workflow is None:
+            return []
+        return workflow.context or []
+
+    async def get_generation(
+        self, account: str, agent_id: str, workflow_id: str = "default"
+    ) -> list:
+        agent_config = self._get_agent(agent_id)
+        workflow = agent_config.workflows.get(workflow_id)
+        if workflow is None:
+            return []
+        return workflow.generation or []
+
+    async def get_postprocess(
+        self, account: str, agent_id: str, workflow_id: str = "default"
+    ) -> list:
+        agent_config = self._get_agent(agent_id)
+        workflow = agent_config.workflows.get(workflow_id)
+        if workflow is None:
+            return []
+        return workflow.postprocess or []

hyperforge/standalone/app.py

@@ -0,0 +1,264 @@
+"""
+Standalone application.
+
+Runs the API (HTTP + MCP) and the agent runner (SessionManager) in the same
+process, connected via a LocalBroker.  No Redis, no gRPC, no PostgreSQL, no
+NucliaDB required.
+"""
+
+from pathlib import Path
+from typing import Any, Tuple
+
+import prometheus_client  # type: ignore
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from lru import LRU
+from mcp.server.lowlevel.server import Server as MCPServer
+from mcp.server.streamable_http import StreamableHTTPServerTransport
+from nucliadb_telemetry.logs import setup_logging
+from nucliadb_telemetry.settings import LogLevel, LogSettings
+from prometheus_client import CONTENT_TYPE_LATEST  # type: ignore
+from redis.asyncio import Redis
+from starlette.authentication import AuthCredentials, AuthenticationBackend, BaseUser
+from starlette.middleware.authentication import AuthenticationMiddleware
+from starlette.requests import HTTPConnection
+from starlette.responses import PlainTextResponse
+
+from hyperforge.api import v1
+from hyperforge.api.authentication import User
+from hyperforge.api.models import AgentRole, StashRoles
+from hyperforge.api.v1 import oauth as v1_oauth
+from hyperforge.broker import Broker
+from hyperforge.broker.local import LocalBroker
+from hyperforge.broker.redis import RedisBroker
+from hyperforge.configure import resolve_dotted_name
+from hyperforge.server.cache import InMemoryCache, ValkeyCache
+from hyperforge.server.session import SessionManager
+from hyperforge.server.settings import Settings as ServerSettings
+from hyperforge.standalone.settings import StandaloneSettings
+from hyperforge.standalone.ui_router import router as ui_router
+
+from .const import STANDALONE_ACCOUNT
+
+# ---------------------------------------------------------------------------
+# SessionManager subclass that skips the aiohttp health-check server started
+# by the base class — the FastAPI app already exposes /health/ready and
+# /health/alive.
+# ---------------------------------------------------------------------------
+
+
+class StandaloneSessionManager(SessionManager):
+    """SessionManager without the embedded aiohttp metrics/health server."""
+
+    async def initialize(self, health_check: bool = False) -> None:
+        await super().initialize(health_check=health_check)
+
+
+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"}
+
+
+# ---------------------------------------------------------------------------
+# Open authentication backend — grants every request all roles so that the
+# existing @requires_one decorators on interaction and MCP endpoints pass
+# without an external authoriser.
+# ---------------------------------------------------------------------------
+
+_ALL_ROLES = AuthCredentials(
+    [
+        AgentRole.MEMBER,
+        StashRoles.OWNER,
+        StashRoles.MEMBER,
+        StashRoles.CONTRIBUTOR,
+        "READER",
+        "WRITER",
+        "MANAGER",
+    ]
+)
+
+
+class OpenAuthBackend(AuthenticationBackend):
+    """Authentication backend that accepts every request as a local user with
+    all roles.  Only used in the standalone single-process deployment."""
+
+    async def authenticate(
+        self, conn: HTTPConnection
+    ) -> tuple[AuthCredentials, BaseUser] | None:
+        # Inject the headers that interaction endpoints declare as required
+        # FastAPI Header() dependencies, so they don't get rejected.
+        if "x-stf-account" not in conn.headers:
+            conn.scope["headers"] = [
+                (b"x-stf-account", STANDALONE_ACCOUNT.encode()),
+                (b"x-stf-user", b"standalone"),
+                (b"x-stf-account-type", b"v3starter"),
+                *[
+                    (k, v)
+                    for k, v in conn.scope["headers"]
+                    if k
+                    not in (
+                        b"x-stf-account",
+                        b"x-stf-user",
+                        b"x-stf-account-type",
+                    )
+                ],
+            ]
+        return _ALL_ROLES, User(username="standalone")
+
+
+# ---------------------------------------------------------------------------
+# Application
+# ---------------------------------------------------------------------------
+
+
+class StandaloneApplication(FastAPI):
+    """Single-process arag: API + SessionManager sharing one LocalBroker."""
+
+    def __init__(
+        self,
+        agents_cfg: dict[str, Any],
+        settings: StandaloneSettings,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            title="arag standalone",
+            description="Single-process agent RAG — interaction and MCP only",
+            **kwargs,
+        )
+        self._agents_cfg = agents_cfg
+        self._standalone_settings = settings
+
+        # Only the interaction and MCP routes — no management endpoints.
+        self.include_router(v1.interaction.router)
+        self.include_router(v1.mcp_interaction.router)
+        self.include_router(v1_oauth.router)
+        self.include_router(router)
+        self.include_router(ui_router)
+
+        # Serve the built frontend SPA if the dist directory exists.
+        # In development the Vite dev server runs separately (proxied to :8080).
+        # app.py lives at: arag/src/hyperforge.standalone/app.py
+        # three .parent steps → arag/
+        _frontend_dist = Path(__file__).parent.parent.parent / "frontend" / "dist"
+        if _frontend_dist.is_dir():
+            self.mount(
+                "/",
+                StaticFiles(directory=str(_frontend_dist), html=True),
+                name="frontend",
+            )
+
+        self.add_middleware(AuthenticationMiddleware, backend=OpenAuthBackend())
+        self.add_middleware(
+            CORSMiddleware,
+            allow_credentials=True,
+            allow_origins=settings.cors_allow_origin,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        self.add_event_handler("startup", self._startup)
+        self.add_event_handler("shutdown", self._shutdown)
+
+    # ------------------------------------------------------------------
+    # Property used by interaction.py / oauth.py to read answers_subject
+    # and oauth_subject without knowing about StandaloneSettings.
+    # ------------------------------------------------------------------
+
+    @property
+    def settings(self) -> ServerSettings:
+        return self._server_settings
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def _startup(self) -> None:
+        s = self._standalone_settings
+
+        setup_logging(
+            settings=LogSettings(
+                debug=s.debug,
+                log_level=LogLevel(s.log_level),
+                logger_levels={
+                    "uvicorn.error": LogLevel.ERROR,
+                    "mcp.client.streamable_http": LogLevel.WARNING,
+                    "mcp.server.lowlevel.server": LogLevel.WARNING,
+                    "hyperforge.configure": LogLevel.WARNING,
+                },
+            )
+        )
+
+        if s.broker_redis_dsn is None:
+            # Shared in-process broker — no Redis needed.
+            self.broker: Broker = LocalBroker(
+                keepalive_ms=int(s.pubsub_keepalive_seconds * 1000)
+            )
+        else:
+            self.broker = RedisBroker.from_url(
+                s.broker_redis_dsn,
+                s.broker_redis_activate_subject,
+                int(s.pubsub_keepalive_seconds * 1000),
+                cluster_mode=s.broker_redis_cluster_mode,
+            )
+
+        # LRU caches for MCP server instances (mirrors HTTPApplication).
+        self.sses: LRU[Tuple[str, str], StreamableHTTPServerTransport] = LRU(size=100)
+        self.mcp_servers: LRU[str, MCPServer] = LRU(size=100)
+
+        # Agent manager backed by the JSON config — no PostgreSQL.
+        agent_manager_class = resolve_dotted_name(s.agent_manager_class)
+        self.agent_manager: Any = agent_manager_class(self._agents_cfg)
+
+        # Build a ServerSettings instance so SessionManager and the subject
+        # format strings work unchanged.  Redis settings are present but
+        # never used (LocalBroker is injected directly).
+        self._server_settings = ServerSettings(
+            valkey_url="redis://localhost",
+            question_timeout_seconds=s.question_timeout_seconds,
+            pubsub_keepalive_seconds=s.pubsub_keepalive_seconds,
+            internal_nua=s.internal_nua,
+            internal_nua_api=s.internal_nua_api,
+            external_nua_api_key=s.external_nua_api_key,
+            local_openai=s.local_openai,
+            internal_nucliadb=False,
+            internal_nucliadb_url=None,
+            standalone=True,
+        )
+
+        # use redis as cache backend if provided
+        cache: ValkeyCache | InMemoryCache
+        if s.session_cache_class is not None:
+            cache_class = resolve_dotted_name(s.session_cache_class)
+            cache = cache_class(s.session_cache_size)
+        elif s.broker_redis_dsn is not None:
+            redis_client: Redis = Redis.from_url(s.broker_redis_dsn)  # type: ignore[arg-type]
+            cache = ValkeyCache(redis_client)
+        else:
+            cache = InMemoryCache(s.in_memory_cache_size)
+        self.session_manager: SessionManager = StandaloneSessionManager(
+            settings=self._server_settings,
+            broker=self.broker,
+            agent_manager=self.agent_manager,
+            cache=cache,
+        )
+        await self.session_manager.initialize()
+
+    async def _shutdown(self) -> None:
+        await self.session_manager.finalize()

hyperforge/standalone/config.py

@@ -0,0 +1,137 @@
+"""
+Standalone agent configuration.
+
+A single JSON file describing one or more agents.  Runtime settings (NUA key,
+HTTP host/port, log level, …) live in StandaloneSettings and are loaded from
+environment variables or the command line — not from this file.
+
+The top-level keys become the agent_id values used in API paths
+(``/api/v1/agent/{agent_id}/...``).  The account is always ``"local"`` in
+standalone mode.
+
+Minimal valid example
+---------------------
+{
+    "my-agent": {
+        "workflows": {
+            "default": {
+                "name": "Default",
+                "context": [
+                    {"module": "google", "title": "Google Search", "source": "google-01"}
+                ],
+                "generation": [
+                    {"module": "summarize"}
+                ]
+            }
+        },
+        "drivers": [
+            {
+                "identifier": "google-01",
+                "name": "google",
+                "provider": "google",
+                "config": {"vertexai": false, "api_key": "..."}
+            }
+        ]
+    }
+}
+"""
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field, TypeAdapter, field_serializer, field_validator
+
+from hyperforge.agent import AgentConfig
+from hyperforge.configure import get_agent_config_klass, get_driver_config_klass
+from hyperforge.driver import DriverConfig
+from hyperforge.models import Rules
+from hyperforge.prompts import PromptConfig
+from hyperforge.workflows import WorkflowData
+
+
+class WorkflowConfig(BaseModel):
+    """Pipeline steps for a single named workflow."""
+
+    name: str = "default"
+    description: Optional[str] = None
+    parameters: Optional[dict[str, Any]] = None
+    required: list[str] = Field(default_factory=list)
+    rules: Rules = Field(default_factory=Rules)
+
+    preprocess: list = Field(default_factory=list)
+    context: list = Field(default_factory=list)
+    generation: list = Field(default_factory=list)
+    postprocess: list = Field(default_factory=list)
+
+    def as_workflow_data(self, workflow_id: str) -> WorkflowData:
+        return WorkflowData(
+            id=workflow_id,
+            name=self.name,
+            description=self.description,
+            parameters=self.parameters,
+            rules=self.rules,
+            required=self.required,
+        )
+
+    @field_validator(
+        "preprocess", "context", "generation", "postprocess", mode="before"
+    )
+    def validate_agents(cls, value: list[Dict[str, Any]], field):
+        if len(value) == 0:
+            return []
+        if all([isinstance(agent, AgentConfig) for agent in value]):
+            return value
+        result = []
+        for agent_config in value:
+            module = agent_config["module"]
+            agent_klass = get_agent_config_klass(module)
+            result.append(agent_klass.model_validate(agent_config))
+
+        return result
+
+    @field_serializer("preprocess", "context", "generation", "postprocess")
+    def serialize_agents(self, agents: list[AgentConfig]) -> list[Dict[str, Any]]:
+        return [agent.model_dump() for agent in agents]
+
+
+class StandAloneAgentConfig(BaseModel):
+    """Configuration for a single agent instance."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    instructions: Optional[str] = None
+
+    # Drivers (LLM providers, search connectors, …) shared across all workflows.
+    # Use DriverConfig[Any] so the generic `config` field preserves arbitrary dicts.
+    drivers: list[DriverConfig[Any]] = Field(default_factory=list)
+
+    # Top-level rules applied to all workflows.
+    rules: Rules = Field(default_factory=Rules)
+
+    # Named workflows. A "default" entry is required for the default workflow.
+    workflows: dict[str, WorkflowConfig] = Field(default_factory=dict)
+
+    # Prompts exposed via the MCP server.
+    prompts: list[PromptConfig] = Field(default_factory=list)
+
+    @field_validator("drivers", mode="before")
+    def validate_drivers(cls, value: list[Dict[str, Any]], field):
+        if len(value) == 0:
+            return []
+        if all([isinstance(agent, DriverConfig) for agent in value]):
+            return value
+        result = []
+        for agent_config in value:
+            module = agent_config["provider"]
+            agent_klass = get_driver_config_klass(module)
+            result.append(agent_klass.model_validate(agent_config))
+
+        return result
+
+    @field_serializer("drivers")
+    def serialize_drivers(self, agents: list[DriverConfig]) -> list[Dict[str, Any]]:
+        return [agent.model_dump() for agent in agents]
+
+
+# The config file is a plain JSON object whose keys are agent IDs.
+# Use StandaloneConfig.validate_json(path.read_text()) to load it.
+StandaloneConfig = TypeAdapter(dict[str, StandAloneAgentConfig])

hyperforge/standalone/const.py

@@ -0,0 +1 @@
+STANDALONE_ACCOUNT = "local"

hyperforge/standalone/run.py

@@ -0,0 +1,60 @@
+import sys
+
+import uvicorn
+import yaml
+from hyperforge_standalone import logger
+from hyperforge_standalone.app import StandaloneApplication
+from hyperforge_standalone.config import StandAloneAgentConfig, StandaloneConfig
+from hyperforge_standalone.settings import StandaloneSettings
+
+from hyperforge.configure import resolve_dotted_name
+
+
+def run(
+    application_class: type[StandaloneApplication] | None = None,
+) -> None:  # pragma: no cover
+    settings: StandaloneSettings = StandaloneSettings()  # type: ignore[call-arg]
+
+    if not settings.agents_config.exists():
+        print(
+            f"error: agents config file not found: {settings.agents_config}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    from hyperforge.configure import load_all_configurations, scan
+
+    # Register all built-in agents and drivers (same as the base initialize,
+    # but without start_health_check() — the FastAPI app handles /health/*).
+    scan("nuclia_agents.agents.agents")
+    scan("nuclia_agents.drivers.drivers")
+    load_all_configurations("nuclia_agents")
+
+    for load_module in settings.load_modules:
+        try:
+            scan(load_module)
+            load_all_configurations(load_module)
+        except ImportError:
+            logger.error(f"Module {load_module} could not be loaded")
+
+    if settings.agents_config.suffix == ".yaml":
+        agents_cfg: dict[str, StandAloneAgentConfig] = StandaloneConfig.validate_python(
+            yaml.safe_load(settings.agents_config.read_text())
+        )
+    else:
+        agents_cfg = StandaloneConfig.validate_json(settings.agents_config.read_text())
+
+    if application_class is None:
+        application_class = resolve_dotted_name(settings.standalone_application_class)
+    app = application_class(agents_cfg, settings)
+
+    uvicorn.run(
+        app,
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    run()