tessaract 0.1.0__py3-none-any.whl

tessaract/__init__.py

@@ -0,0 +1,16 @@
+from .client import Tessaract
+from .providers.openai_provider import OpenAIProvider
+from .tools.function import FunctionTool, InputSchema, Property
+from .types.input_types import FunctionToolResult, UserMessage
+from .types.request import ReasoningOptions
+
+__all__ = [ 
+    "FunctionTool",
+    "FunctionToolResult",
+    "InputSchema",
+    "OpenAIProvider",
+    "Property",
+    "ReasoningOptions",
+    "Tessaract",
+    "UserMessage"
+    ]

tessaract/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import Adapter
+
+__all__ = ["Adapter"]

tessaract/adapters/adapter.py

@@ -0,0 +1,55 @@
+from typing import Any, Literal
+
+from typing_extensions import Protocol
+
+from ..providers.provider import Provider
+from ..tools.function import InputSchema
+
+
+class UserMessageProtocol(Protocol):
+    role: Literal["user"] = "user"
+    content: str | list[dict]
+
+class FunctionToolResultProtocol(Protocol):
+    type: Literal["function_tool_result"] = "function_tool_result"
+    call_id: str
+    result: Any
+    is_error: bool = False
+
+class FunctionToolSchemaProtocol(Protocol):
+    name: str
+    description: str
+    input_schema: InputSchema | None
+    strict: bool | None = None
+    provider_options: dict[str, Any]
+
+class ReasoningParamsProtocol(Protocol):
+    effort: Literal["none", "minimal", "low", "medium", "high", "extra_high", "max"] | None = None
+    summary: Literal["concise", "auto", "detailed"] | None = None
+    mode: Literal["standard", "pro"] | None = None
+
+class ReasoningProtocol(Protocol):
+    type: Literal["reasoning"] = "reasoning"
+    text: str | None = None
+
+class Adapter:
+    def __init__(self, provider: Provider):
+        self._provider = provider
+
+    def map_input_message(self, item: UserMessageProtocol) -> Any:
+        raise NotImplementedError("not yet implemented...")
+
+    def map_tool_result(self, item: FunctionToolResultProtocol) -> Any:
+        raise NotImplementedError("not yet implemented...")
+
+    def map_function_schema(self, tools: list[FunctionToolSchemaProtocol]) -> list:
+        raise NotImplementedError("not yet implemented...")
+
+    def map_reasoning_params(self, item: ReasoningParamsProtocol) -> Any:
+        raise NotImplementedError("not yet implemented...")
+    
+    def map_reasoning(self, item: ReasoningProtocol) -> Any:
+        raise NotImplementedError("not yet implemented")
+
+
+

tessaract/adapters/openai/openai_adapter.py

@@ -0,0 +1,348 @@
+import json
+from collections.abc import Iterator, Sequence
+
+from openai import Omit
+from openai.types.shared_params import Reasoning as OpenAIReasoningParams
+
+from ...providers.openai_provider import OpenAIProvider
+from ...tools.function import InputSchema, Property
+from ...types.output_types import (
+    AssistantMessage,
+    FunctionCallOutputItem,
+    ProviderOutputItem,
+    OutputType,
+    ReasoningOutputItem,
+    TextOutputItem,
+)
+from ...types.request import Request
+from ...types.response import OpenAIResponse, ResponseError
+from ...types.streaming.event_types import (
+    CustomProviderEvent,
+    FunctionCallArgumentDeltaEvent,
+    OutputItemCompletedEvent,
+    ReasoningStartedEvent,
+    ReasoningSummaryDeltaEvent,
+    ReasoningTextDeltaEvent,
+    ResponseCompletedEvent,
+    ResponseFailedEvent,
+    ResponseStartedEvent,
+    StreamEventUnion,
+    TextDeltaEvent,
+    ToolCallStartedEvent,
+)
+from ..adapter import (
+    Adapter,
+    FunctionToolResultProtocol,
+    FunctionToolSchemaProtocol,
+    ReasoningParamsProtocol,
+    UserMessageProtocol,
+)
+
+
+class OpenAIAdapter(Adapter):
+    def __init__(self, provider: OpenAIProvider):
+        super().__init__(provider)
+        self._client = provider.client
+
+    def map_input_message(self, item: UserMessageProtocol):
+        return {
+            "role": item.role,
+            "content": item.content
+        }
+
+    def map_reasoning_params(self, reasoning: ReasoningParamsProtocol | None) -> OpenAIReasoningParams | Omit | None:
+        if reasoning is None:
+            return Omit()
+
+        native_reasoning: OpenAIReasoningParams = {}
+
+        if reasoning.mode is not None:
+            native_reasoning["mode"] = reasoning.mode
+
+        if reasoning.summary is not None:
+            native_reasoning["summary"] = reasoning.summary
+
+        if reasoning.effort is not None:
+            native_reasoning["effort"] = (
+                "xhigh" if reasoning.effort == "extra_high" else reasoning.effort
+            )
+
+        return native_reasoning
+
+    def _native_property(self, prop: Property) -> dict:
+        native: dict[str, object] = {"type": prop.type}
+
+        if prop.description is not None:
+            native["description"] = prop.description
+
+        if prop.enum is not None:
+            native["enum"] = prop.enum
+
+        if prop.items is not None:
+            native["items"] = self._native_property(prop.items)
+
+        if prop.properties is not None:
+            native["properties"] = {
+                name: self._native_property(nested)
+                for name, nested in prop.properties.items()
+            }
+
+        if prop.required is not None:
+            native["required"] = prop.required
+
+        # Strict mode requires additionalProperties: false on every object
+        if "object" in prop._types():
+            native["additionalProperties"] = prop.additionalProperties if prop.additionalProperties is not None else False
+
+        return native
+
+    def _native_tool_parameters(self, input_schema: InputSchema):
+        _properties = {
+            prop_name: self._native_property(prop_schema)
+            for prop_name, prop_schema in input_schema.properties.items()
+        }
+
+        return {
+            "type": input_schema.type,
+            "properties": _properties,
+            "required": input_schema.required,
+            "additionalProperties": input_schema.additionalProperties if input_schema.additionalProperties is not None else False
+        }
+
+    def  map_function_schema(self, tools: Sequence[FunctionToolSchemaProtocol]) -> list:
+
+        _native_tools_list = []
+        for tool in tools:
+            _native_tool_schema: dict[str, object] = {}
+
+            _native_tool_schema["type"] = "function"
+            _native_tool_schema["name"] = tool.name
+            _native_tool_schema["description"] = tool.description
+            _native_tool_schema["strict"] = tool.strict if tool.strict is not None else True
+
+            if tool.input_schema is not None:
+                _native_tool_schema["parameters"] = self._native_tool_parameters(tool.input_schema) if tool.input_schema is not None else None
+
+            canonical_keys = {
+                "type",
+                "name",
+                "description",
+                "strict",
+                "parameters"
+            }
+
+            extra_fields = {
+                key: value
+                for key, value in tool.provider_options.items()
+                if key not in canonical_keys
+            }
+            _native_tools_list.append({**extra_fields, **_native_tool_schema})
+        return _native_tools_list
+
+    def _is_content_parts(self, result) -> bool:
+        return isinstance(result, list) and all(
+            isinstance(part, dict) and "type" in part for part in result
+        )
+
+    def map_tool_result(self, item: FunctionToolResultProtocol):
+        # OpenAI has no error flag on function_call_output, so errors are marked in the output itself
+        if item.is_error:
+            output = json.dumps({"error": item.result}, default=str)
+
+        elif isinstance(item.result, str) or self._is_content_parts(item.result):
+            output = item.result
+
+        else:
+            output = json.dumps(item.result, default=str)
+
+        return {
+            "type": "function_call_output",
+            "call_id": item.call_id,
+            "output": output
+        }
+
+        
+    def _normalize_output_item(self, output_item) -> OutputType:
+        if output_item.type == "message" and (
+            output_item.content is None or any(
+                part.type != "output_text"
+                or bool(getattr(part, "annotations", []))
+                for part in output_item.content
+            )
+        ):
+            return ProviderOutputItem(raw=output_item, provider_type=output_item.type)
+        
+        match output_item.type:
+            case "message":
+                return AssistantMessage(
+                        raw=output_item,
+                        content=[
+                            TextOutputItem(
+                                raw=i,
+                                text=i.text,
+                                annotations=i.annotations
+                            )
+                            for i in output_item.content
+                        ]
+                    )
+
+            case "reasoning":
+                return ReasoningOutputItem(
+                    raw=output_item,
+                    id=output_item.id,
+                    content="".join(part.text for part in output_item.content),
+                    text="".join(part.text for part in output_item.summary)
+                ) 
+
+            case "function_call":
+                return FunctionCallOutputItem(
+                    raw=output_item,
+                    call_id=output_item.call_id,
+                    name=output_item.name,
+                    arguments=json.loads(output_item.arguments)
+                )
+
+            case _:
+                raise ValueError(f"Unsupported OpenAI output item type: {output_item.type!r}")
+
+
+    def _normalize_output(self, output_items) -> list[OutputType]:
+        return [self._normalize_output_item(item) for item in output_items]
+
+    def _normalize_stream_event(self, event):
+        match event.type:
+            case "response.created":
+                yield ResponseStartedEvent(
+                    raw_event=event
+                )
+
+            case "response.completed":
+                yield ResponseCompletedEvent(
+                    response=self._normalize_response(event.response),
+                    raw_event=event
+                )
+
+            case "response.failed":
+                response = self._normalize_response(event.response)
+                error = response.error or ResponseError(message="Response failed")
+                yield ResponseFailedEvent(
+                    message=error.message,
+                    error=error,
+                    response=response,
+                    raw_event=event
+                )
+
+            case "error":
+                yield ResponseFailedEvent(
+                    message=event.message,
+                    error=ResponseError(message=event.message, code=event.code),
+                    raw_event=event
+                )
+
+            case "response.output_item.added" if event.item.type == "function_call":
+                yield ToolCallStartedEvent(
+                    call_id=event.item.call_id,
+                    name=event.item.name,
+                    output_index=event.output_index,
+                    raw_event=event
+                )
+
+            case "response.output_text.delta":
+                yield TextDeltaEvent(
+                    delta=event.delta,
+                    provider="openai",
+                    output_index=event.output_index,
+                    content_index=event.content_index,
+                    raw_event=event
+                )
+
+            case "response.output_item.done":
+                yield OutputItemCompletedEvent(
+                    item=self._normalize_output_item(event.item),
+                    raw_event=event
+                )
+
+            case "response.reasoning_summary_text.delta":
+                yield ReasoningSummaryDeltaEvent(
+                    delta=event.delta,
+                    output_index=event.output_index,
+                    item_id=event.item_id,
+                    raw_event=event
+                )
+
+            case "response.reasoning_text.delta":
+                yield ReasoningTextDeltaEvent(
+                    delta=event.delta,
+                    output_index=event.output_index,
+                    item_id=event.item_id,
+                    raw_event=event
+                )
+
+            case "response.function_call_arguments.delta":
+                yield FunctionCallArgumentDeltaEvent(
+                    delta=event.delta,
+                    output_index=event.output_index,
+                    raw_event=event
+                )
+
+            case "response.reasoning_summary_part.added":
+                yield ReasoningStartedEvent(
+                    item_id=event.item_id,
+                    raw_event=event
+                )
+
+            case _:
+                yield CustomProviderEvent(
+                    type=event.type,
+                    raw_event=event
+                )
+
+
+    def _normalize_response(self, raw_response) -> OpenAIResponse:
+        return OpenAIResponse(
+            id=raw_response.id,
+            model=raw_response.model,
+            status=raw_response.status,
+            provider=self._provider,
+            output=self._normalize_output(raw_response.output),
+            error=ResponseError(message=raw_response.error.message, code=raw_response.error.code) if raw_response.error else None,
+            raw_response=raw_response
+        )
+
+    def _build_request_kwargs(self, request: Request):
+        canonical_params = {
+            "model": request.model,
+            "input": request.input,
+            "tools": self.map_function_schema(request.tools or []),
+            "reasoning": self.map_reasoning_params(request.reasoning), 
+        }
+
+        provider_options = dict(**request.provider_options or {})
+
+        extra_body = provider_options.get("extra_body")
+
+        if extra_body is not None:
+            provider_options["extra_body"] = {
+                key: value
+                for key, value in extra_body.items()
+                if key not in canonical_params
+            }
+
+
+        return {**provider_options, **canonical_params}
+
+    def generate_sync(self, request: Request) -> OpenAIResponse:
+
+        kwargs = self._build_request_kwargs(request)
+
+        _raw_response = self._client.responses.create(**kwargs, stream=False)
+
+        return self._normalize_response(_raw_response)
+
+    def generate_stream(self, request: Request) -> Iterator[StreamEventUnion]:
+    
+        kwargs = self._build_request_kwargs(request)
+
+        with self._client.responses.stream(**kwargs) as stream:
+            for raw_event in stream:
+                yield from self._normalize_stream_event(raw_event)

tessaract/client.py

@@ -0,0 +1,151 @@
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+from .providers import OpenAIProvider
+from .tools.function import FunctionTool
+from .types.input_types import InputType, UserMessage
+from .types.output_types import AssistantMessage, OutputItem
+from .types.request import ReasoningOptions, Request
+from .types.response import Response
+from .types.streaming.event_types import StreamEventUnion
+
+if TYPE_CHECKING:
+    from .adapters.openai.openai_adapter import OpenAIAdapter
+
+class Tessaract:
+    def __init__(self, providers: dict[str, OpenAIProvider]):
+        self.providers = providers
+        self.adapters: dict[str, "OpenAIAdapter" ] = {} # value should be a union of OpenAIAdapter | AnthropicAdapter once implemented
+        self.register_adapter()
+
+    def register_adapter(self):
+        for prefix, provider in self.providers.items():
+            if isinstance(provider, OpenAIProvider):
+                from .adapters.openai.openai_adapter import OpenAIAdapter
+                adapter = OpenAIAdapter(provider)
+            else:
+                raise NotImplementedError("not yet implemented")
+            self.adapters[prefix] = adapter
+
+    def _normalize_model_name(self, model: str):
+        model_prefix, separator, model_name = model.partition("/")
+
+        if not separator or not model_prefix or not model_name:
+            raise ValueError(
+                f"model must be of the form '<provider prefix>/<model name>', got {model!r}"
+            )
+
+        return (model_prefix, model_name)
+
+    def _build_request_model(
+        self,
+        model: str,
+        provider: str,
+        input: str | list[str | InputType],
+        reasoning: ReasoningOptions | None,
+        tools: list[FunctionTool],
+        request_options: dict[str, Any],
+        stream: bool
+    ) -> Request:
+
+        all_items = []
+        
+        if isinstance(input, str):
+            converted_item = UserMessage(content=input)
+            all_items.append(converted_item.raw(self.adapters[provider]))
+
+        else:
+            for message in input:
+                if isinstance(message, str):
+                    converted_item = UserMessage(content=message)
+                    all_items.append(converted_item.raw(self.adapters[provider]))
+                    
+                elif isinstance(message, InputType):
+                    all_items.append(message.raw(self.adapters[provider]))
+
+                elif isinstance(message, AssistantMessage):  # noqa: SIM114
+                    all_items.append(message.raw)
+
+                elif isinstance(message, OutputItem):
+                    all_items.append(message.raw)
+
+                else:
+                    raise TypeError(f"Unsupported input type: {type(message).__name__}")
+
+        return Request(
+            model=model,
+            input=all_items,
+            reasoning=reasoning,
+            tools=tools,
+            provider_options=request_options,
+            stream=stream
+        )
+
+    @overload
+    def send(
+            self, model: str, 
+            input: str | list[str | InputType],
+            stream: Literal[False],
+            reasoning: ReasoningOptions | None = None,
+            tools: list[FunctionTool] | None = None,
+            request_options: dict[str, Any] | None = None
+            ) -> Response: ...
+
+    @overload
+    def send(
+            self, model: str, 
+            input: str | list[str | InputType],
+            stream: Literal[True],
+            reasoning: ReasoningOptions | None = None,
+            tools: list[FunctionTool] | None = None,
+            request_options: dict[str, Any] | None = None
+            ) -> Iterator[StreamEventUnion]: ...
+
+    @overload
+    def send(
+        self,
+        model: str,
+        input: str | list[str | InputType],
+        stream: bool,
+        reasoning: ReasoningOptions | None = None,
+        tools: list[FunctionTool] | None = None,
+        request_options: dict[str, Any] | None = None,
+    ) -> Response | Iterator[StreamEventUnion]: ...
+
+
+    def send(
+            self, model: str, 
+            input: str | list[str | InputType],
+            stream: bool = False,
+            reasoning: ReasoningOptions | None = None,
+            tools: list[FunctionTool] | None = None,
+            request_options: dict[str, Any] | None = None
+            
+        ) -> Response | Iterator[StreamEventUnion]:
+
+        provider, model = self._normalize_model_name(model=model)
+
+        if provider not in self.providers:
+            raise ValueError("provider prefix must match registered provider in tessaract object")
+
+        _request_provider = self.providers[provider]
+
+        _tools = tools if tools is not None else []
+
+        # if reasoning is not None:
+        #     _reasoning = reasoning
+
+        _request_options = request_options if request_options is not None else {}
+
+        _tessaract_request = self._build_request_model(model=model, input=input, provider=provider, reasoning=reasoning, tools=_tools, request_options=_request_options, stream=stream)
+
+        if isinstance(_request_provider, OpenAIProvider):
+
+            adapter = self.adapters[provider]
+
+            if stream == True:
+                return adapter.generate_stream(request=_tessaract_request) 
+
+            return adapter.generate_sync(request=_tessaract_request)
+
+        raise NotImplementedError("Unsupported provider")

tessaract/providers/__init__.py

@@ -0,0 +1,7 @@
+from .openai_provider import OpenAIProvider
+from .provider import Provider
+
+__all__ = [
+    "OpenAIProvider",
+    "Provider"
+]

tessaract/providers/openai_provider.py

@@ -0,0 +1,35 @@
+import os
+from typing import TYPE_CHECKING, cast
+
+from .provider import Provider
+
+if TYPE_CHECKING:
+    from openai import OpenAI
+
+
+class OpenAIProvider(Provider):
+    def __post_init__(self) -> None:
+        try:
+            from openai import OpenAI
+        except ModuleNotFoundError as exc:
+            if exc.name != "openai":
+                raise
+            raise ImportError(
+                "OpenAI support requires the optional dependency. "
+                'Install it with: pip install "tessaract[openai]"'
+            ) from exc
+
+        if self.api_key is None:
+            self.api_key = os.environ.get("OPENAI_API_KEY")
+
+        if self.api_key is None:
+            raise ValueError(
+                "No OpenAI API key found. Pass api_key to OpenAIProvider "
+                "or set the OPENAI_API_KEY environment variable."
+            )
+
+        self._client = OpenAI(**self._client_kwargs())
+
+    @property
+    def client(self) -> "OpenAI":
+        return cast("OpenAI", self._client)

tessaract/providers/provider.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Provider:
+    api_key: str | None = None
+    base_url: str | None = None
+    timeout: float | None = None
+    max_retries: int | None = None
+    default_headers: dict[str, str] | None = None
+    default_query: dict[str, object] | None = None
+    _client: object | None = None
+    provider_args: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        raise NotImplementedError("not yet implemented")
+    
+    @property
+    def client(self):
+        raise NotImplementedError("not yet implemented")
+
+    def _client_kwargs(self) -> dict:
+        '''Keyword arguments for the SDK client: the typed fields that are set, overridden by provider_args.'''
+        typed_args = {
+            "api_key": self.api_key,
+            "base_url": self.base_url,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "default_headers": self.default_headers,
+            "default_query": self.default_query,
+        }
+
+        return {
+            **{key: value for key, value in typed_args.items() if value is not None},
+            **self.provider_args,
+        }

tessaract/tools/__init__.py

@@ -0,0 +1,7 @@
+from .function import FunctionTool, InputSchema, Property
+
+__all__ = [
+    "FunctionTool",
+    "InputSchema",
+    "Property"
+]