hyperforge-restart 1.0.0.post19__tar.gz

hyperforge_restart-1.0.0.post19/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: hyperforge_restart
+Version: 1.0.0.post19
+Summary: Restart Hyperforge agent
+Author-email: Nuclia <nucliadb@nuclia.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://progress.com
+Project-URL: Repository, https://github.com/nuclia/forge
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hyperforge
+
+# Rephrase Hyperforge agents

hyperforge_restart-1.0.0.post19/README.md

@@ -0,0 +1 @@
+# Rephrase Hyperforge agents

hyperforge_restart-1.0.0.post19/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperforge_restart"
+version = "1.0.0.post19"
+license = "Apache-2.0"
+description = "Restart Hyperforge agent"
+authors = [{ name = "Nuclia", email = "nucliadb@nuclia.com" }]
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10, <4"
+dependencies = ["hyperforge"]
+
+[dependency-groups]
+# these dependencies are actually in the src/ folder (under
+# src/nucliadb_utils/tests/), but only used when the module is imported
+dev = [
+    "pytest",
+    "pytest-benchmark",
+    "pytest-docker-fixtures>=1.4.2",
+    "pytest-lazy-fixtures",
+]
+
+[project.urls]
+Homepage = "https://progress.com"
+Repository = "https://github.com/nuclia/forge"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

hyperforge_restart-1.0.0.post19/setup.cfg

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

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

@@ -0,0 +1,118 @@
+from time import time
+
+from hyperforge.agent import Agent
+from hyperforge.exceptions import MaxRetries
+from hyperforge.manager import Manager
+from hyperforge.memory import QuestionMemory
+from hyperforge.trace import trace_agent
+
+from hyperforge_restart.config import RestartAgentConfig
+from hyperforge import PROMPT_ENVIRONMENT, logger
+
+REPHRASE_PROMPT = """
+You are an expert assistant helping to answer complex questions using the provided context and any partial answers already available.
+Your goal is to identify only the missing information needed to fully answer the main question.
+
+Instructions:
+1. Carefully review the main question and the context, which may include partial answers or relevant details.
+2. If the main question is not fully answered by the context, generate only the specific sub-questions or clarifications needed to obtain the missing information.
+3. Briefly explain why each new question is necessary.
+4. If the context is sufficient to answer the main question, simply state that no additional questions are needed. Fill the questions list with an empty string. And answer true in the answered parameter.
+Be concise and focus on actionable, relevant questions that address only the gaps in information.
+
+# Main Question:
+{{question}}
+
+#Context (may include partial answers or supporting information):
+{{context}}
+"""
+JSON_SCHEMA = {
+    "title": "questions",
+    "description": (
+        "An object containing a list of specific sub-questions or clarifications needed "
+        "to fully answer the main question, and a brief explanation for each. "
+        "Focus only on actionable, relevant questions that address gaps in information."
+    ),
+    "type": "object",
+    "properties": {
+        "questions": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "description": "A concise, actionable sub-question or clarification needed to fill a gap in the answer.",
+            },
+            "description": "List of missing sub-questions or clarifications required to fully answer the main question.",
+        },
+        "reason": {
+            "type": "string",
+            "description": "A brief explanation of why these questions are necessary to complete the answer.",
+        },
+        "answered": {
+            "type": "boolean",
+            "description": "Indicates whether the main question can be answered with the provided context.",
+        },
+    },
+    "required": ["questions"],
+}
+
+REPHRASE_PROMPT_TEMPLATE = PROMPT_ENVIRONMENT.from_string(REPHRASE_PROMPT)
+
+
+class RestartAgent(Agent[RestartAgentConfig]):
+    @trace_agent
+    async def __call__(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+    ):
+        # check how many restart options
+
+        retry = 0
+        for step in memory.steps:
+            if step.module == "restart":
+                retry += 1
+
+        question = memory.original_question
+
+        prompt = REPHRASE_PROMPT_TEMPLATE.render(
+            context=memory.contexts_minimal(), question=question
+        )
+        t0 = time()
+        # Ask the LLM to define which information is needed to answer.
+        information, input, output = await manager.execute_json(
+            model=self.config.model,
+            user_id="rephrase",
+            prompt=prompt,
+            schema=JSON_SCHEMA,
+            tracking=memory.get_tracking_info(),
+        )
+
+        # retrieve all paragraphs and ask to rephrase on the NUA API
+        new_questions = information.get("questions", [])
+        reason = information.get("reason", [])
+        answered = information.get("answered", False)
+
+        if retry >= self.config.retries and not answered:
+            error_message = (
+                f"Maximum retries reached ({self.config.retries}). "
+                "Unable to generate new questions to answer the original question."
+            )
+            logger.error(error_message)
+            raise MaxRetries(error_message)
+        if answered:
+            logger.info("No additional questions needed to answer the main question.")
+            memory.restart = False
+            return
+        await memory.add_step(
+            step_module="restart",
+            step_title=self.step_title("Rephrase"),
+            step_value=f"New questions: {', '.join(new_questions)}",
+            step_reason=reason,
+            timeit=time() - t0,
+            step_agent_path=f"/postprocess/{self.config.id if self.config.id else 'default'}",
+            input_nuclia_tokens=input,
+            output_nuclia_tokens=output,
+        )
+
+        memory.add_context_questions(new_questions)
+        memory.restart = True

hyperforge_restart-1.0.0.post19/src/hyperforge_restart/config.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+from hyperforge.agent import AgentConfig
+from pydantic.config import ConfigDict
+
+
+class RestartAgentConfig(AgentConfig):
+    model_config = ConfigDict(title="Restart")
+    module: Literal["restart"] = "restart"
+    model: str
+    retries: int = 2

hyperforge_restart-1.0.0.post19/src/hyperforge_restart.egg-info/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: hyperforge_restart
+Version: 1.0.0.post19
+Summary: Restart Hyperforge agent
+Author-email: Nuclia <nucliadb@nuclia.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://progress.com
+Project-URL: Repository, https://github.com/nuclia/forge
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hyperforge
+
+# Rephrase Hyperforge agents

hyperforge_restart-1.0.0.post19/src/hyperforge_restart.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/hyperforge_restart/__init__.py
+src/hyperforge_restart/agent.py
+src/hyperforge_restart/config.py
+src/hyperforge_restart.egg-info/PKG-INFO
+src/hyperforge_restart.egg-info/SOURCES.txt
+src/hyperforge_restart.egg-info/dependency_links.txt
+src/hyperforge_restart.egg-info/requires.txt
+src/hyperforge_restart.egg-info/top_level.txt
+tests/test_restart.py

hyperforge_restart-1.0.0.post19/src/hyperforge_restart.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyperforge_restart-1.0.0.post19/src/hyperforge_restart.egg-info/requires.txt

@@ -0,0 +1 @@
+hyperforge

hyperforge_restart-1.0.0.post19/src/hyperforge_restart.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyperforge_restart

hyperforge_restart-1.0.0.post19/tests/test_restart.py

@@ -0,0 +1,111 @@
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+from hyperforge.exceptions import MaxRetries
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import EphemeralSessionMemory
+from hyperforge.models import MemoryConfig, Rules
+from hyperforge_restart.agent import RestartAgent
+from hyperforge_restart.config import RestartAgentConfig
+
+pytestmark = pytest.mark.asyncio
+
+
+def make_memory(restart_steps: int = 0):
+    session = EphemeralSessionMemory.from_config(
+        config=MemoryConfig(), agent_id="test", workflow_id="test", rules=Rules()
+    )
+    session.init("test-session")
+    memory = session.start_question("What is the capital of France?")
+    # Inject fake restart steps into memory
+    for _ in range(restart_steps):
+        step = MagicMock()
+        step.module = "restart"
+        memory.steps.append(step)
+    return memory
+
+
+def make_manager(answered: bool, questions: list[str] | None = None):
+    manager = MagicMock(spec=Manager)
+    manager.execute_json = AsyncMock(
+        return_value=(
+            {
+                "questions": questions or ["What language do they speak in France?"],
+                "reason": "Need to confirm language spoken.",
+                "answered": answered,
+            },
+            10,
+            20,
+        )
+    )
+    return manager
+
+
+async def test_restart_agent_answered():
+    """When the LLM says the question is already answered, restart should be False and no step added."""
+    config = RestartAgentConfig(model="gpt-4o", retries=2)
+    agent = RestartAgent(config=config)
+    memory = make_memory(restart_steps=0)
+    manager = make_manager(answered=True)
+
+    await agent(memory=memory, manager=manager)
+
+    assert memory.restart is False
+    assert not any(s.module == "restart" for s in memory.steps)
+
+
+async def test_restart_agent_not_answered_first_retry():
+    """When not answered and retries not exhausted, a restart step should be added."""
+    config = RestartAgentConfig(model="gpt-4o", retries=2)
+    agent = RestartAgent(config=config)
+    memory = make_memory(restart_steps=0)
+    manager = make_manager(answered=False, questions=["What language do they speak?"])
+
+    await agent(memory=memory, manager=manager)
+
+    assert memory.restart is True
+    restart_steps = [s for s in memory.steps if s.module == "restart"]
+    assert len(restart_steps) == 1
+
+
+async def test_restart_agent_not_answered_last_allowed_retry():
+    """On the last allowed retry (retry < retries), a restart step should still be added."""
+    config = RestartAgentConfig(model="gpt-4o", retries=2)
+    agent = RestartAgent(config=config)
+    # One restart step already in memory, retries=2 so retry=1 < 2
+    memory = make_memory(restart_steps=1)
+    manager = make_manager(answered=False, questions=["Another clarification?"])
+
+    await agent(memory=memory, manager=manager)
+
+    assert memory.restart is True
+    restart_steps = [s for s in memory.steps if s.module == "restart"]
+    assert len(restart_steps) == 2
+
+
+async def test_restart_agent_max_retries_raises():
+    """When retries are exhausted and question is not answered, MaxRetries should be raised."""
+    config = RestartAgentConfig(model="gpt-4o", retries=2)
+    agent = RestartAgent(config=config)
+    # Two restart steps already means retry == retries
+    memory = make_memory(restart_steps=2)
+    manager = make_manager(answered=False)
+
+    with pytest.raises(MaxRetries):
+        await agent(memory=memory, manager=manager)
+
+
+async def test_restart_agent_context_questions_updated():
+    """New questions from the LLM should be added to memory context questions."""
+    config = RestartAgentConfig(model="gpt-4o", retries=3)
+    agent = RestartAgent(config=config)
+    memory = make_memory(restart_steps=0)
+    new_questions = ["What year did it become the capital?", "What is the population?"]
+    manager = make_manager(answered=False, questions=new_questions)
+
+    await agent(memory=memory, manager=manager)
+
+    stored_questions = list(memory.context_questions.values())
+    for q in new_questions:
+        assert q in stored_questions