hyperforge-related 1.0.0.post19__tar.gz

hyperforge_related-1.0.0.post19/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: hyperforge_related
+Version: 1.0.0.post19
+Summary: Related 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
+
+# Related Hyperforge agents

hyperforge_related-1.0.0.post19/README.md

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

hyperforge_related-1.0.0.post19/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperforge_related"
+version = "1.0.0.post19"
+license = "Apache-2.0"
+description = "Related 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]
+dev = [
+    "pytest",
+    "pytest-benchmark",
+    "pytest-docker-fixtures>=1.4.2",
+    "pytest-lazy-fixtures",
+    "pytest-recording",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-mock",
+]
+
+[project.urls]
+Homepage = "https://progress.com"
+Repository = "https://github.com/nuclia/forge"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

hyperforge_related-1.0.0.post19/setup.cfg

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

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

@@ -0,0 +1,104 @@
+from time import time
+
+from hyperforge.agent import Agent
+from hyperforge.manager import Manager
+from hyperforge.memory import QuestionMemory
+from hyperforge.trace import trace_agent
+
+from hyperforge_related.config import RelatedAgentConfig
+from hyperforge import PROMPT_ENVIRONMENT
+
+ASK_JSON_SCHEMA = {
+    "title": "related_questions",
+    "description": "Related questions to main question based on context information",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "related": {
+                "type": "array",
+                "items": {
+                    "type": "string",
+                    "description": "related question to the main question",
+                },
+            },
+        },
+    },
+}
+
+
+RELATED_PROMPT = """
+Provice a list of questions related to the original question that are not answered in the context.
+
+{{prompt}}
+
+[START OF CONTEXT]
+
+{% for con in context -%}
+Text:
+{% for chunk in con.chunks %}
+## {{chunk.title}}
+Labels: {% for label in chunk.labels %} {{label}} {% endfor -%}
+URL: {% for url in chunk.url%}{{url}}{% endfor -%}
+
+{{chunk.text}}
+{% endfor -%}
+
+Structured info:
+{% for structured in con.structured %}
+{{structured}}
+{% endfor -%}
+
+Answer summary: {{con.summary}}
+
+{% endfor -%}
+[END OF CONTEXT]
+
+MAIN QUESTION: {{question}}
+
+# Notes
+- Use the context provided without being overly selective.
+- If there is no need to add a new question return an empty list
+
+"""
+
+
+RELATED_PROMPT_TEMPLATE = PROMPT_ENVIRONMENT.from_string(RELATED_PROMPT)
+
+
+class RelatedAgent(Agent[RelatedAgentConfig]):
+    @trace_agent
+    async def __call__(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+    ):
+        # For each context in memory add context query, summary and answer onto a text and the initial question
+        t0 = time()
+
+        related_prompt = RELATED_PROMPT_TEMPLATE.render(
+            question=memory.original_question,
+            context=memory.contexts,
+            prompt=self.config.prompt,
+        )
+
+        related, input, output = await manager.execute_json(
+            prompt=related_prompt,
+            user_id="related",
+            model=self.config.model,
+            schema=ASK_JSON_SCHEMA,
+            tracking=memory.get_tracking_info(),
+        )
+
+        if related is not None:
+            for related_question in related.get("related", []):
+                memory.add_future_questions([related_question])
+            await memory.add_step(
+                step_module=self.config.module,
+                step_title=self.step_title("Related questions"),
+                step_value=str(related),
+                step_reason="",
+                step_agent_path=f"/postprocess/{self.config.id if self.config.id else 'default'}",
+                timeit=time() - t0,
+                input_nuclia_tokens=input,
+                output_nuclia_tokens=output,
+            )

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

@@ -0,0 +1,12 @@
+from typing import Literal, Optional
+
+from hyperforge.agent import AgentConfig
+from pydantic.config import ConfigDict
+
+
+class RelatedAgentConfig(AgentConfig):
+    model_config = ConfigDict(title="Related")
+    module: Literal["related"] = "related"
+    prompt: Optional[str] = None
+    model: str = "chatgpt-azure-4o-mini"
+    images: bool = False

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

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: hyperforge_related
+Version: 1.0.0.post19
+Summary: Related 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
+
+# Related Hyperforge agents

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

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

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+hyperforge_related

hyperforge_related-1.0.0.post19/tests/test_related.py

@@ -0,0 +1,144 @@
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import EphemeralSessionMemory
+from hyperforge.models import MemoryConfig, Rules
+from hyperforge_related.agent import RelatedAgent
+from hyperforge_related.config import RelatedAgentConfig
+
+
+def make_agent(model: str = "chatgpt-azure-4o-mini", prompt: str | None = None) -> RelatedAgent:
+    config = RelatedAgentConfig(id="test-related", model=model, prompt=prompt)
+    return RelatedAgent(config=config)
+
+
+def make_memory(question: str = "What is machine learning?"):
+    session = EphemeralSessionMemory.from_config(
+        config=MemoryConfig(), agent_id="test", workflow_id="test", rules=Rules()
+    )
+    session.init("test-session")
+    return session.start_question(question)
+
+
+def make_manager(related: list[str] | None = None, return_none: bool = False):
+    manager = MagicMock(spec=Manager)
+    questions = ["How does ML work?", "What is deep learning?"] if related is None else related
+    payload = None if return_none else {"related": questions}
+    manager.execute_json = AsyncMock(return_value=(payload, 10, 20))
+    return manager
+
+
+# --- Config tests ---
+
+def test_config_defaults():
+    config = RelatedAgentConfig()
+    assert config.module == "related"
+    assert config.model == "chatgpt-azure-4o-mini"
+    assert config.prompt is None
+    assert config.images is False
+
+
+def test_step_title():
+    agent = make_agent()
+    assert agent.step_title("Related questions") == "Related: Related questions"
+
+
+# --- Behaviour tests ---
+
+@pytest.mark.asyncio
+async def test_related_questions_added_to_future_questions():
+    """Questions returned by the LLM are stored in memory.future_questions."""
+    agent = make_agent()
+    memory = make_memory()
+    questions = ["What is supervised learning?", "What is a neural network?"]
+    manager = make_manager(related=questions)
+
+    await agent(memory=memory, manager=manager)
+
+    stored = list(memory.future_questions.values())
+    for q in questions:
+        assert q in stored
+
+
+@pytest.mark.asyncio
+async def test_step_added_when_related_not_none():
+    """A step is recorded when the LLM returns a non-None result."""
+    agent = make_agent()
+    memory = make_memory()
+    manager = make_manager(related=["Some follow-up?"])
+
+    await agent(memory=memory, manager=manager)
+
+    assert len(memory.steps) == 1
+    step = memory.steps[0]
+    assert step.module == "related"
+    assert step.title == "Related: Related questions"
+    assert step.agent_path == f"/postprocess/{agent.config.id}"
+
+
+@pytest.mark.asyncio
+async def test_no_step_when_llm_returns_none():
+    """When execute_json returns None, no step and no future questions are added."""
+    agent = make_agent()
+    memory = make_memory()
+    manager = make_manager(return_none=True)
+
+    await agent(memory=memory, manager=manager)
+
+    assert len(memory.steps) == 0
+    assert len(memory.future_questions) == 0
+
+
+@pytest.mark.asyncio
+async def test_empty_related_list_adds_step_but_no_future_questions():
+    """When the LLM returns an empty list, a step is still added but future_questions stays empty."""
+    agent = make_agent()
+    memory = make_memory()
+    manager = make_manager(related=[])
+
+    await agent(memory=memory, manager=manager)
+
+    assert len(memory.steps) == 1
+    assert len(memory.future_questions) == 0
+
+
+@pytest.mark.asyncio
+async def test_execute_json_called_with_correct_model():
+    """The configured model name is forwarded to manager.execute_json."""
+    agent = make_agent(model="my-custom-model")
+    memory = make_memory()
+    manager = make_manager()
+
+    await agent(memory=memory, manager=manager)
+
+    call_kwargs = manager.execute_json.call_args.kwargs
+    assert call_kwargs["model"] == "my-custom-model"
+
+
+@pytest.mark.asyncio
+async def test_custom_prompt_rendered_in_request():
+    """A custom prompt from config is included in the rendered prompt sent to the LLM."""
+    custom_prompt = "Focus on practical applications only."
+    agent = make_agent(prompt=custom_prompt)
+    memory = make_memory()
+    manager = make_manager()
+
+    await agent(memory=memory, manager=manager)
+
+    rendered_prompt = manager.execute_json.call_args.kwargs["prompt"]
+    assert custom_prompt in rendered_prompt
+
+
+@pytest.mark.asyncio
+async def test_question_included_in_rendered_prompt():
+    """The original question is included in the prompt sent to the LLM."""
+    question = "What are transformers in NLP?"
+    agent = make_agent()
+    memory = make_memory(question=question)
+    manager = make_manager()
+
+    await agent(memory=memory, manager=manager)
+
+    rendered_prompt = manager.execute_json.call_args.kwargs["prompt"]
+    assert question in rendered_prompt