hyperforge-nucliadb 1.0.0.post108__tar.gz → 1.0.0.post113__tar.gz

{hyperforge_nucliadb-1.0.0.post108 → hyperforge_nucliadb-1.0.0.post113}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperforge_nucliadb
-Version: 1.0.0.post108
+Version: 1.0.0.post113
 Summary: NucliaDB Hyperforge agent
 Author-email: Nuclia <nucliadb@nuclia.com>
 License-Expression: Apache-2.0
@@ -25,3 +25,13 @@ Basic ASK - Basic initial agent
 Advanced ASK (deprecated)
 ASK (experimental)
 Sync (Sync Service oauth linked)
+
+## Client identification
+
+NucliaDB `/ask` and `/find` requests made by these agents use
+`X-NDB-Client: agentic`, including when invoked as tools by a smart agent in a
+RAO workflow. The Sync driver inherits the same behavior. Other request headers
+are preserved, and caller-provided headers are not modified.
+
+Workflow memory searches through `/find` also use the `agentic` client type.
+The receiving NucliaDB API must support the `agentic` client type.

hyperforge_nucliadb-1.0.0.post113/README.md

@@ -0,0 +1,16 @@
+# NucliaDB Hyperforge agents
+
+Basic ASK - Basic initial agent
+Advanced ASK (deprecated)
+ASK (experimental)
+Sync (Sync Service oauth linked)
+
+## Client identification
+
+NucliaDB `/ask` and `/find` requests made by these agents use
+`X-NDB-Client: agentic`, including when invoked as tools by a smart agent in a
+RAO workflow. The Sync driver inherits the same behavior. Other request headers
+are preserved, and caller-provided headers are not modified.
+
+Workflow memory searches through `/find` also use the `agentic` client type.
+The receiving NucliaDB API must support the `agentic` client type.

{hyperforge_nucliadb-1.0.0.post108 → hyperforge_nucliadb-1.0.0.post113}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hyperforge_nucliadb"
-version = "1.0.0.post108"
+version = "1.0.0.post113"
 license = "Apache-2.0"
 description = "NucliaDB Hyperforge agent"
 authors = [{ name = "Nuclia", email = "nucliadb@nuclia.com" }]

{hyperforge_nucliadb-1.0.0.post108 → hyperforge_nucliadb-1.0.0.post113}/src/hyperforge_nucliadb/basic_ask_agent.py

@@ -1554,6 +1554,17 @@ class BasicAskAgent(ContextAgent, Agent[BasicAskAgentConfig]):
             logger.info(
                 f"No labels selected for faceted search on question {question}, skipping."
             )
+            context = Context(
+                agent_id=self.agent_id,
+                original_question_uuid=memory.original_question_uuid,
+                actual_question_uuid=None,
+                missing=question,
+                question=question,
+                source=source.id,
+                chunks=[],
+                agent="basic_ask_facets",
+                title=f"Faceted search on {source.id} Knowledge Box",
+            )
         else:
             # We are assuming resources equals fields here
             facets, total = await ndb.field_labels(labelsets=labels_selected)
@@ -1593,7 +1604,11 @@ class BasicAskAgent(ContextAgent, Agent[BasicAskAgentConfig]):
         await memory.add_step(
             step_module=self.config.module,
             step_title=self.step_title("Faceted count"),
-            step_reason="Faceted search performed",
+            step_reason=(
+                "Faceted search performed"
+                if labels_selected
+                else "Faceted search skipped"
+            ),
             step_value=selected_labels.get("reasoning", ""),
             timeit=time() - t0,
             input_nuclia_tokens=input_nt,

{hyperforge_nucliadb-1.0.0.post108 → hyperforge_nucliadb-1.0.0.post113}/src/hyperforge_nucliadb/driver.py

@@ -303,9 +303,13 @@ class NucliaDBDriver(Driver):
                 result.append(word)
         return " ".join(result)
 
-    async def ask(self, item: AskRequest, headers={}) -> SyncAskResponse:
+    async def ask(
+        self, item: AskRequest, headers: dict[str, str] | None = None
+    ) -> SyncAskResponse:
+        request_headers = httpx.Headers(headers)
+        request_headers["X-NDB-Client"] = "agentic"
         return await self.driver.ask(
-            kbid=self.config.kbid, content=item, headers=headers
+            kbid=self.config.kbid, content=item, headers=dict(request_headers)
         )
 
     async def find(
@@ -313,6 +317,7 @@ class NucliaDBDriver(Driver):
     ) -> KnowledgeboxFindResults:
         return await self.driver.find(
             kbid=self.config.kbid,
+            headers={"X-NDB-Client": "agentic"},
             content=FindRequest(
                 query=q,
                 resource_filters=rids,
@@ -326,6 +331,7 @@ class NucliaDBDriver(Driver):
         return await self.driver.find(
             kbid=self.config.kbid,
             content=q,
+            headers={"X-NDB-Client": "agentic"},
         )
 
     async def graph_relations(

{hyperforge_nucliadb-1.0.0.post108 → hyperforge_nucliadb-1.0.0.post113}/src/hyperforge_nucliadb.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperforge_nucliadb
-Version: 1.0.0.post108
+Version: 1.0.0.post113
 Summary: NucliaDB Hyperforge agent
 Author-email: Nuclia <nucliadb@nuclia.com>
 License-Expression: Apache-2.0
@@ -25,3 +25,13 @@ Basic ASK - Basic initial agent
 Advanced ASK (deprecated)
 ASK (experimental)
 Sync (Sync Service oauth linked)
+
+## Client identification
+
+NucliaDB `/ask` and `/find` requests made by these agents use
+`X-NDB-Client: agentic`, including when invoked as tools by a smart agent in a
+RAO workflow. The Sync driver inherits the same behavior. Other request headers
+are preserved, and caller-provided headers are not modified.
+
+Workflow memory searches through `/find` also use the `agentic` client type.
+The receiving NucliaDB API must support the `agentic` client type.

{hyperforge_nucliadb-1.0.0.post108 → hyperforge_nucliadb-1.0.0.post113}/src/hyperforge_nucliadb.egg-info/SOURCES.txt

@@ -35,5 +35,6 @@ src/hyperforge_nucliadb/sync/config_driver.py
 src/hyperforge_nucliadb/sync/driver.py
 tests/test_ask_utils.py
 tests/test_driver.py
+tests/test_facets_count.py
 tests/test_nucliadb.py
 tests/test_sync.py

hyperforge_nucliadb-1.0.0.post113/tests/test_driver.py

@@ -0,0 +1,99 @@
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from nucliadb_models.search import AskRequest, FindRequest
+from nucliadb_sdk.v2 import NucliaDBAsync
+
+from hyperforge_nucliadb.driver import NucliaDBDriver
+from hyperforge_nucliadb.sync.driver import SyncDriver
+
+
+def make_driver(client, driver_type=NucliaDBDriver):
+    return driver_type.model_construct(
+        provider="nucliadb",
+        name="test",
+        config=SimpleNamespace(kbid="test-kb", filters=[]),
+        driver=client,
+        manager=SimpleNamespace(),
+        _synonyms=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_labels_uses_complete_labelsets_response():
+    client = AsyncMock()
+    client.get_labelsets.return_value = SimpleNamespace(
+        labelsets={
+            "type": SimpleNamespace(labels=[SimpleNamespace(title="report")]),
+            "topic": SimpleNamespace(labels=[SimpleNamespace(title="science")]),
+        }
+    )
+    driver = make_driver(client)
+
+    assert await driver.labels() == {"type": ["report"], "topic": ["science"]}
+
+    client.get_labelsets.assert_awaited_once_with(kbid="test-kb")
+    client.get_labelset.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("driver_type", [NucliaDBDriver, SyncDriver])
+@pytest.mark.parametrize("operation", ["ask", "find", "find_raw"])
+async def test_search_requests_use_agentic_client_type(driver_type, operation):
+    def handle(request: httpx.Request) -> httpx.Response:
+        endpoint = "ask" if operation == "ask" else "find"
+        assert request.url.path.endswith(f"/kb/test-kb/{endpoint}")
+        assert request.headers.get_list("x-ndb-client") == ["agentic"]
+        assert request.headers["x-test-header"] == "preserved"
+        assert json.loads(request.content)["query"] == "question"
+        result = {"resources": {}, "total": 0}
+        if operation == "ask":
+            result = {
+                "status": "success",
+                "answer": "answer",
+                "retrieval_results": result,
+            }
+        return httpx.Response(200, json=result)
+
+    client = NucliaDBAsync(
+        url="http://nucliadb.test/api",
+        headers={"X-NDB-Client": "api", "x-test-header": "preserved"},
+        _httpx_transport=httpx.MockTransport(handle),
+    )
+    driver = make_driver(client, driver_type)
+
+    async with client.session:
+        if operation == "ask":
+            result = await driver.ask(AskRequest(query="question"))
+            assert result.answer == "answer"
+        elif operation == "find":
+            result = await driver.find("question")
+            assert result.total == 0
+        else:
+            result = await driver.find_raw(FindRequest(query="question"))
+            assert result.total == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "client_header", ["X-NDB-Client", "x-ndb-client", "X-NdB-ClIeNt"]
+)
+async def test_ask_preserves_caller_headers_without_mutating_them(client_header):
+    client = AsyncMock()
+    driver = make_driver(client)
+    headers = {client_header: "widget", "X-Synchronous": "true"}
+    original_headers = headers.copy()
+    request = AskRequest(query="question")
+
+    await driver.ask(request, headers=headers)
+
+    kwargs = client.ask.await_args.kwargs
+    sent_headers = httpx.Headers(kwargs["headers"])
+    assert sent_headers.get_list("x-ndb-client") == ["agentic"]
+    assert sent_headers["X-Synchronous"] == "true"
+    assert kwargs["kbid"] == "test-kb"
+    assert kwargs["content"] is request
+    assert headers == original_headers

hyperforge_nucliadb-1.0.0.post113/tests/test_facets_count.py

@@ -0,0 +1,72 @@
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from hyperforge.models import Context, Source
+
+from hyperforge_nucliadb.basic_ask_agent import BasicAskAgent
+from hyperforge_nucliadb.basic_ask_config import BasicAskAgentConfig
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("label_sets", [[], ["topic"]])
+async def test_facets_count_handles_label_selection(mocker, label_sets):
+    agent = BasicAskAgent(BasicAskAgentConfig(sources=["kb"]), agent_id="facets-agent")
+    source = Source.model_construct(id="kb")
+    mocker.patch(
+        "hyperforge_nucliadb.basic_ask_agent.choose_source",
+        new=AsyncMock(return_value=[source]),
+    )
+    driver = Mock(
+        labels=AsyncMock(return_value={"topic": ["science"]}),
+        field_labels=AsyncMock(return_value=({"topic": {"science": 2}}, 2)),
+    )
+    mocker.patch(
+        "hyperforge_nucliadb.basic_ask_agent.get_ndb_driver", return_value=driver
+    )
+    memory = Mock(original_question_uuid="question-id", add_step=AsyncMock())
+    manager = Mock(
+        execute_json=AsyncMock(
+            return_value=(
+                {"label_sets": label_sets, "reasoning": "Label selection"},
+                1,
+                2,
+            )
+        ),
+        execute=AsyncMock(return_value=("There are 2 science documents.", 3, 4, 0)),
+    )
+
+    contexts = await agent.facets_count(memory, manager, question="How many?")
+
+    assert len(contexts) == 1
+    context = contexts[0]
+    assert isinstance(context, Context)
+    assert context.agent_id == "facets-agent"
+    assert context.original_question_uuid == "question-id"
+    assert context.actual_question_uuid is None
+    assert context.question == "How many?"
+    assert context.source == "kb"
+    assert context.agent == "basic_ask_facets"
+    assert context.title == "Faceted search on kb Knowledge Box"
+    memory.add_step.assert_awaited_once()
+    step = memory.add_step.call_args.kwargs
+    assert step["step_value"] == "Label selection"
+    assert step["step_agent_path"] == "/context/facets-agent/facets_count"
+
+    if label_sets:
+        assert context.missing is None
+        assert len(context.chunks) == 1
+        assert context.chunks[0].chunk_id == "facets_count_result-0"
+        assert context.chunks[0].text == "There are 2 science documents."
+        driver.field_labels.assert_awaited_once_with(labelsets=label_sets)
+        manager.execute.assert_awaited_once()
+        assert step["step_reason"] == "Faceted search performed"
+        assert step["input_nuclia_tokens"] == 4
+        assert step["output_nuclia_tokens"] == 6
+    else:
+        assert context.missing == "How many?"
+        assert context.chunks == []
+        driver.field_labels.assert_not_awaited()
+        manager.execute.assert_not_awaited()
+        assert step["step_reason"] == "Faceted search skipped"
+        assert step["input_nuclia_tokens"] == 1
+        assert step["output_nuclia_tokens"] == 2

hyperforge_nucliadb-1.0.0.post108/README.md

@@ -1,6 +0,0 @@
-# NucliaDB Hyperforge agents
-
-Basic ASK - Basic initial agent
-Advanced ASK (deprecated)
-ASK (experimental)
-Sync (Sync Service oauth linked)

hyperforge_nucliadb-1.0.0.post108/tests/test_driver.py

@@ -1,34 +0,0 @@
-from types import SimpleNamespace
-from unittest.mock import AsyncMock
-
-import pytest
-
-from hyperforge_nucliadb.driver import NucliaDBDriver
-
-
-def make_driver(client):
-    return NucliaDBDriver.model_construct(
-        provider="nucliadb",
-        name="test",
-        config=SimpleNamespace(kbid="test-kb"),
-        driver=client,
-        manager=SimpleNamespace(),
-        _synonyms=None,
-    )
-
-
-@pytest.mark.asyncio
-async def test_labels_uses_complete_labelsets_response():
-    client = AsyncMock()
-    client.get_labelsets.return_value = SimpleNamespace(
-        labelsets={
-            "type": SimpleNamespace(labels=[SimpleNamespace(title="report")]),
-            "topic": SimpleNamespace(labels=[SimpleNamespace(title="science")]),
-        }
-    )
-    driver = make_driver(client)
-
-    assert await driver.labels() == {"type": ["report"], "topic": ["science"]}
-
-    client.get_labelsets.assert_awaited_once_with(kbid="test-kb")
-    client.get_labelset.assert_not_awaited()