multillm-core 0.1.0__tar.gz

multillm_core-0.1.0/API_SPEC.md

@@ -0,0 +1,59 @@
+# Internal API Specification — multillm
+
+## 1. Public API Contract
+
+### Package Name
+- **Internal/Import Name**: `multillm`
+- **PyPI Name**: `multillm-core` (Suggested, as `multillm` is taken)
+
+### Entrypoint
+```python
+from multillm import create_client
+
+client = create_client("openai", api_key="sk-...")
+response = await client.generate(model="gpt-4o", prompt="Hello!")
+```
+
+### Core Abstractions
+
+#### BaseLLMClient
+Abstract base class for all providers.
+- `async generate(model: str, prompt: str, **kwargs) -> LLMResponse`
+- `async stream(model: str, prompt: str, **kwargs) -> AsyncGenerator[str, None]` (Future proofing)
+
+#### LLMResponse (Pydantic)
+Unified response object.
+- `text`: str
+- `provider`: str
+- `model`: str
+- `usage`: `TokenUsage` (input_tokens, output_tokens)
+- `raw`: Full response from provider SDK
+
+#### Error Hierarchy
+- `MultiLLMError` (Base)
+  - `ProviderNotFoundError`: Factory can't find provider
+  - `SDKNotInstalledError`: Provider dependencies missing
+  - `APIError`: Base for provider-side errors
+    - `AuthenticationError`: 401
+    - `RateLimitError`: 429
+    - `InvalidRequestError`: 400
+
+## 2. Supported Providers (v0.1 Scope)
+- **OpenAI**: Using `openai` SDK
+- **Anthropic**: Using `anthropic` SDK
+- **Google Gemini**: Using `google-generativeai` SDK
+
+## 3. Project Structure
+```text
+src/multillm/
+├── providers/
+│   ├── base.py
+│   ├── openai.py
+│   ├── anthropic.py
+│   └── gemini.py
+├── factory.py
+├── schemas.py
+├── exceptions.py
+├── version.py
+└── __init__.py
+```

multillm_core-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: multillm-core
+Version: 0.1.0
+Summary: A unified interface for multiple LLM providers
+Author: Divas Rajan
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: google-genai>=1.47.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.10.0; extra == 'all'
+Requires-Dist: google-genai>=0.1.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.10.0; extra == 'anthropic'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.1.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# multillm-core
+
+A unified interface for multiple LLM providers (OpenAI, Anthropic, Gemini).
+
+## Installation
+
+```bash
+pip install multillm-core
+```
+
+### Install with specific providers:
+
+```bash
+pip install "multillm-core[openai]"
+pip install "multillm-core[anthropic]"
+pip install "multillm-core[gemini]"
+pip install "multillm-core[all]"
+```
+
+## Example Usage
+
+```python
+import asyncio
+from multillm import create_client
+
+async def main():
+    client = create_client("openai", api_key="your-key")
+    response = await client.generate(
+        model="gpt-4o",
+        prompt="Explain quantum entanglement in one sentence."
+    )
+    print(f"[{response.provider}] {response.text}")
+    print(f"Usage: {response.usage}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Supported Providers
+- OpenAI
+- Anthropic
+- Google Gemini
+
+## License
+MIT

multillm_core-0.1.0/README.md

@@ -0,0 +1,45 @@
+# multillm-core
+
+A unified interface for multiple LLM providers (OpenAI, Anthropic, Gemini).
+
+## Installation
+
+```bash
+pip install multillm-core
+```
+
+### Install with specific providers:
+
+```bash
+pip install "multillm-core[openai]"
+pip install "multillm-core[anthropic]"
+pip install "multillm-core[gemini]"
+pip install "multillm-core[all]"
+```
+
+## Example Usage
+
+```python
+import asyncio
+from multillm import create_client
+
+async def main():
+    client = create_client("openai", api_key="your-key")
+    response = await client.generate(
+        model="gpt-4o",
+        prompt="Explain quantum entanglement in one sentence."
+    )
+    print(f"[{response.provider}] {response.text}")
+    print(f"Usage: {response.usage}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Supported Providers
+- OpenAI
+- Anthropic
+- Google Gemini
+
+## License
+MIT

multillm_core-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "multillm-core"
+version = "0.1.0"
+description = "A unified interface for multiple LLM providers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Divas Rajan" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "google-genai>=1.47.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.10.0"]
+gemini = ["google-genai>=0.1.0"]
+all = [
+    "openai>=1.0.0",
+    "anthropic>=0.10.0",
+    "google-genai>=0.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/multillm"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "ruff>=0.15.1",
+]

multillm_core-0.1.0/src/multillm/__init__.py

@@ -0,0 +1,13 @@
+from .exceptions import MultiLLMError
+from .factory import create_client
+from .providers.base import BaseLLMClient
+from .schemas import LLMResponse
+from .version import __version__
+
+__all__ = [
+    "create_client",
+    "BaseLLMClient",
+    "LLMResponse",
+    "MultiLLMError",
+    "__version__",
+]

multillm_core-0.1.0/src/multillm/exceptions.py

@@ -0,0 +1,46 @@
+class MultiLLMError(Exception):
+    """Base exception for all multillm errors."""
+
+    pass
+
+
+class ProviderNotFoundError(MultiLLMError):
+    """Raised when a requested provider is not found."""
+
+    pass
+
+
+class SDKNotInstalledError(MultiLLMError):
+    """Raised when a provider's SDK is not installed."""
+
+    def __init__(self, provider: str, package_name: str):
+        self.provider = provider
+        self.package_name = package_name
+        super().__init__(
+            f"SDK for '{provider}' is not installed. Please install it using: "
+            f"pip install 'multillm-core[{package_name}]'"
+        )
+
+
+class APIError(MultiLLMError):
+    """Base for provider-side API errors."""
+
+    pass
+
+
+class AuthenticationError(APIError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Raised when rate limits are exceeded."""
+
+    pass
+
+
+class InvalidRequestError(APIError):
+    """Raised when the request is invalid."""
+
+    pass

multillm_core-0.1.0/src/multillm/factory.py

@@ -0,0 +1,39 @@
+from typing import Any
+
+from .exceptions import ProviderNotFoundError
+from .providers.anthropic import AnthropicClient
+from .providers.base import BaseLLMClient
+from .providers.gemini import GeminiClient
+from .providers.openai import OpenAIClient
+
+PROVIDER_MAP: dict[str, type[BaseLLMClient]] = {
+    "openai": OpenAIClient,
+    "anthropic": AnthropicClient,
+    "gemini": GeminiClient,
+    "google": GeminiClient,
+}
+
+
+def create_client(provider: str, **kwargs: Any) -> BaseLLMClient:
+    """
+    Factory function to create an LLM client.
+
+    Args:
+        provider: Name of the provider ('openai', 'anthropic', 'gemini').
+        **kwargs: Arguments passed to the provider client constructor (e.g., api_key).
+
+    Returns:
+        An instance of BaseLLMClient.
+
+    Raises:
+        ProviderNotFoundError: If the provider is not supported.
+    """
+    provider_key = provider.lower()
+    if provider_key not in PROVIDER_MAP:
+        raise ProviderNotFoundError(
+            f"Provider '{provider}' is not supported. "
+            f"Available providers: {', '.join(PROVIDER_MAP.keys())}"
+        )
+
+    client_cls = PROVIDER_MAP[provider_key]
+    return client_cls(**kwargs)

multillm_core-0.1.0/src/multillm/providers/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseLLMClient
+
+__all__ = ["BaseLLMClient"]

multillm_core-0.1.0/src/multillm/providers/anthropic.py

@@ -0,0 +1,59 @@
+from typing import Any, NoReturn, Optional
+
+from ..exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    RateLimitError,
+    SDKNotInstalledError,
+)
+from ..schemas import LLMResponse, TokenUsage
+from .base import BaseLLMClient
+
+
+class AnthropicClient(BaseLLMClient):
+    """Anthropic provider client."""
+
+    def __init__(self, api_key: Optional[str] = None, **kwargs: Any):
+        try:
+            import anthropic
+
+            self._client = anthropic.AsyncAnthropic(api_key=api_key, **kwargs)
+        except ImportError:
+            raise SDKNotInstalledError("anthropic", "anthropic")
+
+    async def generate(self, model: str, prompt: str, **kwargs: Any) -> LLMResponse:
+        try:
+            response = await self._client.messages.create(
+                model=model,
+                max_tokens=kwargs.get("max_tokens", 4096),
+                messages=[{"role": "user", "content": prompt}],
+                **{k: v for k, v in kwargs.items() if k != "max_tokens"},
+            )
+
+            text = response.content[0].text
+
+            usage = TokenUsage(
+                input_tokens=response.usage.input_tokens,
+                output_tokens=response.usage.output_tokens,
+                total_tokens=response.usage.input_tokens + response.usage.output_tokens,
+            )
+
+            return LLMResponse(
+                text=text, provider="anthropic", model=model, usage=usage, raw=response
+            )
+        except Exception as e:
+            return self._handle_error(e)
+
+    def _handle_error(self, e: Exception) -> NoReturn:
+        import anthropic
+
+        if isinstance(e, anthropic.AuthenticationError):
+            raise AuthenticationError(str(e))
+        if isinstance(e, anthropic.RateLimitError):
+            raise RateLimitError(str(e))
+        if isinstance(e, anthropic.BadRequestError):
+            raise InvalidRequestError(str(e))
+        if isinstance(e, anthropic.APIError):
+            raise APIError(str(e))
+        raise APIError(f"Unexpected Anthropic error: {str(e)}")

multillm_core-0.1.0/src/multillm/providers/base.py

@@ -0,0 +1,42 @@
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from ..schemas import LLMResponse
+
+
+class BaseLLMClient(ABC):
+    """Base class for all LLM provider clients."""
+
+    @abstractmethod
+    async def generate(self, model: str, prompt: str, **kwargs: Any) -> LLMResponse:
+        """
+        Generate a response from the LLM.
+
+        Args:
+            model: The model name to use.
+            prompt: The input text prompt.
+            **kwargs: Provider-specific arguments.
+
+        Returns:
+            LLMResponse object.
+        """
+        pass
+
+    async def stream(
+        self, model: str, prompt: str, **kwargs: Any
+    ) -> AsyncGenerator[str, None]:
+        """
+        Stream back the response from the LLM.
+
+        Args:
+            model: The model name to use.
+            prompt: The input text prompt.
+            **kwargs: Provider-specific arguments.
+
+        Yields:
+            Response chunks text.
+        """
+        raise NotImplementedError(
+            f"Streaming is not implemented for {self.__class__.__name__}"
+        )

multillm_core-0.1.0/src/multillm/providers/gemini.py

@@ -0,0 +1,46 @@
+from typing import Any, Optional
+
+from ..exceptions import APIError, SDKNotInstalledError
+from ..schemas import LLMResponse, TokenUsage
+from .base import BaseLLMClient
+
+
+class GeminiClient(BaseLLMClient):
+    """Google Gemini provider client."""
+
+    def __init__(self, api_key: Optional[str] = None, **kwargs: Any):
+        try:
+            from google import genai
+
+            self._client = genai.Client(api_key=api_key, **kwargs)
+        except ImportError:
+            raise SDKNotInstalledError("google-genai", "gemini")
+
+    async def generate(self, model: str, prompt: str, **kwargs: Any) -> LLMResponse:
+        try:
+            # The new SDK uses client.aio.models.generate_content for async
+            response = await self._client.aio.models.generate_content(
+                model=model, contents=prompt, **kwargs
+            )
+
+            text = response.text or ""
+            usage = TokenUsage()
+
+            if hasattr(response, "usage_metadata") and response.usage_metadata:
+                usage = TokenUsage(
+                    input_tokens=getattr(
+                        response.usage_metadata, "prompt_token_count", 0
+                    ),
+                    output_tokens=getattr(
+                        response.usage_metadata, "candidates_token_count", 0
+                    ),
+                    total_tokens=getattr(
+                        response.usage_metadata, "total_token_count", 0
+                    ),
+                )
+
+            return LLMResponse(
+                text=text, provider="gemini", model=model, usage=usage, raw=response
+            )
+        except Exception as e:
+            raise APIError(f"Gemini error: {str(e)}")

multillm_core-0.1.0/src/multillm/providers/openai.py

@@ -0,0 +1,57 @@
+from typing import Any, NoReturn, Optional
+
+from ..exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    RateLimitError,
+    SDKNotInstalledError,
+)
+from ..schemas import LLMResponse, TokenUsage
+from .base import BaseLLMClient
+
+
+class OpenAIClient(BaseLLMClient):
+    """OpenAI provider client."""
+
+    def __init__(self, api_key: Optional[str] = None, **kwargs: Any):
+        try:
+            import openai
+
+            self._client = openai.AsyncOpenAI(api_key=api_key, **kwargs)
+        except ImportError:
+            raise SDKNotInstalledError("openai", "openai")
+
+    async def generate(self, model: str, prompt: str, **kwargs: Any) -> LLMResponse:
+        try:
+            response = await self._client.chat.completions.create(
+                model=model, messages=[{"role": "user", "content": prompt}], **kwargs
+            )
+
+            choice = response.choices[0]
+            text = choice.message.content or ""
+
+            usage = TokenUsage(
+                input_tokens=response.usage.prompt_tokens,
+                output_tokens=response.usage.completion_tokens,
+                total_tokens=response.usage.total_tokens,
+            )
+
+            return LLMResponse(
+                text=text, provider="openai", model=model, usage=usage, raw=response
+            )
+        except Exception as e:
+            return self._handle_error(e)
+
+    def _handle_error(self, e: Exception) -> NoReturn:
+        import openai
+
+        if isinstance(e, openai.AuthenticationError):
+            raise AuthenticationError(str(e))
+        if isinstance(e, openai.RateLimitError):
+            raise RateLimitError(str(e))
+        if isinstance(e, openai.BadRequestError):
+            raise InvalidRequestError(str(e))
+        if isinstance(e, openai.APIError):
+            raise APIError(str(e))
+        raise APIError(f"Unexpected OpenAI error: {str(e)}")

multillm_core-0.1.0/src/multillm/schemas.py

@@ -0,0 +1,23 @@
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TokenUsage(BaseModel):
+    """Token usage statistics."""
+
+    input_tokens: int = Field(default=0, description="Number of tokens in the input.")
+    output_tokens: int = Field(default=0, description="Number of tokens in the output.")
+    total_tokens: Optional[int] = Field(default=None, description="Total tokens used.")
+
+
+class LLMResponse(BaseModel):
+    """Unified response model for all LLM providers."""
+
+    text: str = Field(..., description="The generated text response.")
+    provider: str = Field(..., description="The name of the provider.")
+    model: str = Field(..., description="The model name used.")
+    usage: TokenUsage = Field(
+        default_factory=TokenUsage, description="Token usage details."
+    )
+    raw: Any = Field(None, description="The raw response from the provider's SDK.")

multillm_core-0.1.0/src/multillm/version.py

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

multillm_core-0.1.0/tests/test_core.py

@@ -0,0 +1,98 @@
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from multillm import LLMResponse, create_client
+from multillm.exceptions import ProviderNotFoundError, SDKNotInstalledError
+
+
+def test_factory_invalid_provider():
+    with pytest.raises(ProviderNotFoundError):
+        create_client("invalid-provider")
+
+
+@patch("multillm.providers.openai.OpenAIClient.__init__", return_value=None)
+def test_factory_openai_creation(mock_init):
+    client = create_client("openai", api_key="test")
+    assert client is not None
+
+
+@pytest.mark.asyncio
+async def test_openai_generate_mock():
+    with patch("openai.AsyncOpenAI") as mock_openai:
+        from multillm.providers.openai import OpenAIClient
+
+        # Mocking the nested response structure
+        mock_response = MagicMock()
+        mock_choice = MagicMock()
+        mock_choice.message.content = "Hehe"
+        mock_response.choices = [mock_choice]
+        mock_response.usage.prompt_tokens = 10
+        mock_response.usage.completion_tokens = 5
+        mock_response.usage.total_tokens = 15
+
+        mock_instance = mock_openai.return_value
+        mock_instance.chat.completions.create = AsyncMock(return_value=mock_response)
+
+        client = OpenAIClient(api_key="test")
+        response = await client.generate(model="gpt-4", prompt="test")
+
+        assert isinstance(response, LLMResponse)
+        assert response.text == "Hehe"
+        assert response.provider == "openai"
+        assert response.usage.input_tokens == 10
+
+
+@pytest.mark.asyncio
+async def test_anthropic_generate_mock():
+    with patch("anthropic.AsyncAnthropic") as mock_anthropic:
+        from multillm.providers.anthropic import AnthropicClient
+
+        mock_response = MagicMock()
+        mock_content = MagicMock()
+        mock_content.text = "Hello from Claude"
+        mock_response.content = [mock_content]
+        mock_response.usage.input_tokens = 20
+        mock_response.usage.output_tokens = 10
+
+        mock_instance = mock_anthropic.return_value
+        mock_instance.messages.create = AsyncMock(return_value=mock_response)
+
+        client = AnthropicClient(api_key="test")
+        response = await client.generate(model="claude-3", prompt="test")
+
+        assert response.text == "Hello from Claude"
+        assert response.provider == "anthropic"
+
+
+def test_sdk_not_installed():
+    from multillm.providers.openai import OpenAIClient
+
+    with patch("openai.AsyncOpenAI", side_effect=ImportError):
+        with pytest.raises(SDKNotInstalledError):
+            OpenAIClient(api_key="test")
+
+
+@pytest.mark.asyncio
+async def test_gemini_generate_mock():
+    with patch("google.genai.Client") as mock_client_cls:
+        from multillm.providers.gemini import GeminiClient
+
+        mock_response = MagicMock()
+        mock_response.text = "Hello from Gemini"
+        mock_response.usage_metadata.prompt_token_count = 10
+        mock_response.usage_metadata.candidates_token_count = 5
+        mock_response.usage_metadata.total_token_count = 15
+
+        mock_client = mock_client_cls.return_value
+        # The new SDK structure is client.aio.models.generate_content
+        mock_client.aio.models.generate_content = AsyncMock(return_value=mock_response)
+
+        client = GeminiClient(api_key="test")
+        response = await client.generate(model="gemini-pro", prompt="test")
+
+        assert response.text == "Hello from Gemini"
+        assert response.provider == "gemini"
+        assert response.usage.input_tokens == 10
+        assert response.usage.output_tokens == 5
+        assert response.usage.total_tokens == 15