trustgraph-base 2.7.3__tar.gz → 2.7.5__tar.gz

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustgraph-base
-Version: 2.7.3
+Version: 2.7.5
 Summary: TrustGraph provides a means to run a pipeline of flexible AI processing components in a flexible means to achieve a processing pipeline.
 Author-email: "trustgraph.ai" <security@trustgraph.ai>
 Project-URL: Homepage, https://github.com/trustgraph-ai/trustgraph

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/api/__init__.py

@@ -107,6 +107,7 @@ from .types import (
     AgentAnswer,
     RAGChunk,
     TextCompletionResult,
+    ImageToTextResult,
     ProvenanceEvent,
 )
 
@@ -186,6 +187,7 @@ __all__ = [
     "AgentAnswer",
     "RAGChunk",
     "TextCompletionResult",
+    "ImageToTextResult",
     "ProvenanceEvent",
 
     # Exceptions

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/api/async_flow.py

@@ -12,9 +12,10 @@ AsyncSocketClient instead.
 
 import aiohttp
 import json
+import base64
 from typing import Optional, Dict, Any, List
 
-from . types import TextCompletionResult
+from . types import TextCompletionResult, ImageToTextResult
 
 from . exceptions import ProtocolException, ApplicationException
 
@@ -476,6 +477,56 @@ class AsyncFlowInstance:
             model=result.get("model"),
         )
 
+    async def image_to_text(self, image: bytes, mime_type: str,
+                            prompt: Optional[str] = None,
+                            system: Optional[str] = None,
+                            **kwargs: Any) -> ImageToTextResult:
+        """
+        Describe an image using the image-to-text service (non-streaming).
+
+        Args:
+            image: Image content as bytes
+            mime_type: Image MIME type (e.g. "image/jpeg")
+            prompt: Optional user prompt (backend default used if None)
+            system: Optional system prompt
+            **kwargs: Additional service-specific parameters
+
+        Returns:
+            ImageToTextResult: Result with text, in_token, out_token, model
+
+        Example:
+            ```python
+            async_flow = await api.async_flow()
+            flow = async_flow.id("default")
+
+            with open("photo.jpg", "rb") as f:
+                result = await flow.image_to_text(
+                    image=f.read(),
+                    mime_type="image/jpeg",
+                )
+            print(result.text)
+            print(f"Tokens: {result.in_token} in, {result.out_token} out")
+            ```
+        """
+        # The image rides the JSON wire format as base64 text
+        request_data = {
+            "image": base64.b64encode(image).decode("utf-8"),
+            "mime_type": mime_type,
+        }
+        if prompt is not None:
+            request_data["prompt"] = prompt
+        if system is not None:
+            request_data["system"] = system
+        request_data.update(kwargs)
+
+        result = await self.request("image-to-text", request_data)
+        return ImageToTextResult(
+            text=result.get("description", ""),
+            in_token=result.get("in_token"),
+            out_token=result.get("out_token"),
+            model=result.get("model"),
+        )
+
     async def graph_rag(self, query: str, collection: str,
                         max_subgraph_size: int = 1000, max_subgraph_count: int = 5,
                         max_entity_distance: int = 3, **kwargs: Any) -> str:

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/api/async_socket_client.py

@@ -1,11 +1,12 @@
 
 import json
+import base64
 import asyncio
 import websockets
 from typing import Optional, Dict, Any, AsyncIterator, Union
 
-from . types import AgentThought, AgentObservation, AgentAnswer, RAGChunk, TextCompletionResult
-from . exceptions import ProtocolException, ApplicationException
+from . types import AgentThought, AgentObservation, AgentAnswer, RAGChunk, TextCompletionResult, ImageToTextResult
+from . exceptions import ProtocolException, ApplicationException, raise_from_error_dict
 
 
 class AsyncSocketClient:
@@ -353,6 +354,38 @@ class AsyncSocketFlowInstance:
             if isinstance(chunk, RAGChunk):
                 yield chunk
 
+    async def image_to_text(self, image: bytes, mime_type: str,
+                            prompt: Optional[str] = None,
+                            system: Optional[str] = None,
+                            **kwargs) -> ImageToTextResult:
+        """Describe an image using the image-to-text service (non-streaming).
+
+        Returns an ImageToTextResult with the description text and token counts.
+        """
+        # The image rides the JSON wire format as base64 text
+        request = {
+            "image": base64.b64encode(image).decode("utf-8"),
+            "mime_type": mime_type,
+        }
+        if prompt is not None:
+            request["prompt"] = prompt
+        if system is not None:
+            request["system"] = system
+        request.update(kwargs)
+
+        result = await self.client._send_request("image-to-text", self.flow_id, request)
+
+        # Service errors arrive inside the response body
+        if isinstance(result, dict) and result.get("error"):
+            raise_from_error_dict(result["error"])
+
+        return ImageToTextResult(
+            text=result.get("description", ""),
+            in_token=result.get("in_token"),
+            out_token=result.get("out_token"),
+            model=result.get("model"),
+        )
+
     async def graph_rag(self, query: str, collection: str,
                         max_subgraph_size: int = 1000, max_subgraph_count: int = 5,
                         max_entity_distance: int = 3, streaming: bool = False, **kwargs):

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/api/flow.py

@@ -11,7 +11,7 @@ import base64
 
 from .. knowledge import hash, Uri, Literal, QuotedTriple
 from .. schema import IRI, LITERAL, TRIPLE
-from . types import Triple, TextCompletionResult
+from . types import Triple, TextCompletionResult, ImageToTextResult
 from . exceptions import ProtocolException
 
 
@@ -296,6 +296,54 @@ class FlowInstance:
             model=result.get("model"),
         )
 
+    def image_to_text(self, image, mime_type, prompt=None, system=None):
+        """
+        Describe an image using the flow's image-to-text service.
+
+        Args:
+            image: Image content as bytes
+            mime_type: Image MIME type (e.g. "image/jpeg")
+            prompt: Optional user prompt (backend default used if None)
+            system: Optional system prompt
+
+        Returns:
+            ImageToTextResult: Result with text, in_token, out_token, model
+
+        Example:
+            ```python
+            flow = api.flow().id("default")
+            with open("photo.jpg", "rb") as f:
+                result = flow.image_to_text(
+                    image=f.read(),
+                    mime_type="image/jpeg",
+                )
+            print(result.text)
+            print(f"Tokens: {result.in_token} in, {result.out_token} out")
+            ```
+        """
+
+        # The image rides the JSON wire format as base64 text
+        input = {
+            "image": base64.b64encode(image).decode("utf-8"),
+            "mime_type": mime_type,
+        }
+        if prompt is not None:
+            input["prompt"] = prompt
+        if system is not None:
+            input["system"] = system
+
+        result = self.request(
+            "service/image-to-text",
+            input
+        )
+
+        return ImageToTextResult(
+            text=result.get("description", ""),
+            in_token=result.get("in_token"),
+            out_token=result.get("out_token"),
+            model=result.get("model"),
+        )
+
     def agent(self, question,state=None, group=None, history=None):
         """
         Execute an agent operation with reasoning and tool use capabilities.

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/api/socket_client.py

@@ -9,13 +9,14 @@ multiplexes requests by ID.
 """
 
 import json
+import base64
 import asyncio
 import websockets
 from websockets.exceptions import ConnectionClosed
 from typing import Optional, Dict, Any, Iterator, Union, List
 from threading import Lock
 
-from . types import AgentThought, AgentObservation, AgentAnswer, RAGChunk, StreamingChunk, ProvenanceEvent, TextCompletionResult
+from . types import AgentThought, AgentObservation, AgentAnswer, RAGChunk, StreamingChunk, ProvenanceEvent, TextCompletionResult, ImageToTextResult
 from . exceptions import ProtocolException, raise_from_error_dict
 
 
@@ -673,6 +674,38 @@ class SocketFlowInstance:
             if isinstance(chunk, RAGChunk):
                 yield chunk
 
+    def image_to_text(self, image: bytes, mime_type: str,
+                      prompt: Optional[str] = None,
+                      system: Optional[str] = None,
+                      **kwargs: Any) -> ImageToTextResult:
+        """Describe an image using the image-to-text service (non-streaming).
+
+        Returns an ImageToTextResult with the description text and token counts.
+        """
+        # The image rides the JSON wire format as base64 text
+        request = {
+            "image": base64.b64encode(image).decode("utf-8"),
+            "mime_type": mime_type,
+        }
+        if prompt is not None:
+            request["prompt"] = prompt
+        if system is not None:
+            request["system"] = system
+        request.update(kwargs)
+
+        result = self.client._send_request_sync("image-to-text", self.flow_id, request, False)
+
+        # Service errors arrive inside the response body
+        if isinstance(result, dict) and result.get("error"):
+            raise_from_error_dict(result["error"])
+
+        return ImageToTextResult(
+            text=result.get("description", ""),
+            in_token=result.get("in_token"),
+            out_token=result.get("out_token"),
+            model=result.get("model"),
+        )
+
     def graph_rag(
         self,
         query: str,

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/api/types.py

@@ -240,6 +240,24 @@ class TextCompletionResult:
     model: Optional[str] = None
     sources: List[Dict[str, str]] = dataclasses.field(default_factory=list)
 
+@dataclasses.dataclass
+class ImageToTextResult:
+    """
+    Result from an image-to-text request.
+
+    Returned by image_to_text(). Non-streaming only.
+
+    Attributes:
+        text: Text description of the image
+        in_token: Input token count (None if not available)
+        out_token: Output token count (None if not available)
+        model: Model identifier (None if not available)
+    """
+    text: Optional[str]
+    in_token: Optional[int] = None
+    out_token: Optional[int] = None
+    model: Optional[str] = None
+
 @dataclasses.dataclass
 class ProvenanceEvent:
     """

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/base/__init__.py

@@ -44,9 +44,11 @@ from . agent_client import AgentClientSpec
 from . structured_query_client import StructuredQueryClientSpec
 from . reranker_client import RerankerClientSpec
 from . reranker_service import RerankerService
+from . image_to_text_service import ImageToTextService, ImageDescriptionResult
 from . keyword_index_service import KeywordIndexService
 from . keyword_index_client import KeywordIndexClientSpec, KeywordIndexClient
 from . row_embeddings_query_client import RowEmbeddingsQueryClientSpec
 from . collection_config_handler import CollectionConfigHandler
 from . audit_publisher import AuditPublisher
+from . schema_compatibility import is_strict_mode_compatible
 

trustgraph_base-2.7.5/trustgraph/base/image_to_text_service.py

@@ -0,0 +1,170 @@
+"""
+Image-to-text description base class
+"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+import logging
+from prometheus_client import Histogram, Info
+
+from .. schema import ImageToTextRequest, ImageToTextResponse, Error
+from .. exceptions import TooManyRequests
+from .. base import FlowProcessor, ConsumerSpec, ProducerSpec, ParameterSpec
+
+# Module logger
+logger = logging.getLogger(__name__)
+
+default_ident = "image-to-text"
+default_concurrency = 1
+
+class ImageDescriptionResult:
+    def __init__(
+            self, text = None, in_token = None, out_token = None,
+            model = None,
+    ):
+        self.text = text
+        self.in_token = in_token
+        self.out_token = out_token
+        self.model = model
+    __slots__ = ["text", "in_token", "out_token", "model"]
+
+class ImageToTextService(FlowProcessor):
+    """
+    Extensible service processing image description requests.
+
+    This class handles the core logic of dispatching image-to-text
+    requests to integrated underlying vision model providers
+    (e.g. OpenAI).
+    """
+
+    def __init__(self, **params):
+
+        id = params.get("id", default_ident)
+        concurrency = params.get("concurrency", 1)
+
+        super(ImageToTextService, self).__init__(**params | {
+            "id": id,
+            "concurrency": concurrency,
+        })
+
+        self.register_specification(
+            ConsumerSpec(
+                name = "request",
+                schema = ImageToTextRequest,
+                handler = self.on_request,
+                concurrency = concurrency,
+            )
+        )
+
+        self.register_specification(
+            ProducerSpec(
+                name = "response",
+                schema = ImageToTextResponse
+            )
+        )
+
+        self.register_specification(
+            ParameterSpec(
+                name = "model",
+            )
+        )
+
+        if not hasattr(__class__, "image_to_text_metric"):
+            __class__.image_to_text_metric = Histogram(
+                'image_to_text_duration',
+                'Image-to-text duration (seconds)',
+                ["id", "flow"],
+                buckets=[
+                    0.25, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0,
+                    8.0, 9.0, 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0,
+                    17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0, 25.0,
+                    30.0, 35.0, 40.0, 45.0, 50.0, 60.0, 80.0, 100.0,
+                    120.0
+                ]
+            )
+
+        if not hasattr(__class__, "image_to_text_model_metric"):
+            __class__.image_to_text_model_metric = Info(
+                'image_to_text_model',
+                'Image-to-text model',
+                ["processor", "flow"]
+            )
+
+    async def on_request(self, msg, consumer, flow):
+
+        try:
+
+            request = msg.value()
+
+            # Sender-produced ID
+
+            id = msg.properties()["id"]
+
+            model = flow("model")
+
+            with __class__.image_to_text_metric.labels(
+                    id=self.id,
+                    flow=f"{flow.name}-{consumer.name}",
+            ).time():
+
+                response = await self.describe_image(
+                    request.image, request.mime_type,
+                    request.prompt, request.system, model,
+                )
+
+            await flow("response").send(
+                ImageToTextResponse(
+                    error=None,
+                    description=response.text,
+                    in_token=response.in_token,
+                    out_token=response.out_token,
+                    model=response.model,
+                ),
+                properties={"id": id}
+            )
+
+            __class__.image_to_text_model_metric.labels(
+                processor = self.id,
+                flow = flow.name
+            ).info({
+                "model": str(model) if model is not None else "",
+            })
+
+        except TooManyRequests as e:
+            raise e
+
+        except Exception as e:
+
+            # Apart from rate limits, treat all exceptions as unrecoverable
+
+            logger.error(f"Image-to-text service exception: {e}", exc_info=True)
+
+            logger.debug("Sending error response...")
+
+            await flow.producer["response"].send(
+                ImageToTextResponse(
+                    error=Error(
+                        type = "image-to-text-error",
+                        message = str(e),
+                    ),
+                    description=None,
+                    in_token=None,
+                    out_token=None,
+                    model=None,
+                ),
+                properties={"id": id}
+            )
+
+    @staticmethod
+    def add_args(parser: ArgumentParser) -> None:
+
+        parser.add_argument(
+            '-c', '--concurrency',
+            type=int,
+            default=default_concurrency,
+            help=f'Concurrent processing threads (default: {default_concurrency})'
+        )
+
+        FlowProcessor.add_args(parser)

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/base/llm_service.py

@@ -126,6 +126,8 @@ class LlmService(FlowProcessor):
 
             # Check if streaming is requested and supported
             streaming = getattr(request, 'streaming', False)
+            response_format = getattr(request, 'response_format', None)
+            schema = getattr(request, 'schema', None)
 
             if streaming and self.supports_streaming():
 
@@ -136,7 +138,8 @@ class LlmService(FlowProcessor):
                 ).time():
 
                     async for chunk in self.generate_content_stream(
-                        request.system, request.prompt, model, temperature
+                        request.system, request.prompt, model, temperature,
+                        response_format=response_format, schema=schema,
                     ):
                         await flow("response").send(
                             TextCompletionResponse(
@@ -159,7 +162,8 @@ class LlmService(FlowProcessor):
                 ).time():
 
                     response = await self.generate_content(
-                        request.system, request.prompt, model, temperature
+                        request.system, request.prompt, model, temperature,
+                        response_format=response_format, schema=schema,
                     )
 
                 await flow("response").send(
@@ -215,7 +219,10 @@ class LlmService(FlowProcessor):
         """
         return False
 
-    async def generate_content_stream(self, system, prompt, model=None, temperature=None):
+    async def generate_content_stream(
+        self, system, prompt, model=None, temperature=None,
+        response_format=None, schema=None,
+    ):
         """
         Override in subclass to implement streaming.
         Should yield LlmChunk objects.

trustgraph_base-2.7.5/trustgraph/base/schema_compatibility.py

@@ -0,0 +1,90 @@
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def is_strict_mode_compatible(schema):
+    """
+    Check whether a JSON schema is compatible with LLM structured-output
+    strict mode.  Returns True if the schema can be passed directly to
+    providers like OpenAI, vLLM, etc.
+    """
+
+    if schema is None:
+        return False
+
+    try:
+        _check_node(schema)
+        return True
+    except _IncompatibleSchema as e:
+        logger.debug("Schema not strict-mode compatible: %s", e)
+        return False
+
+
+class _IncompatibleSchema(Exception):
+    pass
+
+
+def _check_node(node):
+
+    if not isinstance(node, dict):
+        return
+
+    node_type = node.get("type")
+
+    if node_type == "object" or (
+        node_type is None and "properties" in node
+    ):
+        _check_object(node)
+
+    if node_type == "array":
+        items = node.get("items")
+        if items:
+            _check_node(items)
+
+    for keyword in ("oneOf", "anyOf", "allOf"):
+        for child in node.get(keyword, []):
+            _check_node(child)
+
+    _check_unsupported_constraints(node)
+
+
+def _check_object(node):
+
+    props = node.get("properties")
+    if props is None:
+        raise _IncompatibleSchema(
+            "object without properties (open-ended)"
+        )
+
+    if node.get("additionalProperties") is not False:
+        raise _IncompatibleSchema(
+            "object missing additionalProperties: false"
+        )
+
+    required = set(node.get("required", []))
+    for key in props:
+        if key not in required:
+            raise _IncompatibleSchema(
+                f"property '{key}' not in required"
+            )
+
+    for value in props.values():
+        _check_node(value)
+
+
+UNSUPPORTED_KEYWORDS = {
+    "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum",
+    "minLength", "maxLength", "pattern",
+    "minItems", "maxItems",
+    "minProperties", "maxProperties",
+}
+
+
+def _check_unsupported_constraints(node):
+    found = UNSUPPORTED_KEYWORDS & node.keys()
+    if found:
+        raise _IncompatibleSchema(
+            f"unsupported constraints: {', '.join(sorted(found))}"
+        )

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/base/text_completion_client.py

@@ -14,11 +14,15 @@ class TextCompletionResult:
 
 class TextCompletionClient(RequestResponse):
 
-    async def text_completion(self, system, prompt, timeout=600):
+    async def text_completion(
+        self, system, prompt, timeout=600,
+        response_format=None, schema=None,
+    ):
 
         resp = await self.request(
             TextCompletionRequest(
-                system = system, prompt = prompt, streaming = False
+                system=system, prompt=prompt, streaming=False,
+                response_format=response_format, schema=schema,
             ),
             timeout=timeout
         )
@@ -35,6 +39,7 @@ class TextCompletionClient(RequestResponse):
 
     async def text_completion_stream(
             self, system, prompt, handler, timeout=600,
+            response_format=None, schema=None,
     ):
         """
         Streaming text completion. `handler` is an async callable invoked
@@ -54,7 +59,8 @@ class TextCompletionClient(RequestResponse):
 
         final = await self.request(
             TextCompletionRequest(
-                system = system, prompt = prompt, streaming = True
+                system=system, prompt=prompt, streaming=True,
+                response_format=response_format, schema=schema,
             ),
             recipient=on_chunk,
             timeout=timeout,

trustgraph_base-2.7.5/trustgraph/base_version.py

@@ -0,0 +1 @@
+__version__ = "2.7.5"

{trustgraph_base-2.7.3 → trustgraph_base-2.7.5}/trustgraph/messaging/__init__.py

@@ -5,6 +5,7 @@ from .translators import *
 from .translators.agent import AgentRequestTranslator, AgentResponseTranslator
 from .translators.embeddings import EmbeddingsRequestTranslator, EmbeddingsResponseTranslator
 from .translators.text_completion import TextCompletionRequestTranslator, TextCompletionResponseTranslator
+from .translators.image_to_text import ImageToTextRequestTranslator, ImageToTextResponseTranslator
 from .translators.retrieval import (
     DocumentRagRequestTranslator, DocumentRagResponseTranslator,
     GraphRagRequestTranslator, GraphRagResponseTranslator
@@ -50,6 +51,12 @@ TranslatorRegistry.register_service(
     TextCompletionResponseTranslator()
 )
 
+TranslatorRegistry.register_service(
+    "image-to-text",
+    ImageToTextRequestTranslator(),
+    ImageToTextResponseTranslator()
+)
+
 TranslatorRegistry.register_service(
     "document-rag", 
     DocumentRagRequestTranslator(),