hyperforge-google 1.0.0.post29__tar.gz

hyperforge_google-1.0.0.post29/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: hyperforge_google
+Version: 1.0.0.post29
+Summary: Google Search 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/hyperforge
+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
+Requires-Dist: google-genai
+
+# Google Hyperforge agents

hyperforge_google-1.0.0.post29/README.md

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

hyperforge_google-1.0.0.post29/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperforge_google"
+version = "1.0.0.post29"
+license = "Apache-2.0"
+description = "Google Search 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", "google-genai"]
+
+[dependency-groups]
+dev = [
+    "mypy",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-recording",
+    "ty",
+]
+
+[project.urls]
+Homepage = "https://progress.com"
+Repository = "https://github.com/nuclia/hyperforge"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

hyperforge_google-1.0.0.post29/setup.cfg

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

hyperforge_google-1.0.0.post29/src/hyperforge_google/__init__.py

@@ -0,0 +1,4 @@
+from .agent import GoogleAgent
+from .driver import GoogleDriver
+
+__all__ = ["GoogleAgent", "GoogleDriver"]

hyperforge_google-1.0.0.post29/src/hyperforge_google/agent.py

@@ -0,0 +1,199 @@
+# GOOD REFERENCE: https://github.com/philschmid/gemini-samples/blob/main/examples/gemini-google-search.ipynb
+
+from time import time
+from typing import Any, ClassVar, Dict, List, Optional, Tuple, cast
+from uuid import uuid4
+
+from google.genai.types import (
+    GenerateContentConfig,
+    GoogleSearch,
+    ThinkingConfig,
+    Tool,
+)
+from hyperforge.agent import Agent
+from hyperforge.configure import agent
+from hyperforge.context.agent import ContextAgent
+from hyperforge.definition import FunctionDefinition
+from hyperforge.manager import Manager
+from hyperforge.memory.memory import Chunk, Context, QuestionMemory
+from hyperforge.utils.http import safe_http_client
+
+from hyperforge_google.config import GoogleAgentConfig
+from hyperforge_google.driver import GoogleDriver
+
+
+@agent(
+    id="google",
+    agent_type="context",
+    title="Google Search",
+    description="Use Google Search to get information from the internet to answer questions.",
+    config_schema=GoogleAgentConfig,
+)
+class GoogleAgent(ContextAgent, Agent[GoogleAgentConfig]):
+    __published_functions__: ClassVar[Dict[str, FunctionDefinition]] = {
+        "internet_search": FunctionDefinition(
+            name="internet_search",
+            description="Performs an internet search using Google Search to get context to answer questions.",
+            parameters={
+                "question": {
+                    "type": "string",
+                    "description": "The question to search for on the internet.",
+                },
+            },
+        )
+    }
+    google_search_tool: Optional[Tool] = None
+
+    async def inner_from_config(
+        self, config: GoogleAgentConfig, agent_id: Optional[str] = None
+    ):
+        await self.context_from_config(config)
+        self.google_search_tool = Tool(google_search=GoogleSearch())
+
+    def driver(self, manager: Manager) -> GoogleDriver:
+        return cast(GoogleDriver, manager.drivers[self.config.source])
+
+    async def internet_search(
+        self,
+        question: str,
+        memory: QuestionMemory,
+        manager: Manager,
+        question_uuid: Optional[str] = None,
+        flow_id: Optional[str] = None,
+    ) -> Context:
+        if question_uuid is None:
+            question_uuid = uuid4().hex
+
+        driver = self.driver(manager)
+        t0 = time()
+        assert self.google_search_tool is not None, "google_search_tool not initialized"
+        response = await driver.client.aio.models.generate_content(
+            model=self.config.gen_model_id,
+            contents=question,
+            config=GenerateContentConfig(
+                tools=[self.google_search_tool],
+                response_modalities=["TEXT"],
+                thinking_config=ThinkingConfig(include_thoughts=True),
+            ),
+        )
+        if (
+            response is not None
+            and response.usage_metadata is not None
+            and response.usage_metadata.total_token_count is not None
+            and response.usage_metadata.prompt_token_count is not None
+        ):
+            tokens = response.usage_metadata.total_token_count * 0.05
+            input_tokens = response.usage_metadata.prompt_token_count * 0.05
+            output_tokens = tokens - input_tokens
+        else:
+            input_tokens = 0.5
+            output_tokens = 0.5
+        context = Context(
+            agent_id=self.config.id or self.agent_id,
+            original_question_uuid=memory.original_question_uuid,
+            actual_question_uuid=question_uuid,
+            question=question,
+            source="google",
+            agent="google",
+            title=self.config.title
+            if self.config.title
+            else "Internet search with Google",
+        )
+        http_client = safe_http_client()
+        chunks: Dict[int, str] = {}
+        answer = ""
+        reasoning = ""
+        count = 0
+        if (
+            response
+            and response.candidates
+            and len(response.candidates) > 0
+            and response.candidates[0].content
+            and response.candidates[0].content.parts
+        ):
+            candidate = response.candidates[0]
+            for each in response.candidates[0].content.parts:
+                if each.thought is True and each.text is not None:
+                    reasoning += each.text
+                elif each.text is not None:
+                    answer += each.text
+            if (
+                candidate.grounding_metadata
+                and candidate.grounding_metadata.grounding_chunks
+            ):
+                for chunk_id, chunk in enumerate(
+                    candidate.grounding_metadata.grounding_chunks
+                ):
+                    if chunk.web is not None and chunk.web.uri is not None:
+                        resp = await http_client.get(chunk.web.uri)
+                        chunks[chunk_id] = resp.headers.get("location", "")
+
+            if (
+                candidate.grounding_metadata
+                and candidate.grounding_metadata.grounding_supports
+            ):
+                for ground in candidate.grounding_metadata.grounding_supports:
+                    if ground.grounding_chunk_indices:
+                        url = [
+                            chunks[indice] for indice in ground.grounding_chunk_indices
+                        ]
+                    else:
+                        url = []
+                    if ground.segment and ground.segment.text:
+                        text = ground.segment.text
+                    else:
+                        text = ""
+                    count += 1
+                    context.chunks.append(
+                        Chunk(
+                            chunk_id=uuid4().hex,
+                            text=text,
+                            labels=[],
+                            url=url,
+                            origin_agent=self.config.module,
+                        )
+                    )
+                # if candidate.grounding_metadata.web_search_queries:
+                #     for query in candidate.grounding_metadata.web_search_queries:
+                #         # Queries
+        await memory.add_answer(
+            answer,
+            module=self.config.module,
+            agent_path=f"/context/{self.config.id if self.config.id else 'default'}",
+        )
+        context.summary = answer
+        await memory.add_step(
+            step_module=self.config.module,
+            step_title=self.step_title("Search results"),
+            step_agent_path=f"/context/{self.config.id if self.config.id else 'default'}",
+            step_reason=reasoning,
+            step_value=f"{count} results found",
+            timeit=time() - t0,
+            input_nuclia_tokens=input_tokens,
+            output_nuclia_tokens=output_tokens,
+        )
+        return context
+
+    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,
+    ) -> List[Tuple[str, str]]:
+        context = await self.internet_search(
+            question=question,
+            memory=memory,
+            manager=manager,
+            question_uuid=question_uuid,
+        )
+        missing = await self.save_ctx_and_return_missing(
+            context=context,
+            question=question,
+            memory=memory,
+            manager=manager,
+            flow_id=flow_id,
+        )
+        return [missing] if missing is not None else []

hyperforge_google-1.0.0.post29/src/hyperforge_google/config.py

@@ -0,0 +1,38 @@
+from typing import ClassVar, Literal, Optional, Tuple
+
+from hyperforge.context.config import ContextAgentConfig
+from hyperforge.driver import DriverConfig, EncryptedPayload
+from hyperforge.utils import WidgetType
+from pydantic import Field
+from pydantic.config import ConfigDict
+
+
+class GoogleInnerConfig(EncryptedPayload):
+    encrypted_fields: ClassVar[list[str]] = ["api_key", "credentials"]
+
+    api_key: Optional[str] = None
+    credentials: Optional[str] = None
+    vertexai: bool = False
+    project: Optional[str] = None
+    location: Optional[str] = None
+
+
+class GoogleDriverConfig(DriverConfig[GoogleInnerConfig]):
+    model_config = ConfigDict(title="Google Gemini")
+    provider: Literal["google"] = "google"
+    config: GoogleInnerConfig
+
+
+class GoogleAgentConfig(ContextAgentConfig):
+    model_config = ConfigDict(title="Google Gemini")
+    module: Literal["google"] = "google"
+    gen_model_id: str = "gemini-2.5-flash"
+    source: str = "google"
+    published_functions: Optional[Tuple[str, ...]] = Field(
+        default=("internet_search",),
+        title="Published functions",
+        description="List of functions published by this agent to be used by other agents in the chain",
+        json_schema_extra={
+            "widget": WidgetType.NOT_SHOWN,
+        },
+    )

hyperforge_google-1.0.0.post29/src/hyperforge_google/driver.py

@@ -0,0 +1,36 @@
+from google.genai import Client
+from hyperforge.configure import driver
+from hyperforge.driver import Driver
+from typing_extensions import Self
+
+from hyperforge_google.config import GoogleDriverConfig
+
+
+@driver(
+    id="google",
+    title="Google Driver",
+    description="Driver for interacting with the Google API.",
+    config_schema=GoogleDriverConfig,
+)
+class GoogleDriver(Driver):
+    client: Client
+
+    @classmethod
+    async def init(cls, driver: GoogleDriverConfig) -> Self:
+        creds = None
+        if driver.config.vertexai:
+            from google.auth import load_credentials_from_file
+
+            creds, _ = load_credentials_from_file(driver.config.credentials)
+        client = Client(
+            vertexai=driver.config.vertexai,
+            credentials=creds,
+            api_key=driver.config.api_key,
+            project=driver.config.project,
+            location=driver.config.location,
+        )
+        return cls(
+            client=client,
+            name=driver.name,
+            provider=driver.provider,
+        )

hyperforge_google-1.0.0.post29/src/hyperforge_google.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: hyperforge_google
+Version: 1.0.0.post29
+Summary: Google Search 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/hyperforge
+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
+Requires-Dist: google-genai
+
+# Google Hyperforge agents

hyperforge_google-1.0.0.post29/src/hyperforge_google.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/hyperforge_google/__init__.py
+src/hyperforge_google/agent.py
+src/hyperforge_google/config.py
+src/hyperforge_google/driver.py
+src/hyperforge_google/py.typed
+src/hyperforge_google.egg-info/PKG-INFO
+src/hyperforge_google.egg-info/SOURCES.txt
+src/hyperforge_google.egg-info/dependency_links.txt
+src/hyperforge_google.egg-info/requires.txt
+src/hyperforge_google.egg-info/top_level.txt
+tests/test_google.py

hyperforge_google-1.0.0.post29/src/hyperforge_google.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyperforge_google-1.0.0.post29/src/hyperforge_google.egg-info/requires.txt

@@ -0,0 +1,2 @@
+hyperforge
+google-genai

hyperforge_google-1.0.0.post29/src/hyperforge_google.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyperforge_google

hyperforge_google-1.0.0.post29/tests/test_google.py

@@ -0,0 +1,91 @@
+import os
+from uuid import uuid4
+
+import pytest
+from hyperforge.configure import get_driver_config_instance, load_all_configurations
+from hyperforge.manager import Manager
+from hyperforge.memory import Context
+from hyperforge.memory.memory import EphemeralSessionMemory
+from hyperforge.minimal_fixtures import cassette_nua_key
+from hyperforge.models import MemoryConfig, Rules
+from hyperforge_google.agent import GoogleAgent
+from hyperforge_google.config import GoogleAgentConfig
+from nuclia.lib.nua import AsyncNuaClient
+
+NUA_KEY = os.environ.get(
+    "NUA_KEY",
+) or cassette_nua_key("https://europe-1.nuclia.cloud/")
+
+pytestmark = [
+    pytest.mark.vcr(
+        ignore_localhost=True,
+        match_on=["scheme", "host", "port", "path"],
+    ),
+    pytest.mark.asyncio,
+]
+
+
+DRIVERS = [
+    {
+        "provider": "google",
+        "identifier": "google-01",
+        "name": "google",
+        "config": {
+            "vertexai": False,
+            "api_key": os.environ.get("GOOGLE_API_KEY", "DUMMY_API_KEY"),
+        },
+    },
+]
+
+
+async def _run_question(
+    drivers: list[dict],
+    question: str,
+) -> list[Context]:
+    """Build a manager from driver configs, run the agent, return contexts."""
+    load_all_configurations("hyperforge_google")
+    # Google agent doesn't use nua — construct client directly with test values
+    nua = AsyncNuaClient(region="europe-1", account="test", token=NUA_KEY)
+    manager = await Manager.from_config(
+        drivers=[get_driver_config_instance(d) for d in drivers],
+        nua=nua,
+    )
+    config = GoogleAgentConfig.model_validate(
+        {
+            "module": "google",
+            "title": "Google Agent",
+            "source": "google-01",
+        }
+    )
+    agent = GoogleAgent(config=config)
+    await agent.inner_from_config(config)
+
+    session = EphemeralSessionMemory.from_config(
+        config=MemoryConfig(),
+        agent_id="test",
+        workflow_id="test",
+        rules=Rules(),
+    )
+    session.init("test-session")
+    memory = session.start_question(question)
+
+    flow_id = uuid4().hex
+    await agent.get_question_context(
+        memory=memory,
+        manager=manager,
+        question_uuid=memory.original_question_uuid,
+        question=question,
+        flow_id=flow_id,
+    )
+    return memory.get_agent_contexts(flow_id=flow_id, agent_id=agent.agent_id)
+
+
+async def test_google():
+    contexts = await _run_question(
+        DRIVERS,
+        "What is Nuclia?",
+    )
+    assert len(contexts) > 0
+    all_text = " ".join(chunk.text for ctx in contexts for chunk in ctx.chunks).lower()
+    summary = " ".join(ctx.summary for ctx in contexts if ctx.summary).lower()
+    assert "rag" in all_text or "ai" in all_text or "rag" in summary or "ai" in summary