hyperforge 1.0.0.post19__py3-none-any.whl

hyperforge/api/v1/mcp_content.py

@@ -0,0 +1,311 @@
+"""MCP content conversion utilities.
+
+Converts AragAnswer and generic Python objects into MCP content blocks
+(TextContent, ImageContent, EmbeddedResource) suitable for returning from
+tool calls.
+"""
+
+import json
+from itertools import chain
+from typing import Any, Sequence
+
+import pydantic_core
+from mcp.server.fastmcp.utilities.types import Image
+from mcp.types import (
+    Annotations,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+    TextResourceContents,
+)
+
+from hyperforge.interaction import AragAnswer
+from hyperforge.models import Answer, Chunk
+
+
+def _answer_obj_to_content(
+    answer: Answer,
+) -> list[TextContent | ImageContent | EmbeddedResource]:
+    """Convert a hyperforge Answer object to MCP content blocks.
+
+    Handles all fields that Answer can carry: text, citations, chunks,
+    structured items, images, image_urls, and visualizations.
+    """
+    contents: list[TextContent | ImageContent | EmbeddedResource] = []
+
+    if answer.answer:
+        contents.append(TextContent(type="text", text=answer.answer))
+
+    if answer.citations and answer.citations.metadata:
+        citations_json = json.dumps(pydantic_core.to_jsonable_python(answer.citations))
+        contents.append(
+            EmbeddedResource(
+                type="resource",
+                resource=TextResourceContents(
+                    uri="rao-response://answer/citations",  # type: ignore[arg-type]
+                    text=citations_json,
+                    mimeType="application/json",
+                ),
+            )
+        )
+
+    if answer.chunks:
+        for idx, chunk in enumerate(answer.chunks):
+            if chunk:
+                # Extract text from Chunk object or use string directly
+                chunk_text = chunk.text if isinstance(chunk, Chunk) else chunk
+                if chunk_text:
+                    contents.append(
+                        EmbeddedResource(
+                            type="resource",
+                            resource=TextResourceContents(
+                                uri=f"rao-response://answer/chunk/{idx}",  # type: ignore[arg-type]
+                                text=chunk_text,
+                                mimeType="text/plain",
+                            ),
+                        )
+                    )
+
+    if answer.structured:
+        for idx, item in enumerate(answer.structured):
+            if item:
+                contents.append(
+                    EmbeddedResource(
+                        type="resource",
+                        resource=TextResourceContents(
+                            uri=f"rao-response://answer/structured/{idx}",  # type: ignore[arg-type]
+                            text=item,
+                            mimeType="text/plain",
+                        ),
+                    )
+                )
+
+    if answer.images:
+        for image in answer.images.values():
+            contents.append(
+                ImageContent(
+                    type="image",
+                    data=image.b64encoded,
+                    mimeType=image.content_type,
+                )
+            )
+
+    if answer.image_urls:
+        contents.append(
+            EmbeddedResource(
+                type="resource",
+                resource=TextResourceContents(
+                    uri="rao-response://answer/image-urls",  # type: ignore[arg-type]
+                    text=json.dumps(answer.image_urls),
+                    mimeType="application/json",
+                ),
+            )
+        )
+
+    if answer.data_visualizations:
+        for idx, viz in enumerate(answer.data_visualizations):
+            contents.append(
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=f"rao-response://answer/visualization/{idx}",  # type: ignore[arg-type]
+                        text=json.dumps(
+                            pydantic_core.to_jsonable_python(viz.vega_lite_obj)
+                        ),
+                        mimeType="application/vnd.vegalite.v5+json",
+                    ),
+                )
+            )
+
+    return contents
+
+
+def convert_arag_answer_to_content(
+    msg: AragAnswer,
+) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
+    """Convert an AragAnswer to a sequence of MCP content objects.
+
+    Parses **every** populated field independently — the same AragAnswer
+    message never carries all fields at once, but any combination is safe.
+
+    Emits (in order):
+    - possible_answer content (text, citations, chunks, structured, images,
+      image_urls, visualizations) via _answer_obj_to_content
+    - TextContent for the main answer text
+    - EmbeddedResource (application/json) for top-level citations
+    - EmbeddedResource (application/json) for answer URLs
+    - EmbeddedResource (text/plain) per context chunk, with metadata
+    - ImageContent per base64 image in the context
+    - EmbeddedResource (text/plain) per structured item in the context
+    - EmbeddedResource (application/json) for context image URLs
+    - EmbeddedResource (application/vnd.vegalite.v5+json) per visualization
+    - TextContent (assistant-only annotation) for the step, if present
+    - TextContent for exception detail, if present
+    """
+    contents: list[TextContent | ImageContent | EmbeddedResource] = []
+
+    # --- Possible answer (emitted by add_answer callbacks during generation) ---
+    if msg.possible_answer:
+        contents.extend(_answer_obj_to_content(msg.possible_answer))
+
+    # --- Main answer text (emitted by send_final_answer / session.py) ---
+    if msg.answer:
+        contents.append(TextContent(type="text", text=msg.answer))
+
+    # --- Top-level citations (from send_final_answer / session.py) ---
+    if msg.answer_citations and msg.answer_citations.metadata:
+        citations_json = json.dumps(
+            pydantic_core.to_jsonable_python(msg.answer_citations)
+        )
+        contents.append(
+            EmbeddedResource(
+                type="resource",
+                resource=TextResourceContents(
+                    uri="rao-response://citations",  # type: ignore[arg-type]
+                    text=citations_json,
+                    mimeType="application/json",
+                ),
+            )
+        )
+
+    # --- Answer URLs ---
+    if msg.answer_urls:
+        contents.append(
+            EmbeddedResource(
+                type="resource",
+                resource=TextResourceContents(
+                    uri="rao-response://answer-urls",  # type: ignore[arg-type]
+                    text=json.dumps(msg.answer_urls),
+                    mimeType="application/json",
+                ),
+            )
+        )
+
+    # --- Context chunks and images (emitted by save_context callbacks) ---
+    if msg.context:
+        context = msg.context
+        for chunk in context.chunks:
+            meta: dict[str, Any] = {}
+            if chunk.title:
+                meta["title"] = chunk.title
+            if chunk.source:
+                meta["source"] = chunk.source
+            if chunk.labels:
+                meta["labels"] = chunk.labels
+            if chunk.origin_url:
+                meta["origin_url"] = chunk.origin_url
+            if chunk.url:
+                meta["url"] = chunk.url
+            contents.append(
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=f"rao-response://context/{context.id}/chunk/{chunk.chunk_id}",  # type: ignore[arg-type]
+                        text=chunk.text,
+                        mimeType="text/plain",
+                        **{"_meta": meta} if meta else {},
+                    ),
+                )
+            )
+
+        for image in context.images.values():
+            contents.append(
+                ImageContent(
+                    type="image",
+                    data=image.b64encoded,
+                    mimeType=image.content_type,
+                )
+            )
+
+        for idx, structured in enumerate(context.structured):
+            contents.append(
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=f"rao-response://context/{context.id}/structured/{idx}",  # type: ignore[arg-type]
+                        text=structured,
+                        mimeType="text/plain",
+                    ),
+                )
+            )
+
+        if context.image_urls:
+            contents.append(
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=f"rao-response://context/{context.id}/image-urls",  # type: ignore[arg-type]
+                        text=json.dumps(context.image_urls),
+                        mimeType="application/json",
+                    ),
+                )
+            )
+
+    # --- Top-level visualizations (from session.py final answer) ---
+    if msg.data_visualizations:
+        for idx, viz in enumerate(msg.data_visualizations):
+            contents.append(
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=f"rao-response://visualization/{idx}",  # type: ignore[arg-type]
+                        text=json.dumps(
+                            pydantic_core.to_jsonable_python(viz.vega_lite_obj)
+                        ),
+                        mimeType="application/vnd.vegalite.v5+json",
+                    ),
+                )
+            )
+
+    # --- Step (assistant-only, not shown to user) ---
+    if msg.step:
+        step = msg.step
+        parts = [f"Step: {step.title}"]
+        if step.value:
+            parts.append(f"Value: {step.value}")
+        if step.reason:
+            parts.append(f"Reason: {step.reason}")
+        if step.error:
+            parts.append(f"Error: {step.error}")
+        contents.append(
+            TextContent(
+                type="text",
+                text="\n".join(parts),
+                annotations=Annotations(audience=["assistant"]),
+            )
+        )
+
+    # --- Exception ---
+    if msg.exception:
+        contents.append(TextContent(type="text", text=f"Error: {msg.exception.detail}"))
+
+    return contents
+
+
+def convert_to_content(
+    result: Any,
+) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
+    """Convert a generic result to a sequence of MCP content objects.
+
+    Handles MCP content types directly, Image objects, lists/tuples
+    (recursively), and serialises everything else as JSON text.
+    """
+    if result is None:
+        return []
+
+    if isinstance(result, (TextContent, ImageContent, EmbeddedResource)):
+        return [result]
+
+    if isinstance(result, Image):
+        return [result.to_image_content()]
+
+    if isinstance(result, (list, tuple)):
+        return list(chain.from_iterable(convert_to_content(item) for item in result))
+
+    if not isinstance(result, str):
+        try:
+            result = json.dumps(pydantic_core.to_jsonable_python(result))
+        except Exception:
+            result = str(result)
+
+    return [TextContent(type="text", text=result)]

hyperforge/api/v1/mcp_interaction.py

@@ -0,0 +1,322 @@
+import asyncio
+from collections.abc import MutableMapping
+from functools import partial
+from typing import TYPE_CHECKING, Any, Iterable, Sequence
+
+import anyio
+from fastapi import Header
+from mcp.server.fastmcp.exceptions import ResourceError
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+from mcp.server.lowlevel.server import Server as MCPServer
+from mcp.server.lowlevel.server import lifespan as default_lifespan
+from mcp.server.streamable_http import (
+    MCP_SESSION_ID_HEADER,
+    StreamableHTTPServerTransport,
+)
+from mcp.server.transport_security import TransportSecuritySettings
+from mcp.types import (
+    EmbeddedResource,
+    GetPromptResult,
+    ImageContent,
+    Prompt,
+    PromptMessage,
+    Resource,
+    ResourceTemplate,
+    TextContent,
+    Tool,
+)
+from nucliadb_sdk import NucliaDBAsync
+from pydantic import AnyUrl
+from starlette.datastructures import Headers
+from starlette.requests import Request
+from starlette.responses import Response
+
+from hyperforge.api.authentication import requires_one
+from hyperforge.api.models import InteractionRequest
+from hyperforge.api.v1.interaction import WebsocketReceiver, stream_response
+from hyperforge.db.agents import AgentManager
+from hyperforge.interaction import AnswerOperation
+from hyperforge.prompts import PromptConfig
+from hyperforge.pubsub import UserToAgentInteraction
+from hyperforge.workflows import WorkflowData
+
+if TYPE_CHECKING:
+    from hyperforge.api.app import HTTPApplication
+from anyio.abc import TaskStatus
+
+from hyperforge.api import logger
+from hyperforge.api.models import (
+    AgentRole,
+)
+from hyperforge.api.v1.mcp_content import convert_arag_answer_to_content
+from hyperforge.api.v1.router import router
+
+
+async def list_tools(workflows: list[WorkflowData]) -> list[Tool]:
+    return [
+        Tool(
+            name=workflow.name,
+            description=workflow.description,
+            inputSchema={
+                "type": "object",
+                "required": workflow.required,
+                "properties": workflow.parameters,
+            },
+        )
+        for workflow in workflows
+    ]
+
+
+async def list_prompts(prompts: list[PromptConfig]) -> list[Prompt]:
+    """List all available prompts."""
+    return [Prompt(**prompt.model_dump()) for prompt in prompts]
+
+
+async def call_tool(
+    app: "HTTPApplication",
+    mcp_server: MCPServer,
+    x_stf_account: str,
+    agent_id: str,
+    session: str,
+    workflows: list[WorkflowData],
+    headers: Headers,
+    name: str,
+    arguments: dict[str, Any],
+) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
+    """Call a tool by name with arguments."""
+    workflow = next((w for w in workflows if w.name == name), None)
+    if workflow is None:
+        raise ResourceError(f"Unknown tool: {name}")
+
+    for parameter in workflow.required:
+        if parameter not in arguments:
+            raise ResourceError(f"Missing required parameter: {parameter}")
+
+    question = f"Calling tool: {workflow.description or workflow.name} with arguments: {arguments}"
+
+    interaction = InteractionRequest(
+        question=question, headers=dict(headers.items()), arguments=arguments
+    )
+    mcp_session = mcp_server.request_context.session
+    websocket = WebsocketReceiver(websocket=None)
+
+    messages = []
+    async for msg in stream_response(
+        app,
+        websocket,
+        account=x_stf_account,
+        agent_id=agent_id,
+        session=session,
+        interaction=interaction,
+        workflow_id=workflow.id,
+    ):
+        if msg.operation == AnswerOperation.AGENT_REQUEST and msg.oauth:
+            pass
+        elif msg.operation == AnswerOperation.AGENT_REQUEST and msg.feedback:
+            # DO NOTHING FOR NOW
+            result = await mcp_session.elicit_form(
+                message=msg.feedback.question,
+                requestedSchema=msg.feedback.response_schema,
+                related_request_id=msg.feedback.request_id,
+            )
+            websocket.queue.put_nowait(
+                UserToAgentInteraction(
+                    request_id=msg.feedback.request_id, response=result.content
+                )
+            )
+        elif msg.operation == AnswerOperation.ANSWER:
+            result_contents = convert_arag_answer_to_content(msg)
+            for content in result_contents:
+                if isinstance(content, TextContent):
+                    logger.debug(f"Tool output text: {content.text}")
+                messages.append(content)
+
+    return messages
+
+
+async def list_resources(agent_id: str) -> list[Resource]:
+    # TODO : Resource 1 : The list of tools ??
+    return []
+
+
+async def list_resource_templates() -> list[ResourceTemplate]:
+    return []
+
+
+async def get_prompt(
+    prompts_list: list[PromptConfig], name: str, arguments: dict[str, Any] | None = None
+) -> GetPromptResult:
+    """Get a prompt by name with arguments."""
+    prompt = next((p for p in prompts_list if p.name == name), None)
+    if prompt is None:
+        raise ResourceError(f"Unknown prompt: {name}")
+    message = prompt.prompt.format(**(arguments or {}))
+    return GetPromptResult(
+        description=prompt.description,
+        messages=[
+            PromptMessage(role="user", content=TextContent(type="text", text=message))
+        ],
+    )
+
+
+async def read_resource(
+    ndb: NucliaDBAsync, kbid: str, uri: AnyUrl | str
+) -> Iterable[ReadResourceContents]:
+    """Read a resource by URI."""
+
+    raise ResourceError(f"Unknown uri: {uri}")
+
+
+@router.get(
+    "/.well-known/oauth-protected-resource/api/v1/agent/{agent_id}/session/{session}/mcp"
+)
+async def mcp_interaction_protected_resource_metadata(
+    request: Request,
+    agent_id: str,
+    session: str,
+):
+    """
+    Protected resource metadata discovery endpoint for MCP server authorization.
+    See https://datatracker.ietf.org/doc/html/rfc9728 for details on the OAuth-protected resource metadata format and discovery process.
+    """
+    app: "HTTPApplication" = request.app
+    mcp_url = request.url_for(
+        "interaction_mcp_handler", agent_id=agent_id, session=session
+    )
+    mcp_url_https = str(mcp_url).replace(
+        "http://", "https://"
+    )  # Ensure the URL uses https
+    return {
+        "resource": mcp_url_https,
+        "scopes_supported": app.settings.hydra_scopes_supported,
+        "authorization_servers": [app.settings.hydra_public_url],
+    }
+
+
+@router.delete("/api/v1/agent/{agent_id}/session/{session}/mcp")
+@requires_one([AgentRole.MEMBER])
+async def mcp_handler_delete(
+    request: Request,
+    agent_id: str,
+    session: str,
+    x_stf_user: str = Header(..., include_in_schema=False),
+    x_stf_account: str = Header(..., include_in_schema=False),
+    x_stf_account_type: str = Header(..., include_in_schema=False),
+):
+    app: HTTPApplication = request.app
+    if (agent_id, session) in app.sses:
+        await app.sses[(agent_id, session)].terminate()
+    if (agent_id, session) in app.sses:
+        del app.sses[(agent_id, session)]
+
+
+@router.get("/api/v1/agent/{agent_id}/session/{session}/mcp")
+@router.post("/api/v1/agent/{agent_id}/session/{session}/mcp")
+@requires_one([AgentRole.MEMBER])
+async def interaction_mcp_handler(
+    request: Request,
+    agent_id: str,
+    session: str,
+    x_stf_user: str = Header(..., include_in_schema=False),
+    x_stf_account: str = Header(..., include_in_schema=False),
+    x_stf_account_type: str = Header(..., include_in_schema=False),
+):
+    app: HTTPApplication = request.app
+    agent_manager: AgentManager = request.app.agent_manager
+    request._headers._list.append((MCP_SESSION_ID_HEADER.encode(), session.encode()))
+
+    # No session ID needed in stateless mode
+    security_settings: TransportSecuritySettings | None = None
+    http_transport = StreamableHTTPServerTransport(
+        mcp_session_id=session,  # No session tracking in stateless mode
+        is_json_response_enabled=True,
+        event_store=None,  # No event store in stateless mode
+        security_settings=security_settings,
+    )
+
+    workflows, agent_config, prompts = await asyncio.gather(
+        agent_manager.workflows_list(account=x_stf_account, agent_id=agent_id),
+        agent_manager.get_agent_config_basic(account=x_stf_account, agent_id=agent_id),
+        agent_manager.get_prompts(account=x_stf_account, agent_id=agent_id),
+    )
+
+    mcp_server = MCPServer(
+        name=agent_id,
+        version="1.0.0",
+        instructions=agent_config.instructions,
+        lifespan=default_lifespan,
+    )
+
+    list_tools_partial = partial(list_tools, workflows)
+    mcp_server.list_tools()(list_tools_partial)
+
+    call_tool_partial = partial(
+        call_tool,
+        app,
+        mcp_server,
+        x_stf_account,
+        agent_id,
+        session,
+        workflows,
+        request.headers,
+    )
+    mcp_server.call_tool()(call_tool_partial)
+
+    list_prompts_partial = partial(list_prompts, prompts=prompts)
+    mcp_server.list_prompts()(list_prompts_partial)
+
+    get_prompt_partial = partial(get_prompt, prompts)
+    mcp_server.get_prompt()(get_prompt_partial)
+
+    # Start server in a new task
+    async def run_stateless_server(
+        *, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORED
+    ):
+        async with http_transport.connect() as streams:
+            read_stream, write_stream = streams
+            task_status.started()
+            try:
+                await mcp_server.run(
+                    read_stream,
+                    write_stream,
+                    mcp_server.create_initialization_options(),
+                    stateless=True,
+                )
+            except Exception:
+                logger.exception("Stateless session crashed")
+
+    # Intercept ASGI send messages so FastAPI doesn't attempt to send a
+    # second response after the transport has already sent one (which would
+    # cause: RuntimeError: Unexpected ASGI message 'http.response.start'
+    # sent, after response already completed).
+    response_status = 200
+    response_headers: dict[str, str] = {}
+    body_chunks: list[bytes] = []
+
+    async def intercepting_send(message: MutableMapping[str, Any]) -> None:
+        nonlocal response_status
+        if message["type"] == "http.response.start":
+            response_status = message["status"]
+            response_headers.update(
+                {k.decode(): v.decode() for k, v in message.get("headers", [])}
+            )
+        elif message["type"] == "http.response.body":
+            body_chunks.append(message.get("body", b""))
+
+    async with anyio.create_task_group() as tg:
+        # Start the server task
+        await tg.start(run_stateless_server)
+
+        # Handle the HTTP request via the intercepting send
+        await http_transport.handle_request(
+            request.scope, request._receive, intercepting_send
+        )
+
+        # Terminate the transport after the request is handled
+        await http_transport.terminate()
+
+    return Response(
+        content=b"".join(body_chunks),
+        status_code=response_status,
+        headers=response_headers,
+    )

hyperforge/api/v1/oauth.py

@@ -0,0 +1,60 @@
+import logging
+
+from fastapi import Query
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+
+from hyperforge.api.settings import Settings
+from hyperforge.api.v1.router import router
+from hyperforge.api.v1.utils import tracer
+
+logger = logging.getLogger(__name__)
+
+RENDER = "<html><body><h1>OAuth Completed</h1><p>You can close this window and return to the application.</p></body></html>"
+
+
+@router.get(
+    "/api/auth/agent/{agent_id}/workflow/{workflow_id}/session/{session}/oauth/{oauth_uuid}/callback",
+    status_code=200,
+    description="Get Agent Schema",
+    tags=["Retrieval Agent"],
+    include_in_schema=False,
+)
+async def oauth_callback(
+    request: Request,
+    agent_id: str,
+    session: str,
+    workflow_id: str,
+    oauth_uuid: str,
+    question_id: str = Query(..., include_in_schema=False),
+    state: str = Query(..., include_in_schema=False),
+    account_id: str = Query(..., include_in_schema=False),
+):
+    """
+    Callback from oauth flow on RAO that requires to send creds to websocket
+    """
+    settings: Settings = request.app.settings
+    subject = settings.oauth_subject.format(
+        account=account_id,
+        agent_id=agent_id,
+        session=session,
+        question=question_id,
+        oauth_uuid=oauth_uuid,
+        workflow_id=workflow_id,
+    )
+    # Request a question
+    with tracer().start_as_current_span("Request activation"):
+        logger.info(
+            "OAuth callback received for agent=%s, session=%s, oauth_uuid=%s, question_id=%s",
+            agent_id,
+            session,
+            oauth_uuid,
+            question_id,
+        )
+        await request.app.broker.send_reply(subject, state)
+        logger.info(
+            "OAuth callback published to stream %s",
+            subject,
+        )
+
+    return HTMLResponse(content=RENDER)