slimx 0.5.0__py3-none-any.whl

slimx/__init__.py

@@ -0,0 +1,99 @@
+"""SlimX — a slim, intuitive, lightweight library for calling LLMs.
+
+This top-level module keeps imports *lazy* to:
+- speed up imports
+- avoid provider bootstrapping side-effects at import time
+- prevent circular imports across `high`, `low`, and `providers`
+
+You can still write:
+
+    from slimx import llm, tool, Message
+
+The symbols resolve on first access.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, TYPE_CHECKING
+
+__version__ = "0.5.0"
+
+_LAZY: dict[str, tuple[str, str]] = {
+    # High-level
+    "llm": ("slimx.high.api", "llm"),
+    "allm": ("slimx.high.api", "allm"),
+    "Model": ("slimx.high.api", "Model"),
+    "AsyncModel": ("slimx.high.api", "AsyncModel"),
+
+    # Tooling
+    "tool": ("slimx.tooling", "tool"),
+    "ToolSpec": ("slimx.tooling", "ToolSpec"),
+
+    # Messages & core types
+    "Message": ("slimx.messages", "Message"),
+    "Result": ("slimx.types", "Result"),
+    "StreamEvent": ("slimx.types", "StreamEvent"),
+    "Usage": ("slimx.types", "Usage"),
+    "ToolCall": ("slimx.types", "ToolCall"),
+
+    # Low-level
+    "Client": ("slimx.low.client", "Client"),
+    "ChatRequest": ("slimx.low.types", "ChatRequest"),
+
+    # Providers
+    "get_provider": ("slimx.providers.registry", "get_provider"),
+    "list_providers": ("slimx.providers.registry", "list_providers"),
+}
+
+__all__ = [
+    # High-level
+    "llm",
+    "allm",
+    "Model",
+    "AsyncModel",
+
+    # Tooling
+    "tool",
+    "ToolSpec",
+
+    # Messages & core types
+    "Message",
+    "Result",
+    "StreamEvent",
+    "Usage",
+    "ToolCall",
+
+    # Low-level
+    "Client",
+    "ChatRequest",
+
+    # Providers
+    "get_provider",
+    "list_providers",
+
+    "__version__",
+]
+
+
+if TYPE_CHECKING:
+    # These imports are for type checkers only; runtime is lazy.
+    from slimx.high.api import AsyncModel, Model, allm, llm
+    from slimx.low.client import Client
+    from slimx.low.types import ChatRequest
+    from slimx.messages import Message
+    from slimx.providers.registry import get_provider, list_providers
+    from slimx.tooling import ToolSpec, tool
+    from slimx.types import Result, StreamEvent, ToolCall, Usage
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY:
+        module_name, attr = _LAZY[name]
+        mod = import_module(module_name)
+        return getattr(mod, attr)
+    raise AttributeError(f"module 'slimx' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + list(_LAZY.keys()))

slimx/errors.py

@@ -0,0 +1,7 @@
+class SlimXError(Exception): ...
+class ProviderError(SlimXError): ...
+class ProviderAuthError(ProviderError): ...
+class ProviderRateLimitError(ProviderError): ...
+class ProviderTimeoutError(ProviderError): ...
+class ToolExecutionError(SlimXError): ...
+class SchemaError(SlimXError): ...

slimx/high/__init__.py

@@ -0,0 +1,2 @@
+from .api import llm, allm, Model, AsyncModel
+__all__=['llm','allm','Model','AsyncModel']

slimx/high/api.py

@@ -0,0 +1,148 @@
+from typing import Any, Dict, Iterable, Optional, Sequence
+
+from ..messages import Message
+from ..types import Result, StreamEvent
+from ..schema import parse_json, schema_for, coerce_dataclass
+from ..tooling import ToolSpec
+from ..providers import get_provider
+from ..low import Client, ChatRequest
+
+
+def _parse_model(model: str):
+    if ":" in model:
+        p, m = model.split(":", 1)
+        return p.strip(), m.strip()
+    return "openai", model.strip()
+
+
+class Model:
+    def __init__(
+        self,
+        model: str,
+        *,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        tools: Optional[Sequence[ToolSpec]] = None,
+        tool_runtime: str = "none",
+        timeout: Optional[float] = None,
+        retries: int = 2,
+        provider_kwargs: Optional[Dict[str, Any]] = None,
+    ):
+        provider_name, model_name = _parse_model(model)
+        provider = get_provider(provider_name, async_mode=False, **(provider_kwargs or {}))
+        self._client = Client(provider, timeout=timeout, retries=retries)
+        self._model = model_name
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._tools = list(tools or [])
+        self._tool_runtime = tool_runtime
+
+    def __call__(self, prompt: str, **overrides: Any) -> Result:
+        req = ChatRequest(
+            model=self._model,
+            messages=[Message.user(prompt)],
+            temperature=overrides.get("temperature", self._temperature),
+            max_tokens=overrides.get("max_tokens", self._max_tokens),
+        )
+        return self._client.chat(req, tools=self._tools, tool_runtime=self._tool_runtime)
+
+    def stream(self, prompt: str, **overrides: Any) -> Iterable[StreamEvent]:
+        req = ChatRequest(
+            model=self._model,
+            messages=[Message.user(prompt)],
+            temperature=overrides.get("temperature", self._temperature),
+            max_tokens=overrides.get("max_tokens", self._max_tokens),
+        )
+        return self._client.stream(req, tools=self._tools)
+
+    def json(self, prompt: str, *, schema: Any, **overrides: Any) -> Result:
+        if isinstance(schema, dict):
+            schema_dict = schema
+            schema_type = None
+        else:
+            schema_type = schema
+            schema_dict = schema_for(schema)
+
+        sys = "Return ONLY valid JSON (no markdown). Match this JSON Schema exactly: " + str(schema_dict)
+        req = ChatRequest(
+            model=self._model,
+            messages=[Message.system(sys), Message.user(prompt)],
+            temperature=overrides.get("temperature", self._temperature),
+            max_tokens=overrides.get("max_tokens", self._max_tokens),
+            response_format="json_object",
+        )
+        res = self._client.chat(req, tools=self._tools, tool_runtime=self._tool_runtime)
+        obj = parse_json(res.text)
+        res.data = coerce_dataclass(schema_type, obj) if schema_type else obj
+        return res
+
+
+class AsyncModel:
+    def __init__(
+        self,
+        model: str,
+        *,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        tools: Optional[Sequence[ToolSpec]] = None,
+        tool_runtime: str = "none",
+        timeout: Optional[float] = None,
+        retries: int = 2,
+        provider_kwargs: Optional[Dict[str, Any]] = None,
+    ):
+        provider_name, model_name = _parse_model(model)
+        provider = get_provider(provider_name, async_mode=True, **(provider_kwargs or {}))
+        self._client = Client(provider, timeout=timeout, retries=retries)
+        self._model = model_name
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._tools = list(tools or [])
+        self._tool_runtime = tool_runtime
+
+    async def __call__(self, prompt: str, **overrides: Any) -> Result:
+        req = ChatRequest(
+            model=self._model,
+            messages=[Message.user(prompt)],
+            temperature=overrides.get("temperature", self._temperature),
+            max_tokens=overrides.get("max_tokens", self._max_tokens),
+        )
+        return await self._client.achat(req, tools=self._tools, tool_runtime=self._tool_runtime)
+
+    async def astream(self, prompt: str, **overrides: Any):
+        req = ChatRequest(
+            model=self._model,
+            messages=[Message.user(prompt)],
+            temperature=overrides.get("temperature", self._temperature),
+            max_tokens=overrides.get("max_tokens", self._max_tokens),
+        )
+        async for ev in self._client.astream(req, tools=self._tools):
+            yield ev
+
+    async def json(self, prompt: str, *, schema: Any, **overrides: Any) -> Result:
+        if isinstance(schema, dict):
+            schema_dict = schema
+            schema_type = None
+        else:
+            schema_type = schema
+            schema_dict = schema_for(schema)
+
+        sys = "Return ONLY valid JSON (no markdown). Match this JSON Schema exactly: " + str(schema_dict)
+        req = ChatRequest(
+            model=self._model,
+            messages=[Message.system(sys), Message.user(prompt)],
+            temperature=overrides.get("temperature", self._temperature),
+            max_tokens=overrides.get("max_tokens", self._max_tokens),
+            response_format="json_object",
+        )
+        res = await self._client.achat(req, tools=self._tools, tool_runtime=self._tool_runtime)
+        obj = parse_json(res.text)
+        res.data = coerce_dataclass(schema_type, obj) if schema_type else obj
+        return res
+
+
+def llm(model: str, **kwargs: Any) -> Model:
+    return Model(model, **kwargs)
+
+
+def allm(model: str, **kwargs: Any) -> AsyncModel:
+    return AsyncModel(model, **kwargs)

slimx/low/__init__.py

@@ -0,0 +1,32 @@
+"""Low-level SlimX API.
+
+This module is intentionally lazy to avoid circular imports.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, TYPE_CHECKING
+
+_LAZY: dict[str, tuple[str, str]] = {
+    "Client": ("slimx.low.client", "Client"),
+    "ChatRequest": ("slimx.low.types", "ChatRequest"),
+}
+
+__all__ = ["Client", "ChatRequest"]
+
+
+if TYPE_CHECKING:
+    from .client import Client
+    from .types import ChatRequest
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY:
+        module_name, attr = _LAZY[name]
+        return getattr(import_module(module_name), attr)
+    raise AttributeError(name)
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + list(_LAZY.keys()))

slimx/low/client.py

@@ -0,0 +1,137 @@
+import json
+import time
+from typing import Iterable, Optional, Sequence
+from ..messages import Message
+from ..types import Result, StreamEvent
+from ..tooling import ToolSpec, execute_tool
+from ..utils.retry import retry
+from ..providers.base import Provider
+from .types import ChatRequest
+
+class Client:
+    def __init__(self, provider: Provider, *, timeout: Optional[float]=None, retries: int=2):
+        self.provider = provider
+        self.timeout = timeout
+        self.retries = retries
+        self.provider_name = getattr(provider, "name", "provider")
+
+    def chat(self, req: ChatRequest, *, tools: Sequence[ToolSpec]=(), tool_runtime: str="none", max_steps: int=6) -> Result:
+        tool_map = {t.name: t for t in tools}
+        started = time.perf_counter()
+
+        res = retry(lambda: self.provider.chat(req, tools=tools, timeout=self.timeout), retries=self.retries)
+
+        if tool_runtime != "auto" or not res.tool_calls or not tool_map:
+            self._attach_trace(res, req=req, started=started, steps=0)
+            return res
+
+        # Auto tool loop (best-effort cross-provider)
+        messages = list(req.messages)
+        steps = 0
+        while res.tool_calls and steps < max_steps:
+            steps += 1
+            messages.append(Message.assistant("", tool_calls=[_tool_call_to_provider_dict(tc) for tc in res.tool_calls]))
+            for tc in res.tool_calls:
+                spec = tool_map.get(tc.name)
+                if not spec:
+                    continue
+                out = execute_tool(spec, tc.arguments)
+                messages.append(Message.tool(content=json.dumps(out), tool_call_id=tc.id or tc.name))
+
+            req = ChatRequest(
+                model=req.model,
+                messages=messages,
+                temperature=req.temperature,
+                max_tokens=req.max_tokens,
+                response_format=req.response_format,
+                extra=req.extra,
+            )
+            res = retry(lambda: self.provider.chat(req, tools=tools, timeout=self.timeout), retries=self.retries)
+            if not res.tool_calls:
+                break
+        self._attach_trace(res, req=req, started=started, steps=steps)
+        return res
+
+    def stream(self, req: ChatRequest, *, tools: Sequence[ToolSpec]=()) -> Iterable[StreamEvent]:
+        return self.provider.stream(req, tools=tools, timeout=self.timeout)
+
+    async def achat(self, req: ChatRequest, *, tools: Sequence[ToolSpec]=(), tool_runtime: str="none", max_steps: int=6) -> Result:
+        started = time.perf_counter()
+        # async retry
+        last = None
+        for i in range(self.retries + 1):
+            try:
+                res = await self.provider.achat(req, tools=tools, timeout=self.timeout)
+                break
+            except Exception as e:
+                last = e
+                if i >= self.retries:
+                    raise
+        else:
+            raise last  # type: ignore[misc]
+
+        tool_map = {t.name: t for t in tools}
+        if tool_runtime != "auto" or not res.tool_calls or not tool_map:
+            self._attach_trace(res, req=req, started=started, steps=0)
+            return res
+
+        messages = list(req.messages)
+        steps = 0
+        while res.tool_calls and steps < max_steps:
+            steps += 1
+            messages.append(Message.assistant("", tool_calls=[_tool_call_to_provider_dict(tc) for tc in res.tool_calls]))
+            for tc in res.tool_calls:
+                spec = tool_map.get(tc.name)
+                if not spec:
+                    continue
+                out = execute_tool(spec, tc.arguments)
+                messages.append(Message.tool(content=json.dumps(out), tool_call_id=tc.id or tc.name))
+
+            req = ChatRequest(
+                model=req.model,
+                messages=messages,
+                temperature=req.temperature,
+                max_tokens=req.max_tokens,
+                response_format=req.response_format,
+                extra=req.extra,
+            )
+
+            last = None
+            for i in range(self.retries + 1):
+                try:
+                    res = await self.provider.achat(req, tools=tools, timeout=self.timeout)
+                    break
+                except Exception as e:
+                    last = e
+                    if i >= self.retries:
+                        raise
+            else:
+                raise last  # type: ignore[misc]
+
+            if not res.tool_calls:
+                break
+        self._attach_trace(res, req=req, started=started, steps=steps)
+        return res
+
+    async def astream(self, req: ChatRequest, *, tools: Sequence[ToolSpec]=()):
+        async for ev in self.provider.astream(req, tools=tools, timeout=self.timeout):
+            yield ev
+
+    def _attach_trace(self, res: Result, *, req: ChatRequest, started: float, steps: int) -> None:
+        res.trace.update({
+            "provider": self.provider_name,
+            "model": req.model,
+            "elapsed_ms": int((time.perf_counter() - started) * 1000),
+            "retries": self.retries,
+            "tool_steps": steps,
+            "tool_call_count": len(res.tool_calls or []),
+            "timeout": self.timeout,
+        })
+
+
+def _tool_call_to_provider_dict(tc) -> dict:
+    return {
+        "id": tc.id or tc.name,
+        "type": "function",
+        "function": {"name": tc.name, "arguments": tc.arguments_json},
+    }

slimx/low/providers/__init__.py

@@ -0,0 +1,6 @@
+# Backwards-compatible import path for older code:
+from ...providers.openai import OpenAIProvider
+from ...providers.anthropic import AnthropicProvider
+from ...providers.ollama import OllamaProvider
+
+__all__ = ["OpenAIProvider", "AnthropicProvider", "OllamaProvider"]

slimx/low/types.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+from ..messages import Message
+
+@dataclass
+class ChatRequest:
+    model: str
+    messages: List[Message]
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    response_format: Optional[str] = None
+    extra: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"model": self.model, "messages": [m.to_dict() for m in self.messages]}
+        if self.temperature is not None:
+            d["temperature"] = self.temperature
+        if self.max_tokens is not None:
+            d["max_tokens"] = self.max_tokens
+        if self.response_format:
+            d["response_format"] = self.response_format
+        if self.extra:
+            d.update(self.extra)
+        return d

slimx/messages.py

@@ -0,0 +1,89 @@
+# slimx/messages.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class Message:
+    """
+    SlimX canonical message.
+
+    - `role`: system | user | assistant | tool
+    - `content`: message content (text)
+    - `name`: optional participant name
+    - `tool_call_id`: provider tool call identifier (OpenAI/Anthropic)
+    - `tool_name`: required by some providers for tool result messages (e.g., Ollama)
+    - `metadata`: extension point for provider-specific or app-specific fields
+    """
+    role: str
+    content: str
+    name: Optional[str] = None
+
+    # Tool message fields
+    tool_call_id: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_calls: List[Dict[str, Any]] = field(default_factory=list)
+
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def system(content: str, *, name: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> "Message":
+        return Message("system", content, name=name, metadata=metadata or {})
+
+    @staticmethod
+    def user(content: str, *, name: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> "Message":
+        return Message("user", content, name=name, metadata=metadata or {})
+
+    @staticmethod
+    def assistant(
+        content: str,
+        *,
+        name: Optional[str] = None,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "Message":
+        return Message("assistant", content, name=name, tool_calls=tool_calls or [], metadata=metadata or {})
+
+    @staticmethod
+    def tool(
+        content: str,
+        *,
+        tool_call_id: Optional[str] = None,
+        tool_name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "Message":
+        # tool_call_id: OpenAI/Anthropic
+        # tool_name: Ollama and some adapters
+        return Message(
+            "tool",
+            content,
+            tool_call_id=tool_call_id,
+            tool_name=tool_name,
+            metadata=metadata or {},
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Best-effort provider-agnostic serialization.
+        Providers may ignore unknown keys; adapters/providers can override if needed.
+        """
+        d: Dict[str, Any] = {"role": self.role, "content": self.content}
+
+        if self.name:
+            d["name"] = self.name
+
+        # Tool-related fields (only set if present)
+        if self.tool_call_id:
+            d["tool_call_id"] = self.tool_call_id
+        if self.tool_name:
+            d["tool_name"] = self.tool_name
+        if self.tool_calls:
+            d["tool_calls"] = self.tool_calls
+
+        # Optional extra fields
+        if self.metadata:
+            d["metadata"] = self.metadata
+
+        return d

slimx/providers/__init__.py

@@ -0,0 +1,13 @@
+"""Providers package.
+
+Provider implementations live under `slimx.providers.*`.
+
+Important: we do *not* import/register built-in providers at import time.
+Defaults are registered lazily in `slimx.providers.registry` when you call
+`list_providers()` or `get_provider()`.
+"""
+
+from .base import ProviderCapabilities
+from .registry import get_provider, list_providers, load_plugins, register
+
+__all__ = ["register", "get_provider", "load_plugins", "list_providers", "ProviderCapabilities"]

slimx/providers/_defaults.py

@@ -0,0 +1,100 @@
+"""Built-in provider factories.
+
+We keep provider imports inside factories so importing SlimX doesn't pull in
+provider code unless you actually select/use a provider.
+
+Factories accept keyword overrides where possible:
+- OpenAI: api_key, base_url
+- Anthropic: api_key, base_url, version
+- Ollama: base_url
+- Google: api_key, base_url
+
+Async selection is controlled via `async_mode=True`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, Dict
+
+from ..errors import ProviderAuthError
+from .base import Provider
+
+ProviderFactory = Callable[..., Provider]
+
+
+def openai_factory(*, async_mode: bool = False, **kwargs: Any) -> Provider:
+    api_key = kwargs.pop("api_key", None) or os.environ.get("OPENAI_API_KEY")
+    base_url = kwargs.pop("base_url", None) or os.environ.get(
+        "OPENAI_BASE_URL", "https://api.openai.com/v1"
+    )
+
+    if async_mode:
+        from .openai_async import OpenAIAsyncProvider as P
+    else:
+        from .openai import OpenAIProvider as P
+
+    if not api_key:
+        raise ProviderAuthError("OPENAI_API_KEY is not set")
+
+    return P(api_key=api_key, base_url=base_url)
+
+
+def anthropic_factory(*, async_mode: bool = False, **kwargs: Any) -> Provider:
+    api_key = kwargs.pop("api_key", None) or os.environ.get("ANTHROPIC_API_KEY")
+    base_url = kwargs.pop("base_url", None) or os.environ.get(
+        "ANTHROPIC_BASE_URL", "https://api.anthropic.com"
+    )
+    version = kwargs.pop("version", None) or os.environ.get("ANTHROPIC_VERSION", "2023-06-01")
+
+    if async_mode:
+        from .anthropic_async import AnthropicAsyncProvider as P
+    else:
+        from .anthropic import AnthropicProvider as P
+
+    if not api_key:
+        raise ProviderAuthError("ANTHROPIC_API_KEY is not set")
+
+    return P(api_key=api_key, base_url=base_url, version=version)
+
+
+def ollama_factory(*, async_mode: bool = False, **kwargs: Any) -> Provider:
+    base_url = kwargs.pop("base_url", None) or os.environ.get(
+        "OLLAMA_BASE_URL", "http://localhost:11434"
+    )
+
+    if async_mode:
+        from .ollama_async import OllamaAsyncProvider as P
+    else:
+        from .ollama import OllamaProvider as P
+
+    return P(base_url=base_url)
+
+
+def google_factory(*, async_mode: bool = False, **kwargs: Any) -> Provider:
+    api_key = (
+        kwargs.pop("api_key", None)
+        or os.environ.get("GOOGLE_API_KEY")
+        or os.environ.get("GEMINI_API_KEY")
+    )
+    base_url = kwargs.pop("base_url", None) or os.environ.get(
+        "GOOGLE_BASE_URL", "https://generativelanguage.googleapis.com/v1beta"
+    )
+
+    if async_mode:
+        from .google_async import GoogleAsyncProvider as P
+    else:
+        from .google import GoogleProvider as P
+
+    if not api_key:
+        raise ProviderAuthError("GOOGLE_API_KEY or GEMINI_API_KEY is not set")
+
+    return P(api_key=api_key, base_url=base_url)
+
+
+DEFAULT_FACTORIES: Dict[str, ProviderFactory] = {
+    "openai": openai_factory,
+    "anthropic": anthropic_factory,
+    "ollama": ollama_factory,
+    "google": google_factory,
+}