PyPI - hyperforge - Versions diffs - 1.0.0.post55__tar.gz → 1.0.0.post57__tar.gz - Mend

hyperforge 1.0.0.post55tar.gz → 1.0.0.post57tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (106) hide show

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperforge
-Version: 1.0.0.post55
+Version: 1.0.0.post57
 Summary: Agentic Framework for Orchestrated Runtime, Governance, and Execution
 Author: AI Data Team
 Author-email: AI Data Team <learning@nuclia.com>

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 [project]
 name = "hyperforge"
-version = "1.0.0.post55"
+version = "1.0.0.post57"
 authors = [{ name = "AI Data Team", email = "learning@nuclia.com" }]
 description = "Agentic Framework for Orchestrated Runtime, Governance, and Execution"
 readme = "README.md"

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/api/models.py RENAMED Viewed

@@ -5,7 +5,7 @@ from nucliadb_models import TextFormat
 from pydantic import BaseModel, Field
 from hyperforge.driver import DriverConfig
-from hyperforge.models import Rules
+from hyperforge.models import HistoryQuestionAnswer, Rules
 class StashRoles(str, Enum):
@@ -125,5 +125,9 @@ class InteractionRequest(BaseModel):
     question: str
     headers: Dict[str, str] = {}
     arguments: Dict[str, str] = {}
+    chat_history: Optional[List[HistoryQuestionAnswer]] = Field(
+        default=None,
+        description="Client-managed chat history. When set (even to an empty list), overrides any server-side session history for agents that use previous Q&A context (rephrase, summarize, smart, etc.). Omit the field entirely to use server-side session history.",
+    )
     operation: InteractionOperation = InteractionOperation.QUESTION
     streaming: bool = False

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/api/v1/interaction.py RENAMED Viewed

@@ -208,6 +208,7 @@ async def stream_response(
         question=interaction.question,
         headers=interaction.headers,
         arguments=interaction.arguments,
+        chat_history=interaction.chat_history,
         workflow_id=workflow_id,
         streaming=interaction.streaming,
     )

hyperforge-1.0.0.post57/src/hyperforge/api/v1/oauth.py ADDED Viewed

@@ -0,0 +1,163 @@
+import logging
+from urllib.parse import urlencode
+from cryptography.fernet import InvalidToken
+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
+from hyperforge_mcp.http import _fingerprint, decrypt_mcp_oauth_state
+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>"
+def _build_oauth_subject(
+    settings: Settings,
+    account_id: str,
+    agent_id: str,
+    workflow_id: str,
+    session: str,
+    question_id: str,
+    oauth_uuid: str,
+) -> str:
+    return settings.oauth_subject.format(
+        account=account_id,
+        agent_id=agent_id,
+        session=session,
+        question=question_id,
+        oauth_uuid=oauth_uuid,
+        workflow_id=workflow_id,
+    )
+@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 = _build_oauth_subject(
+        settings,
+        account_id,
+        agent_id,
+        workflow_id,
+        session,
+        question_id,
+        oauth_uuid,
+    )
+    # 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)
+@router.get(
+    "/api/auth/mcp/callback",
+    status_code=200,
+    description="Generic MCP OAuth callback (fixed redirect URI, state-routed)",
+    tags=["Retrieval Agent"],
+    include_in_schema=False,
+)
+async def mcp_oauth_callback_generic(
+    request: Request,
+    code: str | None = Query(None, include_in_schema=False),
+    state: str | None = Query(None, include_in_schema=False),
+    error: str | None = Query(None, include_in_schema=False),
+    error_description: str | None = Query(None, include_in_schema=False),
+):
+    settings: Settings = request.app.settings
+    if state is None:
+        logger.warning("MCP generic OAuth callback received without state parameter")
+        return HTMLResponse(content="Missing OAuth state parameter", status_code=400)
+    try:
+        routing = decrypt_mcp_oauth_state(state)
+    except InvalidToken:
+        logger.warning(
+            "MCP generic OAuth callback: invalid or expired state (Fernet decryption failed)"
+        )
+        return HTMLResponse(content="Invalid or expired OAuth state", status_code=400)
+    sdk_state = routing.sdk_state or None
+    if sdk_state is None:
+        logger.warning(
+            "MCP generic OAuth callback: decrypted state missing sdk_state field"
+        )
+        return HTMLResponse(content="Malformed OAuth state", status_code=400)
+    subject = _build_oauth_subject(
+        settings,
+        routing.account_id,
+        routing.agent_id,
+        routing.workflow_id,
+        routing.session_id,
+        routing.question_id,
+        routing.oauth_uuid,
+    )
+    payload_data: dict[str, str] = {}
+    if code is not None:
+        payload_data["code"] = code
+    if sdk_state is not None:
+        payload_data["state"] = sdk_state
+    if error is not None:
+        payload_data["error"] = error
+    if error_description is not None:
+        payload_data["error_description"] = error_description
+    payload = urlencode(payload_data)
+    with tracer().start_as_current_span("MCP generic OAuth callback"):
+        logger.info(
+            "MCP generic OAuth callback: agent=%s workflow=%s session=%s question_id=%s oauth_uuid=%s sdk_state_fp=%s has_code=%s has_error=%s",
+            routing.agent_id,
+            routing.workflow_id,
+            routing.session_id,
+            routing.question_id,
+            routing.oauth_uuid,
+            _fingerprint(sdk_state),
+            code is not None,
+            error is not None,
+        )
+        await request.app.broker.send_reply(subject, payload)
+        logger.info("mcp_oauth send_reply: published to stream %s", subject)
+    if error is not None:
+        desc = f": {error_description}" if error_description else ""
+        return HTMLResponse(
+            content=f"OAuth authorization failed ({error}{desc})", status_code=400
+        )
+    return HTMLResponse(content=RENDER)

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/engine.py RENAMED Viewed

@@ -1,6 +1,6 @@
 import logging
 from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Dict, Optional, Tuple, cast
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple, cast
 from nuclia.lib.nua import AsyncNuaClient
@@ -9,6 +9,7 @@ from hyperforge.interaction import AragAnswer
 from hyperforge.llm import NoopNuaClient, NuaBaseModel, NUAConnection
 from hyperforge.manager import Manager
 from hyperforge.memory.memory import BaseSessionMemory, QuestionMemory, SessionMemory
+from hyperforge.models import HistoryQuestionAnswer
 from hyperforge.retrieval.agent import RetrievalAgent
 from hyperforge.retrieval.config import RetrievalAgentConfig
@@ -84,6 +85,7 @@ async def main(
     headers: Optional[Dict[str, str]] = None,
     memory_klass: type[BaseSessionMemory] = SessionMemory,
     streaming: bool = False,
+    chat_history: Optional[List[HistoryQuestionAnswer]] = None,
 ) -> QuestionMemory:
     try:
         state, session_memory = await init(
@@ -99,7 +101,9 @@ async def main(
             session_id=session_id,
             memory_klass=memory_klass,
         )
-        question_memory = session_memory.start_question(question, streaming=streaming)
+        question_memory = session_memory.start_question(
+            question, streaming=streaming, chat_history=chat_history
+        )
         if callback is not None:
             question_memory.set_callback_fn(callback)

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/interaction.py RENAMED Viewed

@@ -60,6 +60,7 @@ class Provider(Enum):
     AZURE_CERTIFICATE_CREDENTIALS = "azure_certificate_credentials"
     AWS_S3_ACCESS_KEYS = "aws_s3_access_keys"
     SHAREFILE_OAUTH = "sharefile_oauth"
+    MCP_OAUTH = "mcp_oauth"
 class OAuthAuthenticateURL(BaseModel):

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/memory/memory.py RENAMED Viewed

@@ -54,6 +54,26 @@ logger = logging.getLogger("arag.memory")
 # NucliaDB storage
 QUESTION_ANSWERS_FIELD: str = "qas"
+def _qa_list_to_context_string(history: List[HistoryQuestionAnswer]) -> Tuple[str, int]:
+    """Format a list of Q&A pairs into the prompt context string used by agents."""
+    result = "".join(
+        f"- Question: {qa.question}\n- Answer: {qa.answer}\n" for qa in history
+    )
+    return result, len(history)
+def _qa_list_to_chat_messages(history: List[HistoryQuestionAnswer]) -> List[Message]:
+    """Convert a list of Q&A pairs into the alternating User/Nuclia Message list used by LLMs."""
+    return [
+        msg
+        for qa in history
+        for msg in (
+            Message(author=Author.USER, text=qa.question),
+            Message(author=Author.NUCLIA, text=qa.answer),
+        )
+    ]
 CONTEXT_FIELD: str = "context"
 STEPS_FIELD: str = "steps"
 USER_INFO_FIELD: str = "user_info"
@@ -65,6 +85,7 @@ class BaseSessionMemory:
     agent_id: str = ""
     workflow_id: str = ""
+    account_id: str = ""
     kbid: Optional[str] = None
     # User information dictionary
@@ -112,34 +133,13 @@ class BaseSessionMemory:
         return KnowledgeboxFindResults(total=0, resources={})
     async def get_chat_history(self) -> List[Message]:
-        qas = await self.qa_history()
-        result = []
-        for qa in qas:
-            result.append(
-                Message(
-                    author=Author.USER,
-                    text=qa.question,
-                )
-            )
-            result.append(
-                Message(
-                    author=Author.NUCLIA,
-                    text=qa.answer,
-                )
-            )
-        return result
+        return _qa_list_to_chat_messages(await self.qa_history())
     async def qa_history(self) -> list[HistoryQuestionAnswer]:
         return []
     async def context_history(self) -> Tuple[str, int]:
-        result = ""
-        interactions = 0
-        for qa in await self.qa_history():
-            result += f"- Question: {qa.question}\n"
-            result += f"- Answer: {qa.answer}\n"
-            interactions += 1
-        return result, interactions
+        return _qa_list_to_context_string(await self.qa_history())
     def start_question(
         self,
@@ -149,6 +149,7 @@ class BaseSessionMemory:
         headers: Dict[str, str] = {},
         arguments: Dict[str, str] = {},
         streaming: bool = False,
+        chat_history: Optional[List[HistoryQuestionAnswer]] = None,
     ) -> "QuestionMemory":
         return QuestionMemory(
             self,
@@ -158,6 +159,7 @@ class BaseSessionMemory:
             headers=headers,
             arguments=arguments,
             streaming=streaming,
+            chat_history=chat_history,
         )
     async def save(self, question: "QuestionMemory") -> None:
@@ -183,6 +185,7 @@ class NoMemorySessionMemory(BaseSessionMemory):
         headers: Dict[str, str] = {},
         arguments: Dict[str, str] = {},
         streaming: bool = False,
+        chat_history: Optional[List[HistoryQuestionAnswer]] = None,
     ) -> "QuestionMemory":
         return QuestionMemory(
             self,
@@ -192,6 +195,7 @@ class NoMemorySessionMemory(BaseSessionMemory):
             headers=headers,
             arguments=arguments,
             streaming=streaming,
+            chat_history=chat_history,
         )
     async def save(self, question: "QuestionMemory") -> None:
@@ -250,6 +254,7 @@ class EphemeralSessionMemory(BaseSessionMemory):
         headers: Dict[str, str] = {},
         arguments: Dict[str, str] = {},
         streaming: bool = False,
+        chat_history: Optional[List[HistoryQuestionAnswer]] = None,
     ) -> "QuestionMemory":
         return QuestionMemory(
             self,
@@ -259,6 +264,7 @@ class EphemeralSessionMemory(BaseSessionMemory):
             headers=headers,
             arguments=arguments,
             streaming=streaming,
+            chat_history=chat_history,
         )
     async def save(self, question: "QuestionMemory") -> None:
@@ -580,10 +586,21 @@ class QuestionMemory:
         headers: Dict[str, str] | None = None,
         arguments: Dict[str, str] | None = None,
         streaming: bool = False,
+        chat_history: Optional[List[HistoryQuestionAnswer]] = None,
     ):
         self.session = session
         self.started_at = datetime.now(timezone.utc)
+        # Client-managed chat history. When set (even to an empty list), overrides
+        # server-side session history for agents that use previous Q&A context
+        # (rephrase, summarize, smart, etc.). None means "not set — use server-side
+        # history". [] means "override with no history". Intended for ephemeral
+        # sessions where the client is responsible for maintaining conversation state.
+        # Note: search_in_questions() performs semantic search over NucliaDB-stored
+        # conversation history and is NOT affected by this field. The HistoricalAgent
+        # uses that method and therefore does not benefit from client-managed history.
+        self._client_chat_history: Optional[List[HistoryQuestionAnswer]] = chat_history
         # Start of a new question by the user
         self.original_question = question
         if actions is not None:
@@ -622,6 +639,10 @@ class QuestionMemory:
         """Returns the workflow ID for the current question. The workflow ID is a unique identifier that is shared across all questions and interactions that belong to the same workflow. This can be used to group related interactions together, and to keep track of the conversation history in a coherent way."""
         return self.session.workflow_id
+    def get_account_id(self) -> str:
+        """Returns the account ID for the current question."""
+        return self.session.account_id
     def context_user_info(self) -> str:
         """Returns a string with user information that can be used in the context of the agent. This can include information such as user preferences, user history, or any other relevant information about the user that can help the agent to generate a more personalized and accurate response."""
         return self.session.context_user_info()
@@ -649,11 +670,19 @@ class QuestionMemory:
         return await self.session.get_source(source_id)
     async def context_history(self) -> Tuple[str, int]:
-        """Returns a string with the context history of the conversation. This can include information such as previous questions and answers, relevant information that has been previously discussed in the conversation, or any other relevant information that can help the agent to generate a more accurate and personalized response."""
+        """Returns a string with the context history of the conversation. This can include information such as previous questions and answers, relevant information that has been previously discussed in the conversation, or any other relevant information that can help the agent to generate a more accurate and personalized response.
+        When the client sets chat_history in the request (even to an empty list), it overrides any server-side session history. None means "not set — use server-side history"."""
+        if self._client_chat_history is not None:
+            return _qa_list_to_context_string(self._client_chat_history)
         return await self.session.context_history()
     async def get_chat_history(self) -> list[Message]:
-        """Returns a list of tuples with the chat history of the conversation. Each tuple contains a question and an answer. This can be used to keep track of the conversation history in a more structured way, and to provide more context to the agent when generating a response."""
+        """Returns a list of tuples with the chat history of the conversation. Each tuple contains a question and an answer. This can be used to keep track of the conversation history in a more structured way, and to provide more context to the agent when generating a response.
+        When the client sets chat_history in the request (even to an empty list), it overrides any server-side session history. None means "not set — use server-side history"."""
+        if self._client_chat_history is not None:
+            return _qa_list_to_chat_messages(self._client_chat_history)
         return await self.session.get_chat_history()
     def stats(self):

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/pubsub.py RENAMED Viewed

@@ -1,4 +1,4 @@
-from typing import Annotated, Dict, Literal
+from typing import Annotated, Dict, List, Literal, Optional
 from pydantic import AliasChoices, BaseModel, Field
 from pydantic.types import Discriminator, Tag
@@ -8,6 +8,7 @@ from hyperforge.interaction import (
     Feedback,
     OAuthAuthenticateURL,
 )
+from hyperforge.models import HistoryQuestionAnswer
 # Messages used in the pubsub protocol between API and agent servers
@@ -22,6 +23,10 @@ class StartInteraction(BaseModel):
     question: str
     headers: Dict[str, str] = {}
     arguments: Dict[str, str] = {}
+    chat_history: Optional[List[HistoryQuestionAnswer]] = Field(
+        default=None,
+        description="Client-managed chat history. When set (even to an empty list), overrides any server-side session history for agents that use previous Q&A context. Omit the field entirely to use server-side session history.",
+    )
     workflow_id: str = "default"
     streaming: bool = False
     op: Literal["start"] = "start"

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/server/session.py RENAMED Viewed

@@ -181,8 +181,12 @@ class SessionManager:
                     config=config.memory,
                     agent=message.agent_id,
                     workflow_id=message.workflow_id,
+                    account_id=message.account,
                 )
-                self.memory[message.session] = memory
+                # Ephemeral sessions are short-lived and should not be persisted in
+                # the shared LRU cache across activations.
+                if message.session != "ephemeral":
+                    self.memory[message.session] = memory
             else:
                 memory = self.memory[message.session]
@@ -194,6 +198,7 @@ class SessionManager:
                 headers=message.headers,
                 arguments=message.arguments,
                 streaming=message.streaming,
+                chat_history=message.chat_history,
             )
             task = asyncio.create_task(

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/server/utils.py RENAMED Viewed

@@ -16,6 +16,7 @@ async def get_memory(
     config: MemoryConfig,
     agent: str,
     workflow_id: str,
+    account_id: str = "",
 ) -> BaseSessionMemory:
     memory: BaseSessionMemory
@@ -53,5 +54,6 @@ async def get_memory(
         )
     memory.init(session=session)
+    memory.account_id = account_id
     return memory

{hyperforge-1.0.0.post55 → hyperforge-1.0.0.post57}/src/hyperforge/settings.py RENAMED Viewed

@@ -2,17 +2,23 @@ from pydantic import model_validator
 from pydantic_settings import BaseSettings
 _REDIRECT_PATH = "/api/auth/agent/{agent_id}/workflow/{workflow_id}/session/{session_id}/oauth/{oauth_uuid}/callback"
+_MCP_CALLBACK_PATH = "/api/auth/mcp/callback"
 class OAuthSettings(BaseSettings):
     nuclia_public_url: str = "https://{zone}.nuclia.com"
     nuclia_zone: str = "arag"
     rao_redirect_url: str = ""
+    mcp_callback_url: str = ""
     @model_validator(mode="after")
     def _resolve_urls(self) -> "OAuthSettings":
         self.nuclia_public_url = self.nuclia_public_url.format(zone=self.nuclia_zone)
         if not self.rao_redirect_url:
             self.rao_redirect_url = self.nuclia_public_url.rstrip("/") + _REDIRECT_PATH
+        if not self.mcp_callback_url:
+            self.mcp_callback_url = (
+                self.nuclia_public_url.rstrip("/") + _MCP_CALLBACK_PATH
+            )
         return self

hyperforge-1.0.0.post55/src/hyperforge/api/v1/oauth.py DELETED Viewed

@@ -1,60 +0,0 @@
-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)