interfaze 1.0.1__py3-none-any.whl

interfaze/__init__.py

@@ -0,0 +1,69 @@
+"""Official Interfaze SDK for Python."""
+
+from __future__ import annotations
+
+from openai import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    OpenAIError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+
+from . import _inputs as inputs
+from ._client import AsyncInterfaze, Interfaze
+from ._constants import GUARD_CODES, INTERFAZE_BASE_URL, INTERFAZE_MODEL, TASK_NAMES
+from ._errors import InterfazeError
+from ._schema import empty_task_schema, response_format
+from ._stream import AsyncInterfazeStream, InterfazeStream
+from ._types import (
+    GuardCode,
+    InterfazeChatCompletion,
+    Precontext,
+    ReasoningEffort,
+    TaskName,
+)
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "Interfaze",
+    "AsyncInterfaze",
+    "InterfazeError",
+    "InterfazeChatCompletion",
+    "InterfazeStream",
+    "AsyncInterfazeStream",
+    "Precontext",
+    "TaskName",
+    "GuardCode",
+    "ReasoningEffort",
+    "response_format",
+    "empty_task_schema",
+    "inputs",
+    "TASK_NAMES",
+    "GUARD_CODES",
+    "INTERFAZE_MODEL",
+    "INTERFAZE_BASE_URL",
+    # openai re-exports
+    "OpenAIError",
+    "APIError",
+    "APIStatusError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "BadRequestError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "InternalServerError",
+    "PermissionDeniedError",
+    "UnprocessableEntityError",
+]

interfaze/_chat.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Literal, Optional, Union, cast, overload
+
+from openai import AsyncOpenAI, AsyncStream, OpenAI, Stream
+from openai.types.chat import ChatCompletion, ChatCompletionChunk, ParsedChatCompletion
+
+from ._constants import INTERFAZE_MODEL
+from ._errors import InterfazeError
+from ._guard import guard_tag
+from ._schema import empty_task_schema
+from ._stream import AsyncInterfazeStream, InterfazeStream, strip_json_fence
+from ._types import GuardCode, InterfazeChatCompletion, TaskName
+
+
+def _is_non_empty_schema(rf: Any) -> bool:
+    schema = (rf or {}).get("json_schema", {}).get("schema", {}) if isinstance(rf, dict) else {}
+    props = schema.get("properties") if isinstance(schema, dict) else None
+    return bool(props)
+
+
+def prepare(
+    messages: Iterable[Any],
+    model: Optional[str],
+    task: Optional[TaskName],
+    guard: Optional[List[GuardCode]],
+    response_format: Optional[Dict[str, Any]],
+) -> "tuple[List[Any], str, Optional[Dict[str, Any]], bool]":
+    rf = response_format
+    if task:
+        if rf and _is_non_empty_schema(rf):
+            raise InterfazeError(
+                "A non-empty `response_format` cannot be combined with `task` "
+                "(Interfaze runs tasks with raw output)."
+            )
+        rf = empty_task_schema()
+    tags = " ".join(
+        t for t in (f"<task>{task}</task>" if task else None, guard_tag(guard) if guard else None) if t
+    )
+    msgs = list(messages)
+    if tags:
+        idx = next(
+            (i for i, m in enumerate(msgs) if isinstance(m, dict) and m.get("role") == "system"),
+            None,
+        )
+        if idx is not None and isinstance(msgs[idx].get("content"), str):
+            merged = dict(msgs[idx])
+            existing = merged["content"]
+            merged["content"] = f"{tags}\n{existing}" if existing else tags
+            msgs[idx] = merged
+        else:
+            msgs = [{"role": "system", "content": tags}, *msgs]
+    strip = isinstance(rf, dict) and rf.get("type") == "json_object"
+    return msgs, (model or INTERFAZE_MODEL), rf, strip
+
+
+def to_interfaze(raw: ChatCompletion, strip_fence: bool) -> InterfazeChatCompletion:
+    data = raw.model_dump()
+    if strip_fence:
+        try:
+            msg = data["choices"][0]["message"]
+            if isinstance(msg.get("content"), str):
+                msg["content"] = strip_json_fence(msg["content"])
+        except (KeyError, IndexError, TypeError):
+            pass
+    result = InterfazeChatCompletion.model_validate(data)
+    request_id = getattr(raw, "_request_id", None)
+    if request_id is not None:
+        result._request_id = request_id
+    return result
+
+
+class _CompletionsBase:
+    def _kwargs(
+        self,
+        messages: Iterable[Any],
+        model: Optional[str],
+        task: Optional[TaskName],
+        guard: Optional[List[GuardCode]],
+        response_format: Optional[Dict[str, Any]],
+        extra: Dict[str, Any],
+    ) -> "tuple[Dict[str, Any], bool]":
+        msgs, mdl, rf, strip = prepare(messages, model, task, guard, response_format)
+        kw: Dict[str, Any] = {"model": mdl, "messages": msgs, **extra}
+        if rf is not None:
+            kw["response_format"] = rf
+        return kw, strip
+
+
+class Completions(_CompletionsBase):
+    """`interfaze.chat.completions` (sync)."""
+
+    def __init__(self, client: OpenAI) -> None:
+        self._client = client
+
+    @overload
+    def create(
+        self,
+        *,
+        messages: Iterable[Any],
+        stream: Literal[False] = False,
+        model: str = ...,
+        task: Optional[TaskName] = ...,
+        guard: Optional[List[GuardCode]] = ...,
+        response_format: Optional[Dict[str, Any]] = ...,
+        **kwargs: Any,
+    ) -> InterfazeChatCompletion: ...
+    @overload
+    def create(
+        self,
+        *,
+        messages: Iterable[Any],
+        stream: Literal[True],
+        model: str = ...,
+        task: Optional[TaskName] = ...,
+        guard: Optional[List[GuardCode]] = ...,
+        response_format: Optional[Dict[str, Any]] = ...,
+        **kwargs: Any,
+    ) -> Stream[ChatCompletionChunk]: ...
+
+    def create(
+        self,
+        *,
+        messages: Iterable[Any],
+        stream: bool = False,
+        model: str = INTERFAZE_MODEL,
+        task: Optional[TaskName] = None,
+        guard: Optional[List[GuardCode]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> "Union[InterfazeChatCompletion, Stream[ChatCompletionChunk]]":
+        kw, strip = self._kwargs(messages, model, task, guard, response_format, kwargs)
+        if stream:
+            return cast(
+                "Stream[ChatCompletionChunk]", self._client.chat.completions.create(stream=True, **kw)
+            )
+        raw = self._client.chat.completions.create(**kw)
+        return to_interfaze(cast(ChatCompletion, raw), strip)
+
+    def stream(
+        self,
+        *,
+        messages: Iterable[Any],
+        model: str = INTERFAZE_MODEL,
+        task: Optional[TaskName] = None,
+        guard: Optional[List[GuardCode]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> InterfazeStream:
+        kw, strip = self._kwargs(messages, model, task, guard, response_format, kwargs)
+        return InterfazeStream(self._client, kw, strip)
+
+    def parse(
+        self,
+        *,
+        messages: Iterable[Any],
+        response_format: Any,
+        model: str = INTERFAZE_MODEL,
+        guard: Optional[List[GuardCode]] = None,
+        **kwargs: Any,
+    ) -> "ParsedChatCompletion[Any]":
+        """Structured output via a Pydantic model (delegates to the OpenAI client's ``parse``).
+
+        Interfaze extras (``vcache``/``precontext``) are present but untyped here; use ``create`` for
+        the typed extended completion.
+        """
+        msgs = prepare(messages, model, None, guard, None)[0]
+        return self._client.chat.completions.parse(
+            model=model, messages=msgs, response_format=response_format, **kwargs
+        )
+
+    @property
+    def with_raw_response(self) -> Any:
+        """Raw-HTTP escape hatch (delegates to the OpenAI client; bypasses task/guard preprocessing)."""
+        return self._client.chat.completions.with_raw_response
+
+    @property
+    def with_streaming_response(self) -> Any:
+        """Streaming raw-HTTP escape hatch (delegates to the OpenAI client)."""
+        return self._client.chat.completions.with_streaming_response
+
+
+class AsyncCompletions(_CompletionsBase):
+    """`interfaze.chat.completions` (async)."""
+
+    def __init__(self, client: AsyncOpenAI) -> None:
+        self._client = client
+
+    @overload
+    async def create(
+        self,
+        *,
+        messages: Iterable[Any],
+        stream: Literal[False] = False,
+        model: str = ...,
+        task: Optional[TaskName] = ...,
+        guard: Optional[List[GuardCode]] = ...,
+        response_format: Optional[Dict[str, Any]] = ...,
+        **kwargs: Any,
+    ) -> InterfazeChatCompletion: ...
+    @overload
+    async def create(
+        self,
+        *,
+        messages: Iterable[Any],
+        stream: Literal[True],
+        model: str = ...,
+        task: Optional[TaskName] = ...,
+        guard: Optional[List[GuardCode]] = ...,
+        response_format: Optional[Dict[str, Any]] = ...,
+        **kwargs: Any,
+    ) -> AsyncStream[ChatCompletionChunk]: ...
+
+    async def create(
+        self,
+        *,
+        messages: Iterable[Any],
+        stream: bool = False,
+        model: str = INTERFAZE_MODEL,
+        task: Optional[TaskName] = None,
+        guard: Optional[List[GuardCode]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> "Union[InterfazeChatCompletion, AsyncStream[ChatCompletionChunk]]":
+        kw, strip = self._kwargs(messages, model, task, guard, response_format, kwargs)
+        if stream:
+            return cast(
+                "AsyncStream[ChatCompletionChunk]",
+                await self._client.chat.completions.create(stream=True, **kw),
+            )
+        raw = await self._client.chat.completions.create(**kw)
+        return to_interfaze(cast(ChatCompletion, raw), strip)
+
+    def stream(
+        self,
+        *,
+        messages: Iterable[Any],
+        model: str = INTERFAZE_MODEL,
+        task: Optional[TaskName] = None,
+        guard: Optional[List[GuardCode]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> AsyncInterfazeStream:
+        kw, strip = self._kwargs(messages, model, task, guard, response_format, kwargs)
+        return AsyncInterfazeStream(self._client, kw, strip)
+
+    async def parse(
+        self,
+        *,
+        messages: Iterable[Any],
+        response_format: Any,
+        model: str = INTERFAZE_MODEL,
+        guard: Optional[List[GuardCode]] = None,
+        **kwargs: Any,
+    ) -> "ParsedChatCompletion[Any]":
+        """Structured output via a Pydantic model (delegates to the OpenAI client's ``parse``).
+
+        Interfaze extras (``vcache``/``precontext``) are present but untyped here; use ``create`` for
+        the typed extended completion.
+        """
+        msgs = prepare(messages, model, None, guard, None)[0]
+        return await self._client.chat.completions.parse(
+            model=model, messages=msgs, response_format=response_format, **kwargs
+        )
+
+    @property
+    def with_raw_response(self) -> Any:
+        """Raw-HTTP escape hatch (delegates to the OpenAI client; bypasses task/guard preprocessing)."""
+        return self._client.chat.completions.with_raw_response
+
+    @property
+    def with_streaming_response(self) -> Any:
+        """Streaming raw-HTTP escape hatch (delegates to the OpenAI client)."""
+        return self._client.chat.completions.with_streaming_response
+
+
+class Chat:
+    def __init__(self, client: OpenAI) -> None:
+        self.completions = Completions(client)
+
+
+class AsyncChat:
+    def __init__(self, client: AsyncOpenAI) -> None:
+        self.completions = AsyncCompletions(client)

interfaze/_client.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+from openai import AsyncOpenAI, OpenAI
+
+from ._chat import AsyncChat, Chat
+from ._constants import (
+    DEFAULT_TIMEOUT,
+    HEADER_ADMIN_KEY,
+    HEADER_BYPASS_CACHE,
+    HEADER_BYPASS_MOE,
+    HEADER_SHOW_ADDITIONAL_INFO,
+    INTERFAZE_BASE_URL,
+)
+from ._errors import InterfazeError
+from ._tasks import AsyncTasks, Tasks
+
+
+def _resolve_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("INTERFAZE_API_KEY")
+    if not key:
+        raise InterfazeError(
+            "Missing API key. Pass Interfaze(api_key=...) or set the INTERFAZE_API_KEY environment variable."
+        )
+    return key
+
+
+def _build_headers(
+    default_headers: Optional[Dict[str, str]],
+    show_additional_info: bool,
+    bypass_moe: bool,
+    bypass_cache: bool,
+    admin_key: Optional[str],
+) -> Dict[str, str]:
+    headers: Dict[str, str] = dict(default_headers or {})
+    if show_additional_info:
+        headers[HEADER_SHOW_ADDITIONAL_INFO] = "true"
+    if bypass_moe:
+        headers[HEADER_BYPASS_MOE] = "true"
+    if bypass_cache:
+        headers[HEADER_BYPASS_CACHE] = "true"
+    if admin_key:
+        headers[HEADER_ADMIN_KEY] = admin_key
+    return headers
+
+
+class Interfaze:
+    """Synchronous Interfaze client — a curated wrapper over ``openai.OpenAI``.
+
+    Exposes the endpoints Interfaze implements (``chat.completions``, ``models``) plus task
+    helpers (``tasks.*``). The underlying client is available at ``.openai``.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        show_additional_info: bool = False,
+        bypass_moe: bool = False,
+        bypass_cache: bool = False,
+        admin_key: Optional[str] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> None:
+        kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+        self.openai = OpenAI(
+            api_key=_resolve_key(api_key),
+            base_url=base_url or INTERFAZE_BASE_URL,
+            default_headers=_build_headers(
+                default_headers, show_additional_info, bypass_moe, bypass_cache, admin_key
+            ),
+            **kwargs,
+        )
+        self.chat = Chat(self.openai)
+        self.models = self.openai.models
+        self.tasks = Tasks(self.chat.completions)
+
+
+class AsyncInterfaze:
+    """Asynchronous Interfaze client — a curated wrapper over ``openai.AsyncOpenAI``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        show_additional_info: bool = False,
+        bypass_moe: bool = False,
+        bypass_cache: bool = False,
+        admin_key: Optional[str] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> None:
+        kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+        self.openai = AsyncOpenAI(
+            api_key=_resolve_key(api_key),
+            base_url=base_url or INTERFAZE_BASE_URL,
+            default_headers=_build_headers(
+                default_headers, show_additional_info, bypass_moe, bypass_cache, admin_key
+            ),
+            **kwargs,
+        )
+        self.chat = AsyncChat(self.openai)
+        self.models = self.openai.models
+        self.tasks = AsyncTasks(self.chat.completions)

interfaze/_constants.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+INTERFAZE_BASE_URL = "https://api.interfaze.ai/v1"
+INTERFAZE_MODEL = "interfaze-beta"
+DEFAULT_TIMEOUT = 900.0
+
+# Task names accepted in a <task>...</task> tag.
+TASK_NAMES = (
+    "ocr",
+    "object_detection",
+    "gui_detection",
+    "web_search",
+    "scraper",
+    "translate",
+    "speech_to_text",
+    "forecast",
+)
+
+# Guardrail categories (ALL enables everything).
+GUARD_CODES = (
+    "S1",
+    "S2",
+    "S3",
+    "S4",
+    "S5",
+    "S6",
+    "S7",
+    "S8",
+    "S9",
+    "S10",
+    "S11",
+    "S12",
+    "S13",
+    "S14",
+    "S1_IMAGE",
+    "S12_IMAGE",
+    "S15_IMAGE",
+    "ALL",
+)
+
+# Formats Interfaze rejects.
+BLACKLISTED_FORMATS = ("image/gif", "image/avif")
+
+# Interfaze control-plane headers.
+HEADER_SHOW_ADDITIONAL_INFO = "x-show-additional-info"
+HEADER_BYPASS_MOE = "x-bypass-moe"
+HEADER_BYPASS_CACHE = "x-bypass-cache"
+HEADER_ADMIN_KEY = "x-admin-key"

interfaze/_errors.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class InterfazeError(Exception):
+    """SDK-level (client-side) error.
+
+    HTTP errors surface as the openai error classes (openai.BadRequestError, etc.),
+    which are re-exported from the package root.
+    """

interfaze/_guard.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import List
+
+from ._constants import GUARD_CODES
+from ._errors import InterfazeError
+from ._types import GuardCode
+
+_VALID = set(GUARD_CODES)
+
+
+def guard_tag(codes: List[GuardCode]) -> str:
+    """Serialize guardrail categories into the ``<guard>...</guard>`` tag, validating codes."""
+    if not codes:
+        raise InterfazeError("`guard` must contain at least one code")
+    invalid = [c for c in codes if c not in _VALID]
+    if invalid:
+        raise InterfazeError(
+            f"Invalid guard code(s): {', '.join(invalid)}. Valid codes: {', '.join(GUARD_CODES)}"
+        )
+    return f"<guard>{', '.join(codes)}</guard>"

interfaze/_inputs.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import base64 as _base64
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from ._constants import BLACKLISTED_FORMATS
+from ._errors import InterfazeError
+
+BytesLike = Union[bytes, bytearray]
+
+_EXT_MIME = {
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "webp": "image/webp",
+    "gif": "image/gif",
+    "bmp": "image/bmp",
+    "heic": "image/heic",
+    "heif": "image/heif",
+    "pdf": "application/pdf",
+    "csv": "text/csv",
+    "tsv": "text/tab-separated-values",
+    "xml": "application/xml",
+    "json": "application/json",
+    "txt": "text/plain",
+    "md": "text/markdown",
+    "markdown": "text/markdown",
+    "yaml": "application/yaml",
+    "yml": "application/yaml",
+    "wav": "audio/wav",
+    "mp3": "audio/mpeg",
+    "m4a": "audio/mp4",
+    "ogg": "audio/ogg",
+    "flac": "audio/flac",
+    "mp4": "video/mp4",
+    "mov": "video/quicktime",
+    "webm": "video/webm",
+    "avi": "video/x-msvideo",
+    "mkv": "video/x-matroska",
+    "3gp": "video/3gpp",
+}
+
+
+def _mime_from_data_url(s: str) -> Optional[str]:
+    if s.startswith("data:"):
+        return s[5:].split(";")[0].split(",")[0] or None
+    return None
+
+
+def _ext_of(url_or_name: str) -> Optional[str]:
+    base = url_or_name.split("?")[0].split("#")[0]
+    return base.rsplit(".", 1)[-1].lower() if "." in base else None
+
+
+def _assert_allowed(mime: Optional[str]) -> None:
+    if mime and mime in BLACKLISTED_FORMATS:
+        raise InterfazeError(f'Format "{mime}" is not supported by Interfaze.')
+
+
+def data_url(data: BytesLike, mime_type: str) -> str:
+    """Build a base64 ``data:`` URI from raw bytes."""
+    _assert_allowed(mime_type)
+    return f"data:{mime_type};base64,{_base64.b64encode(bytes(data)).decode('ascii')}"
+
+
+def from_path(path: Union[str, Path]) -> str:
+    """Read a local file into a ``data:`` URI (mime by extension)."""
+    p = Path(path)
+    mime = _EXT_MIME.get((p.suffix.lstrip(".")).lower(), "application/octet-stream")
+    return data_url(p.read_bytes(), mime)
+
+
+def image(src: str) -> Dict[str, Any]:
+    """Image content part. ``src`` = https URL or ``data:`` URI."""
+    _assert_allowed(_mime_from_data_url(src) or _EXT_MIME.get(_ext_of(src) or ""))
+    return {"type": "image_url", "image_url": {"url": src}}
+
+
+def file(src: str, *, filename: Optional[str] = None, format: Optional[str] = None) -> Dict[str, Any]:
+    """File content part (pdf/csv/xml/json/text/audio/video/…). ``src`` = https URL or ``data:`` URI."""
+    mime = format or _mime_from_data_url(src) or _EXT_MIME.get(_ext_of(filename or src) or "")
+    _assert_allowed(mime)
+    f: Dict[str, Any] = {"file_data": src}
+    if filename:
+        f["filename"] = filename
+    if mime:
+        f["format"] = mime
+    return {"type": "file", "file": f}
+
+
+def audio(src: str, *, format: Optional[str] = None) -> Dict[str, Any]:
+    """Audio content part via ``input_audio`` (``audio_url`` is a dead field in Interfaze)."""
+    mime = _mime_from_data_url(src)
+    _assert_allowed(mime or _EXT_MIME.get(_ext_of(src) or ""))
+    fmt = format or (mime.split("/", 1)[-1] if mime else _ext_of(src)) or "wav"
+    return {"type": "input_audio", "input_audio": {"data": src, "format": fmt}}
+
+
+def video(src: str, *, filename: Optional[str] = None) -> Dict[str, Any]:
+    """Video content part — rides on the ``file`` part (there is no video content part)."""
+    return file(src, filename=filename)
+
+
+def auto_part(src: str, *, filename: Optional[str] = None, format: Optional[str] = None) -> Dict[str, Any]:
+    """Pick a content part by media type: image → image_url, audio → input_audio, else file."""
+    mime = format or _mime_from_data_url(src) or _EXT_MIME.get(_ext_of(filename or src) or "")
+    if mime and mime.startswith("image/"):
+        return image(src)
+    if mime and mime.startswith("audio/"):
+        return audio(src, format=format or mime.split("/", 1)[-1])
+    return file(src, filename=filename, format=format)

interfaze/_schema.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+JSONSchema = Dict[str, Any]
+
+
+def empty_task_schema(name: str = "empty_schema") -> Dict[str, Any]:
+    """Empty ``response_format`` for raw ``<task>`` runs."""
+    return {"type": "json_schema", "json_schema": {"name": name, "schema": {}}}
+
+
+def response_format(schema: JSONSchema, name: str = "response") -> Dict[str, Any]:
+    """Build a structured-output ``response_format`` from a JSON Schema.
+
+    Non-object roots are wrapped in a ``{"result": ...}`` object (structured output requires
+    an object root); the wrapped output is then under the ``result`` key.
+    """
+    return {"type": "json_schema", "json_schema": {"name": name, "schema": _ensure_object_root(schema)}}
+
+
+def _ensure_object_root(schema: JSONSchema) -> JSONSchema:
+    if isinstance(schema, dict) and schema.get("type") == "object":
+        return schema
+    return {
+        "type": "object",
+        "properties": {"result": schema},
+        "required": ["result"],
+        "additionalProperties": False,
+    }