nullprotocol 0.2.0__tar.gz → 0.3.0__tar.gz

{nullprotocol-0.2.0 → nullprotocol-0.3.0}/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.0
+
+- Add images to all four sync/async operations, with HTTPS URL validation, explicit model capability refusals and unchanged text requests.
+
 ## 0.2.0 — 2026-11-06
 
 - Agent and Space Knowledge management, including source CRUD, state, preparation retry, connections and embedding usage.

{nullprotocol-0.2.0 → nullprotocol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nullprotocol
-Version: 0.2.0
+Version: 0.3.0
 Summary: Focused AI tasks with managed context, Knowledge and observable results
 Project-URL: Homepage, https://nullprotocol.ai
 Project-URL: Documentation, https://nullprotocol.ai/docs/python
@@ -266,3 +266,17 @@ mypy src
 ```
 
 Tests use a scripted HTTP fixture, not paid providers. The workspace integration proof also runs this client against the actual API/gateway and an isolated PostgreSQL database with scripted generation/embeddings. These checks verify integration, not model accuracy.
+
+## Photo input
+
+```python
+result = agent.extract(
+    "Identify the landmark.",
+    {"landmark": "string"},
+    images=["https://images.unsplash.com/photo-1502602898657-3e91760cbb34?w=800&q=80"],
+)
+```
+
+Use the loaded agent inside your client context. All four operations support up to four reachable HTTPS photo URLs of at most 2048 UTF-16 characters. Async clients accept the same keyword. Select a Vision-capable model. Empty text is allowed for photo-only input; validate still needs criteria and decide needs its actions. Inline base64, browser blob URLs and local files are not supported.
+
+History retains URLs, not immutable copies of remote images. Knowledge uses a text query, not the photo or its URL; supply an explicit query for a photo-only search. Generation usage includes provider-reported image tokens. The gateway conservatively holds credit against the model context ceiling for photo calls, settles actual reported usage and releases the unused reserve. [Photo guide](https://nullprotocol.ai/docs/images?lang=python).

{nullprotocol-0.2.0 → nullprotocol-0.3.0}/README.md

@@ -236,3 +236,17 @@ mypy src
 ```
 
 Tests use a scripted HTTP fixture, not paid providers. The workspace integration proof also runs this client against the actual API/gateway and an isolated PostgreSQL database with scripted generation/embeddings. These checks verify integration, not model accuracy.
+
+## Photo input
+
+```python
+result = agent.extract(
+    "Identify the landmark.",
+    {"landmark": "string"},
+    images=["https://images.unsplash.com/photo-1502602898657-3e91760cbb34?w=800&q=80"],
+)
+```
+
+Use the loaded agent inside your client context. All four operations support up to four reachable HTTPS photo URLs of at most 2048 UTF-16 characters. Async clients accept the same keyword. Select a Vision-capable model. Empty text is allowed for photo-only input; validate still needs criteria and decide needs its actions. Inline base64, browser blob URLs and local files are not supported.
+
+History retains URLs, not immutable copies of remote images. Knowledge uses a text query, not the photo or its URL; supply an explicit query for a photo-only search. Generation usage includes provider-reported image tokens. The gateway conservatively holds credit against the model context ceiling for photo calls, settles actual reported usage and releases the unused reserve. [Photo guide](https://nullprotocol.ai/docs/images?lang=python).

nullprotocol-0.3.0/examples/photos.py

@@ -0,0 +1,26 @@
+"""Run a saved Vision agent. Set NULLPROTOCOL_KEY on your backend."""
+
+import os
+
+from nullprotocol import NullProtocol
+
+with NullProtocol() as client:
+    agent = client.load(os.environ.get("AGENT_ID", "photo-reader"))
+    result = agent.extract(
+        "Identify the landmark in the photo.",
+        {"landmark": "string"},
+        images=[
+            os.environ.get(
+                "PHOTO_URL",
+                "https://images.unsplash.com/photo-1502602898657-3e91760cbb34?w=800&q=80",
+            )
+        ],
+    )
+    if not result.success:
+        print(result.error_code, result.error)
+        raise SystemExit(1)
+    print(result.data)
+    print(result.usage)
+    if result.history_error:
+        print("History was not saved:", result.history_error)
+        raise SystemExit(1)

{nullprotocol-0.2.0 → nullprotocol-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nullprotocol"
-version = "0.2.0"
+version = "0.3.0"
 description = "Focused AI tasks with managed context, Knowledge and observable results"
 readme = "README.md"
 requires-python = ">=3.10"

{nullprotocol-0.2.0 → nullprotocol-0.3.0}/src/nullprotocol/_agent.py

@@ -184,9 +184,10 @@ class Agent(AgentState):
         knowledge: Knowledge | None,
         context_keys: list[str] | None,
         idempotency_key: str | None,
+        images: list[str] | None = None,
     ) -> Result[Any]:
         task_id = self._task_id(idempotency_key)
-        body = operation_payload(operation, values, self.scope, knowledge, context_keys)
+        body = operation_payload(operation, values, self.scope, knowledge, context_keys, images)
         return _result(
             self._transport.request(
                 "POST",
@@ -203,12 +204,18 @@ class Agent(AgentState):
         data: Any,
         schema: dict[str, Any],
         *,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
     ) -> Result[Any]:
         return self._run(
-            "extract", {"data": data, "schema": schema}, knowledge, context_keys, idempotency_key
+            "extract",
+            {"data": data, "schema": schema},
+            knowledge,
+            context_keys,
+            idempotency_key,
+            images,
         )
 
     def summarize(
@@ -217,6 +224,7 @@ class Agent(AgentState):
         *,
         max_length: int = 200,
         focus: str | None = None,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
@@ -227,6 +235,7 @@ class Agent(AgentState):
             knowledge,
             context_keys,
             idempotency_key,
+            images,
         )
 
     def validate(
@@ -235,6 +244,7 @@ class Agent(AgentState):
         subject: Any,
         *,
         reference: Any = _UNSET,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
@@ -245,6 +255,7 @@ class Agent(AgentState):
             knowledge,
             context_keys,
             idempotency_key,
+            images,
         )
 
     def decide(
@@ -252,6 +263,7 @@ class Agent(AgentState):
         context: Any,
         actions: list[ActionChoice],
         *,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
@@ -264,6 +276,7 @@ class Agent(AgentState):
             _knowledge_for_decision(original, values, knowledge),
             context_keys,
             idempotency_key,
+            images,
         )
         return self._remember(result, original)
 
@@ -379,9 +392,10 @@ class AsyncAgent(AgentState):
         knowledge: Knowledge | None,
         context_keys: list[str] | None,
         idempotency_key: str | None,
+        images: list[str] | None = None,
     ) -> Result[Any]:
         task_id = self._task_id(idempotency_key)
-        body = operation_payload(operation, values, self.scope, knowledge, context_keys)
+        body = operation_payload(operation, values, self.scope, knowledge, context_keys, images)
         return _result(
             await self._transport.request(
                 "POST",
@@ -398,12 +412,18 @@ class AsyncAgent(AgentState):
         data: Any,
         schema: dict[str, Any],
         *,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
     ) -> Result[Any]:
         return await self._run(
-            "extract", {"data": data, "schema": schema}, knowledge, context_keys, idempotency_key
+            "extract",
+            {"data": data, "schema": schema},
+            knowledge,
+            context_keys,
+            idempotency_key,
+            images,
         )
 
     async def summarize(
@@ -412,6 +432,7 @@ class AsyncAgent(AgentState):
         *,
         max_length: int = 200,
         focus: str | None = None,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
@@ -422,6 +443,7 @@ class AsyncAgent(AgentState):
             knowledge,
             context_keys,
             idempotency_key,
+            images,
         )
 
     async def validate(
@@ -430,6 +452,7 @@ class AsyncAgent(AgentState):
         subject: Any,
         *,
         reference: Any = _UNSET,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
@@ -440,6 +463,7 @@ class AsyncAgent(AgentState):
             knowledge,
             context_keys,
             idempotency_key,
+            images,
         )
 
     async def decide(
@@ -447,6 +471,7 @@ class AsyncAgent(AgentState):
         context: Any,
         actions: list[ActionChoice],
         *,
+        images: list[str] | None = None,
         knowledge: Knowledge | None = None,
         context_keys: list[str] | None = None,
         idempotency_key: str | None = None,
@@ -459,6 +484,7 @@ class AsyncAgent(AgentState):
             _knowledge_for_decision(original, values, knowledge),
             context_keys,
             idempotency_key,
+            images,
         )
         return self._remember(result, original)
 

{nullprotocol-0.2.0 → nullprotocol-0.3.0}/src/nullprotocol/_common.py

@@ -6,6 +6,7 @@ from copy import deepcopy
 from dataclasses import dataclass
 from threading import Lock
 from typing import Any, TypeVar
+from urllib.parse import urlsplit
 from uuid import UUID, uuid4
 from weakref import WeakKeyDictionary, WeakValueDictionary
 
@@ -60,6 +61,7 @@ def operation_payload(
     scope: str | None,
     knowledge: Knowledge | None,
     context_keys: list[str] | None,
+    images: list[str] | None = None,
 ) -> dict[str, Any]:
     body = {"operation": operation, **values}
     if scope is not None:
@@ -85,6 +87,17 @@ def operation_payload(
         if not isinstance(context_keys, list) or len(context_keys) > 16:
             raise ValueError("context_keys must be a list of at most 16 keys.")
         body["contextKeys"] = [identifier(key, "context key") for key in context_keys]
+    if images is not None:
+        if not isinstance(images, list) or len(images) > 4:
+            raise ValueError("images must be a list of at most four HTTPS photo URLs.")
+        for address in images:
+            if not isinstance(address, str) or utf16_length(address) > 2048:
+                raise ValueError("Each photo needs an HTTPS URL of at most 2048 characters.")
+            url = urlsplit(address)
+            if url.scheme != "https" or not url.hostname or url.username or url.password:
+                raise ValueError("Photo URLs must use HTTPS without embedded credentials.")
+        if images:
+            body["images"] = list(images)
     if len(json_body(body)) > 131072:
         raise ValueError("The HTTP operation body exceeds 131072 UTF-8 bytes.")
     return body

nullprotocol-0.3.0/tests/test_images.py

@@ -0,0 +1,67 @@
+import asyncio
+import json
+
+import httpx
+import pytest
+
+from nullprotocol import AsyncNullProtocol, NullProtocol
+
+PHOTO = "https://images.example.test/mug.jpg"
+
+
+def test_photos_survive_every_operation_and_idempotency(api):
+    with NullProtocol(
+        key="fixture", http_client=httpx.Client(transport=httpx.MockTransport(api))
+    ) as client:
+        agent = client.load("support")
+        images = [PHOTO]
+        assert agent.extract("", {"days": "number"}, images=images).success
+        assert agent.summarize("Describe the mug.", images=images).success
+        assert agent.validate("There is damage.", "", images=images).success
+        assert agent.decide("What next?", ["send_message"], images=images).success
+        agent.extract("", {"days": "number"}, images=images, idempotency_key="photo-42")
+        agent.extract("", {"days": "number"}, images=images, idempotency_key="photo-42")
+        assert api.model_calls == 5
+    bodies = [json.loads(r.content) for r in api.requests if r.url.path.endswith("/run")]
+    assert all(body["images"] == [PHOTO] for body in bodies)
+    assert bodies[0]["data"] == ""
+
+
+@pytest.mark.parametrize(
+    "images",
+    [
+        "photo.jpg",
+        ["http://example.test/photo.jpg"],
+        ["data:image/png;base64,AAAA"],
+        ["https://user:password@example.test/photo.jpg"],
+        [PHOTO] * 5,
+    ],
+)
+def test_invalid_photos_never_reach_api(api, images):
+    with NullProtocol(
+        key="fixture", http_client=httpx.Client(transport=httpx.MockTransport(api))
+    ) as client:
+        agent = client.load("support")
+        before = len(api.requests)
+        with pytest.raises(ValueError):
+            agent.extract("", {"days": "number"}, images=images)
+        assert len(api.requests) == before
+
+
+def test_async_photos(api):
+    async def run():
+        async with AsyncNullProtocol(
+            key="fixture", http_client=httpx.AsyncClient(transport=httpx.MockTransport(api))
+        ) as client:
+            agent = await client.load("support")
+            assert (await agent.extract("", {"days": "number"}, images=[PHOTO])).success
+            assert (await agent.summarize("Describe.", images=[PHOTO])).success
+            assert (await agent.validate("Damaged.", "", images=[PHOTO])).success
+            assert (await agent.decide("Next?", ["send_message"], images=[PHOTO])).success
+
+    asyncio.run(run())
+    assert all(
+        json.loads(r.content)["images"] == [PHOTO]
+        for r in api.requests
+        if r.url.path.endswith("/run")
+    )