hyperforge-conditional 1.0.0.post19__py3-none-any.whl

hyperforge_conditional/__init__.py

@@ -0,0 +1,11 @@
+from .context_agent import ContextConditional
+from .generation_agent import GenerationConditional
+from .postprocess_agent import PostprocessConditional
+from .preprocess_agent import PreprocessConditional
+
+__all__ = [
+    "ContextConditional",
+    "GenerationConditional",
+    "PreprocessConditional",
+    "PostprocessConditional",
+]

hyperforge_conditional/conditional.py

@@ -0,0 +1,235 @@
+import asyncio
+from time import time
+from typing import Any, Dict, List, Literal, Optional, cast
+
+from hyperforge.agent import Agent, AgentConfig
+from hyperforge.configure import get_agent_config_klass, get_agent_klass
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import QuestionMemory
+from hyperforge.trace import trace_agent
+from hyperforge.utils import WidgetType
+from pydantic import BaseModel, Field, field_serializer, field_validator
+
+from hyperforge import PROMPT_ENVIRONMENT
+
+CONDITIONAL_AGENT = """
+Given a prompt that indicates a condition , assess whether a given text fulfills it or not.
+# PROMPT:
+{{prompt}}
+
+
+# TEXT:
+{{text}}
+
+{% if similarity %}
+# SIMILAR QUERIES:
+Similar queries that also fulfill that condition
+{% for similar in similarity_examples %}
+- {{similar}}
+{% endfor -%}
+{% endif %}
+
+# Important rules to follow
+
+{% for rule in rules %}
+{{rule}}
+{% endfor -%}
+
+# Output definition:
+
+Your output should always follow the following schema in a JSON format (Not markdon, please, start with b...).
+
+{{json_schema}}
+"""
+
+CONDITIONAL_AGENT_TEMPLATE = PROMPT_ENVIRONMENT.from_string(CONDITIONAL_AGENT)
+
+
+CONDITIONAL_SCHEMA = {
+    "title": "yes_no",
+    "description": "Choose yes or no, depending on whether the condition is fulfilled",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "yes": {"type": "boolean"},
+            "reason": {"type": "string", "description": "reasoning behind the answer"},
+        },
+    },
+}
+
+
+class ConditionalAgentConfig(AgentConfig):
+    then: List[AgentConfig] = Field(
+        default_factory=list,
+        title="Then",
+        description="List of agents to run in case the condition is  valid",
+    )
+    else_: List[AgentConfig] = Field(
+        default_factory=list,
+        title="Else",
+        description="List of agents to run in case the condition is not valid",
+    )
+    prompt: Optional[str] = Field(
+        default=None,
+        title="Condition Prompt",
+        description="Prompt to evaluate the condition",
+        json_schema_extra={
+            "show_in_node": True,
+            "widget": WidgetType.EXPANDABLE_TEXTAREA,
+        },
+    )
+    has_keywords: Optional[List[str]] = Field(
+        default=None,
+        title="Keywords",
+        description="List of keywords to evaluate the condition",
+    )
+    similarity: Optional[List[str]] = Field(
+        default=None,
+        title="Similar Queries",
+        description="List of similar queries to evaluate the condition",
+    )
+    on: Literal["QUESTION", "ANSWER", "CONTEXT"] = Field(
+        default="QUESTION",
+        title="Evaluate condition on",
+        description="Source to evaluate the condition on. ",
+    )
+    model: str = Field(
+        default="chatgpt-o3-mini",
+        title="Generative model",
+        description="Model used to assess the condition",
+        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
+    )
+
+    @field_serializer("then", "else_")
+    def serialize_conditional_agent(
+        self, field: list[BaseModel]
+    ) -> Optional[List[Dict[str, Any]]]:
+        if field is None:
+            return field
+        return [agent.model_dump() for agent in field]
+
+    @field_validator("then", "else_", mode="before")
+    @classmethod
+    def is_conditional_agent(cls, value: list[Dict[str, Any]]) -> list[BaseModel]:
+        if value is None:
+            return value
+        result = []
+        for agent_cfg in value:
+            module = agent_cfg.get("module")
+            if module is None:
+                raise ValueError("Invalid agent config: missing 'module' field")
+
+            agent_config_klass = get_agent_config_klass(module)
+            agent_config_instance = agent_config_klass.model_validate(agent_cfg)
+            result.append(agent_config_instance)
+        return result  # type: ignore
+
+
+class Conditional:
+    then: Optional[list[Agent]] = None
+    else_: Optional[list[Agent]] = None
+    arag_step: str
+    config: Any
+    agent_id: Any
+
+    async def conditional_from_config(self, config: ConditionalAgentConfig):
+        agent_module = None
+        then_agents_obj_list = []
+        for then_agent in config.then:
+            if then_agent:
+                agent_module = then_agent.module
+            if agent_module is None:
+                raise Exception("No agent found")
+
+            agent_klass = get_agent_klass(agent_module)
+            # We dump and load to create the agent via from_config
+            then_agents_obj_list.append((agent_klass, then_agent))
+
+        agent_id = None
+        else_agents_obj_list = []
+        for else_agent in config.else_:
+            if else_agent is not None:
+                agent_id = else_agent.module
+            if agent_id is None:
+                raise Exception("No agent found")
+
+            agent_class = get_agent_klass(agent_id)
+            # We dump and load to create the agent via from_config
+            else_agents_obj_list.append((agent_class, else_agent))
+
+        self.then = await asyncio.gather(
+            *[klass.from_config(cfg) for klass, cfg in then_agents_obj_list]
+        )
+        self.else_ = (
+            await asyncio.gather(
+                *[klass.from_config(cfg) for klass, cfg in else_agents_obj_list]
+            )
+            if else_agents_obj_list
+            else None
+        )
+
+    async def make_decision(
+        self,
+        question: str,
+        memory: QuestionMemory,
+        manager: Manager,
+        title: Optional[str] = None,
+    ) -> bool:
+        t0 = time()
+        config: ConditionalAgentConfig = cast(ConditionalAgentConfig, self.config)
+
+        prompt = CONDITIONAL_AGENT_TEMPLATE.render(
+            prompt=config.prompt,
+            rules=memory.get_rules(),
+            text=question,
+            similarity_examples=config.similarity,
+        )
+
+        sources, input, output = await manager.execute_json(
+            prompt=prompt,
+            schema=CONDITIONAL_SCHEMA,
+            user_id="conditional",
+            model=config.model,
+            tracking=memory.get_tracking_info(),
+        )
+        condition = sources.get("yes", False)
+        reason = sources.get("reason")
+
+        await memory.add_step(
+            step_module=config.module,
+            step_title=f"{title}: Condition check",
+            step_value=str(condition),
+            step_reason=reason,
+            timeit=time() - t0,
+            input_nuclia_tokens=input,
+            output_nuclia_tokens=output,
+            step_agent_path=f"/{self.arag_step}/{self.agent_id}",
+        )
+        return condition
+
+    @trace_agent
+    async def __call__(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+    ):
+        question = ""
+        if self.config.on == "QUESTION" and memory.actual_question:
+            question = memory.actual_question
+        elif self.config.on == "ANSWER" and memory.final_answer:
+            question = memory.final_answer
+        elif self.config.on == "CONTEXT":
+            question = "\n".join([x.summary for x in memory.contexts])
+
+        condition = await self.make_decision(
+            memory=memory,
+            manager=manager,
+            question=question,
+        )
+
+        if condition and self.then is not None:
+            for then_agent in self.then:
+                await then_agent(memory, manager)  # type: ignore
+        elif condition is False and self.else_ is not None:
+            for else_agent in self.else_:
+                await else_agent(memory, manager)  # type: ignore

hyperforge_conditional/context_agent.py

@@ -0,0 +1,159 @@
+from typing import Any, Dict, Literal, Optional, cast
+from uuid import uuid4
+
+from hyperforge.agent import Agent
+from hyperforge.configure import agent
+from hyperforge.context.agent import ContextAgent, trace_agent
+from hyperforge.context.config import ContextAgentConfig
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import Chunk, Context, QuestionMemory
+from pydantic import Field
+from pydantic.config import ConfigDict
+
+from hyperforge_conditional.conditional import (
+    Conditional,
+    ConditionalAgentConfig,
+)
+
+
+class ContextConditionalAgentConfig(ConditionalAgentConfig, ContextAgentConfig):
+    model_config = ConfigDict(title="Condition")
+    module: Literal["context_conditional"] = "context_conditional"
+    on: Literal["QUESTION", "CONTEXT"] = Field(  # type: ignore
+        default="QUESTION",
+        title="Evaluate condition on",
+        description="Source to evaluate the condition on. CONTEXT is only valid when this agent is used as a next agent in a chain.",
+    )
+
+
+@agent(
+    id="context_conditional",
+    agent_type="context",
+    title="Context Conditional",
+    description="Use Context Conditional to get information from the internet to answer questions.",
+    config_schema=ContextConditionalAgentConfig,
+)
+class ContextConditional(
+    ContextAgent, Conditional, Agent[ContextConditionalAgentConfig]
+):
+    arag_step: str = "context"
+
+    async def inner_from_config(
+        self, config: ContextConditionalAgentConfig, agent_id: Optional[str] = None
+    ):
+        # Build then and else branches
+        await self.context_from_config(config)
+        await self.conditional_from_config(config)
+
+    async def __call__(self, memory: QuestionMemory, manager: Manager):
+        await Conditional.__call__(self, memory, manager)
+
+    @trace_agent
+    async def get_question_context(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+        question_uuid: str,
+        question: str,
+        flow_id: str,
+        extra_context: Optional[Dict[str, Any]] = None,
+    ):
+        self.config: ContextConditionalAgentConfig  # type: ignore
+        if extra_context is not None:
+            question, question_uuid = await self.rephrase(
+                memory=memory,
+                manager=manager,
+                question_uuid=question_uuid,
+                question=question,
+                contexts=extra_context,
+                model=self.config.rephrase_model,
+                module=self.config.module,
+                user_id="next_rephrase",
+                ident=self.agent_id,
+            )
+
+        conditional_subject = question
+        # Previous context only used when selected and extra context is provided - that is, the conditional comes after a next agent in the flow
+        if self.config.on == "CONTEXT" and extra_context is not None:
+            conditional_subject = "\n".join(extra_context.values())
+
+        # condition checking and branching
+        condition = await self.make_decision(
+            memory=memory,
+            manager=manager,
+            question=conditional_subject,
+        )
+        selected_agents: list[Agent] = [
+            agent for agent in (self.then if condition else self.else_) or []
+        ]
+        for selected_agent in selected_agents:
+            await cast(ContextAgent, selected_agent).get_question_context(
+                memory, manager, question_uuid, question, flow_id=flow_id
+            )
+        # If fallback is configured, we check if there are missing questions taking into account the executed agents contexts/summaries
+        if self.fallback is not None:
+            conditional_context = Context(
+                agent_id=self.agent_id,
+                original_question_uuid=memory.original_question_uuid,
+                actual_question_uuid=question_uuid,
+                question=question,
+                agent="Conditional",
+                title="Summarizing Conditional Agents Contexts",
+                source="conditional",
+                chunks=[],
+            )
+
+            for agent in selected_agents:
+                conditional_context.chunks.extend(
+                    [
+                        Chunk(
+                            chunk_id=agent.agent_id,
+                            text=summary,
+                            origin_agent=self.config.module,
+                        )
+                        for summary in memory.get_agent_answer_summaries(
+                            flow_id=flow_id, agent_id=agent.agent_id
+                        )
+                    ]
+                )
+            (
+                _,
+                missing_question,
+                _,
+            ) = await self.validate_ctx_and_answer(
+                memory,
+                manager,
+                conditional_context,
+                question=question,
+            )
+            if missing_question is not None and missing_question.strip() != "":
+                await self.fallback.get_question_context(
+                    memory,
+                    manager,
+                    question_uuid=uuid4().hex,
+                    question=missing_question,
+                    flow_id=flow_id,
+                )
+
+        if self.next_agent is not None:
+            extra_context = extra_context or {}
+            for agent in (  # type: ignore
+                selected_agents + [self.fallback]
+                if self.fallback is not None
+                else selected_agents
+            ):
+                if agent:
+                    answer_summaries = memory.get_agent_answer_summaries(
+                        flow_id=flow_id, agent_id=agent.agent_id
+                    )
+                    if answer_summaries:
+                        extra_context[agent.agent_id] = "\n".join(answer_summaries)
+
+            await self.next_agent.get_question_context(
+                memory,
+                manager,
+                question_uuid,
+                question,
+                extra_context=extra_context,
+                flow_id=flow_id,
+            )

hyperforge_conditional/generation_agent.py

@@ -0,0 +1,48 @@
+from typing import List, Literal, Optional
+
+from hyperforge.agent import Agent, AgentConfig
+from hyperforge.configure import agent
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import QuestionMemory
+from pydantic import Field
+from pydantic.config import ConfigDict
+
+from hyperforge_conditional.conditional import (
+    Conditional,
+    ConditionalAgentConfig,
+)
+
+
+class GenerationConditionalAgentConfig(ConditionalAgentConfig):
+    model_config = ConfigDict(title="Condition")
+    module: Literal["generation_conditional"] = "generation_conditional"
+    then: List["AgentConfig"] = Field(
+        default_factory=list,
+        title="Then",
+        description="List of agents to run in case the condition is  valid",
+    )
+    else_: List["AgentConfig"] = Field(
+        default_factory=list,
+        title="Else",
+        description="List of agents to run in case the condition is not valid",
+    )
+
+
+@agent(
+    id="generation_conditional",
+    agent_type="generation",
+    title="Generation Conditional",
+    description="Conditional generation agent that decides which generation strategy to use based on the context.",
+    config_schema=GenerationConditionalAgentConfig,
+)
+class GenerationConditional(Agent[GenerationConditionalAgentConfig], Conditional):
+    arag_step: str = "generation"
+
+    async def inner_from_config(
+        self, config: GenerationConditionalAgentConfig, agent_id: Optional[str] = None
+    ):
+        # Build then and else branches
+        await self.conditional_from_config(config)
+
+    async def __call__(self, memory: QuestionMemory, manager: Manager):
+        await Conditional.__call__(self, memory, manager)

hyperforge_conditional/postprocess_agent.py

@@ -0,0 +1,47 @@
+from typing import List, Literal, Optional
+
+from hyperforge.agent import Agent, AgentConfig
+from hyperforge.configure import agent
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import QuestionMemory
+from pydantic import Field
+from pydantic.config import ConfigDict
+
+from hyperforge_conditional.conditional import (
+    Conditional,
+    ConditionalAgentConfig,
+)
+
+
+class PostprocessConditionalAgentConfig(ConditionalAgentConfig):
+    model_config = ConfigDict(title="Condition")
+    module: Literal["post_conditional"] = "post_conditional"
+    then: List["AgentConfig"] = Field(
+        default_factory=list,
+        title="Then",
+        description="List of agents to run in case the condition is  valid",
+    )
+    else_: List["AgentConfig"] = Field(
+        default_factory=list,
+        title="Else",
+        description="List of agents to run in case the condition is not valid",
+    )
+
+
+@agent(
+    id="postprocess_conditional",
+    agent_type="postprocess",
+    title="Postprocess Conditional",
+    description="Agent that performs conditional postprocessing.",
+    config_schema=PostprocessConditionalAgentConfig,
+)
+class PostprocessConditional(Agent[PostprocessConditionalAgentConfig], Conditional):
+    arag_step: str = "postprocess"
+
+    async def inner_from_config(
+        self, config: PostprocessConditionalAgentConfig, agent_id: Optional[str] = None
+    ):
+        await self.conditional_from_config(config)
+
+    async def __call__(self, memory: QuestionMemory, manager: Manager):
+        await Conditional.__call__(self, memory, manager)

hyperforge_conditional/preprocess_agent.py

@@ -0,0 +1,47 @@
+from typing import List, Literal, Optional
+
+from hyperforge.agent import Agent, AgentConfig
+from hyperforge.configure import agent
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import QuestionMemory
+from pydantic import Field
+from pydantic.config import ConfigDict
+
+from hyperforge_conditional.conditional import (
+    Conditional,
+    ConditionalAgentConfig,
+)
+
+
+class PreprocessConditionalAgentConfig(ConditionalAgentConfig):
+    model_config = ConfigDict(title="Condition")
+    module: Literal["pre_conditional"] = "pre_conditional"
+    then: List[AgentConfig] = Field(
+        default_factory=list,
+        title="Then",
+        description="List of agents to run in case the condition is  valid",
+    )
+    else_: List[AgentConfig] = Field(
+        default_factory=list,
+        title="Else",
+        description="List of agents to run in case the condition is not valid",
+    )
+
+
+@agent(
+    id="preprocess_conditional",
+    agent_type="preprocess",
+    title="Preprocess Conditional",
+    description="Conditional preprocessing agent that decides which preprocessing strategy to use based on the context.",
+    config_schema=PreprocessConditionalAgentConfig,
+)
+class PreprocessConditional(Agent[PreprocessConditionalAgentConfig], Conditional):
+    arag_step: str = "preprocess"
+
+    async def inner_from_config(
+        self, config: PreprocessConditionalAgentConfig, agent_id: Optional[str] = None
+    ):
+        await self.conditional_from_config(config)
+
+    async def __call__(self, memory: QuestionMemory, manager: Manager):
+        await Conditional.__call__(self, memory, manager)

hyperforge_conditional-1.0.0.post19.dist-info/METADATA

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

hyperforge_conditional-1.0.0.post19.dist-info/RECORD

@@ -0,0 +1,10 @@
+hyperforge_conditional/__init__.py,sha256=u0ZZtOSOL0xIypljmJjGiHMI-6G_oGcichP8aS9Mn1U,333
+hyperforge_conditional/conditional.py,sha256=_dKSf_ctilRrz7pWpu4ZHgRFf59ZKu1IclFho_MdLHc,7513
+hyperforge_conditional/context_agent.py,sha256=h0JkRpNoJ9yHIODXC9aqsk0inRGiWhLdiw31m89VWGE,6035
+hyperforge_conditional/generation_agent.py,sha256=uKYqcyE-0vCqhlGrH3Vx9KRU_RisEVummvT9sX8PMmI,1669
+hyperforge_conditional/postprocess_agent.py,sha256=6-a8IohFUM8oJvvcmVcKHHVcCCLEwCTuSUc_6sm1Nk8,1578
+hyperforge_conditional/preprocess_agent.py,sha256=yuKOkwtgsGz4EhH6uzuTXjVP8vQDTF0HV7oUDpmvlUQ,1618
+hyperforge_conditional-1.0.0.post19.dist-info/METADATA,sha256=GU-4xk1w7ksUeItEV2LJqoSlfYjU9awkFC57P6vMJdw,737
+hyperforge_conditional-1.0.0.post19.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hyperforge_conditional-1.0.0.post19.dist-info/top_level.txt,sha256=L7vLEjAFnCSkTy4XqjBicrm8-5rGiy99fCnuPmEllx0,23
+hyperforge_conditional-1.0.0.post19.dist-info/RECORD,,

hyperforge_conditional-1.0.0.post19.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hyperforge_conditional-1.0.0.post19.dist-info/top_level.txt

@@ -0,0 +1 @@
+hyperforge_conditional