lm15 0.1.0__tar.gz

lm15-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/

lm15-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lm15 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lm15-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: lm15
+Version: 0.1.0
+Summary: Universal LM core with pluggable provider adapters
+Project-URL: Homepage, https://github.com/maxime/lm15
+Project-URL: Documentation, https://github.com/maxime/lm15
+Project-URL: Issues, https://github.com/maxime/lm15/issues
+Author: lm15 contributors
+License-File: LICENSE
+Keywords: adapters,ai,anthropic,gemini,llm,openai,streaming
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pycurl>=7.45.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Provides-Extra: speed
+Requires-Dist: pycurl>=7.45.0; extra == 'speed'
+Description-Content-Type: text/markdown
+
+# lm15 (Universal LM) — thin core, full plugin contract
+
+A universal LM core optimized for low import/runtime overhead with provider plugins.
+
+## Core architecture
+
+- **Universal contract** (`types.py`): normalized request/response/stream/live types.
+- **Provider plugin contract** (`providers/base.py`): complete/stream/live/embeddings/files/batch/images/audio methods.
+- **Transport boundary** (`transports/*`): urllib and pycurl implementations.
+- **Capability resolver** (`capabilities.py`): static + optional hydration from models.dev.
+- **Model catalog bridge** (`model_catalog.py`): loads `https://models.dev/api.json`.
+- **Middleware pipeline** (`middleware.py`): retries/history/cache wrappers.
+- **Completeness harness** (`completeness/*`): fixture + live probes, score output.
+
+## Quick start
+
+```python
+from lm15 import Message, LMRequest, Part, build_default
+
+lm = build_default(use_pycurl=True)
+req = LMRequest(model="claude-sonnet-4-5", messages=(Message(role="user", parts=(Part.text_part("Say hi."),)),))
+resp = lm.complete(req)
+print(resp.message.parts[0].text)
+```
+
+## External plugin adapters (no core PR)
+
+LM15 auto-discovers installed entry-points in group `lm15.providers`.
+
+```toml
+# in external package pyproject.toml
+[project.entry-points."lm15.providers"]
+myprovider = "ulm_x_myprovider:build_adapter"
+```
+
+```python
+from lm15 import build_default
+
+lm = build_default(discover_plugins=True)
+```
+
+## Optional models.dev hydration
+
+```python
+lm = build_default(hydrate_models_dev_catalog=True)
+```
+
+## Completeness
+
+```bash
+python3 completeness/runner.py --mode fixture --fail-under 1.0
+python3 completeness/runner.py --mode live --fail-under 0.0
+```
+
+Outputs:
+- `completeness/report.json`
+- `completeness/report.md`
+
+## Packaging and publishing (uv + twine)
+
+```bash
+# build sdist + wheel
+uv run python -m build
+
+# upload to TestPyPI
+# twine upload --repository testpypi dist/*
+
+# upload to PyPI
+# twine upload dist/*
+```
+
+## Environment variables
+
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+
+## Docs
+
+### Core
+
+- `docs/GETTING_STARTED.md`
+- `docs/CONCEPTS.md`
+- `docs/ARCHITECTURE.md`
+- `docs/CONTRACT.md`
+- `docs/ERRORS.md`
+- `docs/STREAMING.md`
+- `docs/COMPLETENESS.md`
+- `docs/PRODUCTION_CHECKLIST.md`
+
+### Provider development
+
+- `docs/ADAPTER_GUIDE.md`
+- `docs/ADD_PROVIDER_GUIDE.md`
+- `docs/COOKBOOK_TEMPLATE.md`
+
+### Cookbooks (learning order)
+
+- `docs/COOKBOOKS/01-basic-text.md`
+- `docs/COOKBOOKS/02-streaming.md`
+- `docs/COOKBOOKS/03-tools.md`
+- `docs/COOKBOOKS/04-multimodal.md`
+- `docs/COOKBOOKS/05-files-batches.md`
+- `docs/COOKBOOKS/06-reliability.md`
+- `docs/COOKBOOKS/07-external-plugins.md`
+- `docs/COOKBOOKS/08-models-dev-hydration.md`

lm15-0.1.0/README.md

@@ -0,0 +1,106 @@
+# lm15 (Universal LM) — thin core, full plugin contract
+
+A universal LM core optimized for low import/runtime overhead with provider plugins.
+
+## Core architecture
+
+- **Universal contract** (`types.py`): normalized request/response/stream/live types.
+- **Provider plugin contract** (`providers/base.py`): complete/stream/live/embeddings/files/batch/images/audio methods.
+- **Transport boundary** (`transports/*`): urllib and pycurl implementations.
+- **Capability resolver** (`capabilities.py`): static + optional hydration from models.dev.
+- **Model catalog bridge** (`model_catalog.py`): loads `https://models.dev/api.json`.
+- **Middleware pipeline** (`middleware.py`): retries/history/cache wrappers.
+- **Completeness harness** (`completeness/*`): fixture + live probes, score output.
+
+## Quick start
+
+```python
+from lm15 import Message, LMRequest, Part, build_default
+
+lm = build_default(use_pycurl=True)
+req = LMRequest(model="claude-sonnet-4-5", messages=(Message(role="user", parts=(Part.text_part("Say hi."),)),))
+resp = lm.complete(req)
+print(resp.message.parts[0].text)
+```
+
+## External plugin adapters (no core PR)
+
+LM15 auto-discovers installed entry-points in group `lm15.providers`.
+
+```toml
+# in external package pyproject.toml
+[project.entry-points."lm15.providers"]
+myprovider = "ulm_x_myprovider:build_adapter"
+```
+
+```python
+from lm15 import build_default
+
+lm = build_default(discover_plugins=True)
+```
+
+## Optional models.dev hydration
+
+```python
+lm = build_default(hydrate_models_dev_catalog=True)
+```
+
+## Completeness
+
+```bash
+python3 completeness/runner.py --mode fixture --fail-under 1.0
+python3 completeness/runner.py --mode live --fail-under 0.0
+```
+
+Outputs:
+- `completeness/report.json`
+- `completeness/report.md`
+
+## Packaging and publishing (uv + twine)
+
+```bash
+# build sdist + wheel
+uv run python -m build
+
+# upload to TestPyPI
+# twine upload --repository testpypi dist/*
+
+# upload to PyPI
+# twine upload dist/*
+```
+
+## Environment variables
+
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+
+## Docs
+
+### Core
+
+- `docs/GETTING_STARTED.md`
+- `docs/CONCEPTS.md`
+- `docs/ARCHITECTURE.md`
+- `docs/CONTRACT.md`
+- `docs/ERRORS.md`
+- `docs/STREAMING.md`
+- `docs/COMPLETENESS.md`
+- `docs/PRODUCTION_CHECKLIST.md`
+
+### Provider development
+
+- `docs/ADAPTER_GUIDE.md`
+- `docs/ADD_PROVIDER_GUIDE.md`
+- `docs/COOKBOOK_TEMPLATE.md`
+
+### Cookbooks (learning order)
+
+- `docs/COOKBOOKS/01-basic-text.md`
+- `docs/COOKBOOKS/02-streaming.md`
+- `docs/COOKBOOKS/03-tools.md`
+- `docs/COOKBOOKS/04-multimodal.md`
+- `docs/COOKBOOKS/05-files-batches.md`
+- `docs/COOKBOOKS/06-reliability.md`
+- `docs/COOKBOOKS/07-external-plugins.md`
+- `docs/COOKBOOKS/08-models-dev-hydration.md`

lm15-0.1.0/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+Run all examples in offline-safe mode:
+
+```bash
+python examples/validate_examples.py
+```
+
+Run one example with live API calls:
+
+```bash
+# ensure provider keys are set and do not set LM15_EXAMPLES_SKIP_LIVE
+python examples/01_basic_text.py
+```
+
+Files:
+
+- `01_basic_text.py`
+- `02_streaming.py`
+- `03_tools.py`
+- `04_multimodal.py`
+- `05_files_batches.py`
+- `06_reliability.py`
+- `07_external_plugins.py`
+- `08_models_dev_hydration.py`

lm15-0.1.0/lm15/__init__.py

@@ -0,0 +1,87 @@
+from .capabilities import hydrate_with_specs
+from .client import UniversalLM
+from .middleware import with_cache, with_history, with_retries
+from .model_catalog import build_provider_model_index, fetch_models_dev
+from .plugins import discover_provider_entry_points, load_plugins
+from .transports.base import TransportPolicy
+from .types import (
+    AudioFormat,
+    AudioGenerationRequest,
+    AudioGenerationResponse,
+    BatchRequest,
+    BatchResponse,
+    Config,
+    DataSource,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    FileUploadRequest,
+    FileUploadResponse,
+    ImageGenerationRequest,
+    ImageGenerationResponse,
+    LMRequest,
+    LMResponse,
+    LiveClientEvent,
+    LiveConfig,
+    LiveServerEvent,
+    Message,
+    Part,
+    StreamEvent,
+    Tool,
+    ToolConfig,
+    Usage,
+)
+
+
+def build_default(
+    use_pycurl: bool = True,
+    policy: TransportPolicy | None = None,
+    hydrate_models_dev_catalog: bool = False,
+    discover_plugins: bool = True,
+):
+    from .factory import build_default as _build_default
+
+    return _build_default(
+        use_pycurl=use_pycurl,
+        policy=policy,
+        hydrate_models_dev=hydrate_models_dev_catalog,
+        discover_plugins=discover_plugins,
+    )
+
+
+__all__ = [
+    "UniversalLM",
+    "build_default",
+    "TransportPolicy",
+    "with_cache",
+    "with_history",
+    "with_retries",
+    "hydrate_with_specs",
+    "load_plugins",
+    "discover_provider_entry_points",
+    "fetch_models_dev",
+    "build_provider_model_index",
+    "Config",
+    "DataSource",
+    "LMRequest",
+    "LMResponse",
+    "Message",
+    "Part",
+    "StreamEvent",
+    "EmbeddingRequest",
+    "EmbeddingResponse",
+    "FileUploadRequest",
+    "FileUploadResponse",
+    "BatchRequest",
+    "BatchResponse",
+    "ImageGenerationRequest",
+    "ImageGenerationResponse",
+    "AudioGenerationRequest",
+    "AudioGenerationResponse",
+    "LiveConfig",
+    "LiveClientEvent",
+    "LiveServerEvent",
+    "AudioFormat",
+    "Tool",
+    "ToolConfig",
+    "Usage",
+]

lm15-0.1.0/lm15/auth.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class AuthStrategy:
+    def apply_headers(self, headers: dict[str, str]) -> dict[str, str]:
+        return headers
+
+    def apply_params(self, params: dict[str, str]) -> dict[str, str]:
+        return params
+
+
+@dataclass(slots=True, frozen=True)
+class BearerAuth(AuthStrategy):
+    token: str
+
+    def apply_headers(self, headers: dict[str, str]) -> dict[str, str]:
+        out = dict(headers)
+        out["Authorization"] = f"Bearer {self.token}"
+        return out
+
+
+@dataclass(slots=True, frozen=True)
+class HeaderKeyAuth(AuthStrategy):
+    header: str
+    key: str
+
+    def apply_headers(self, headers: dict[str, str]) -> dict[str, str]:
+        out = dict(headers)
+        out[self.header] = self.key
+        return out
+
+
+@dataclass(slots=True, frozen=True)
+class QueryKeyAuth(AuthStrategy):
+    param: str
+    key: str
+
+    def apply_params(self, params: dict[str, str]) -> dict[str, str]:
+        out = dict(params)
+        out[self.param] = self.key
+        return out

lm15-0.1.0/lm15/bench_import.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import statistics
+import subprocess
+import sys
+
+
+def bench(module: str, runs: int = 30):
+    vals = []
+    for _ in range(runs):
+        p = subprocess.run(
+            [sys.executable, "-c", f"import time; t=time.perf_counter(); import {module}; print((time.perf_counter()-t)*1000)"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        vals.append(float(p.stdout.strip()))
+    vals.sort()
+    return {
+        "median_ms": statistics.median(vals),
+        "p95_ms": vals[int(0.95 * (len(vals) - 1))],
+        "min_ms": vals[0],
+        "max_ms": vals[-1],
+    }
+
+
+if __name__ == "__main__":
+    print({"lm15": bench("lm15")})

lm15-0.1.0/lm15/capabilities.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .model_catalog import ModelSpec
+from .protocols import Capabilities
+
+
+@dataclass(slots=True, frozen=True)
+class ModelCapabilities:
+    provider: str
+    pattern: str
+    caps: Capabilities
+
+
+REGISTRY: tuple[ModelCapabilities, ...] = (
+    ModelCapabilities(
+        provider="anthropic",
+        pattern="claude",
+        caps=Capabilities(
+            input_modalities=frozenset({"text", "image", "document"}),
+            output_modalities=frozenset({"text"}),
+            features=frozenset({"streaming", "tools", "reasoning"}),
+        ),
+    ),
+    ModelCapabilities(
+        provider="gemini",
+        pattern="gemini",
+        caps=Capabilities(
+            input_modalities=frozenset({"text", "image", "audio", "video", "document"}),
+            output_modalities=frozenset({"text"}),
+            features=frozenset({"streaming", "tools", "json_output", "live"}),
+        ),
+    ),
+    ModelCapabilities(
+        provider="openai",
+        pattern="gpt",
+        caps=Capabilities(
+            input_modalities=frozenset({"text", "image", "audio", "video", "document"}),
+            output_modalities=frozenset({"text", "audio"}),
+            features=frozenset({"streaming", "tools", "json_output", "reasoning", "live", "embeddings"}),
+        ),
+    ),
+)
+
+
+class CapabilityResolver:
+    def __init__(self):
+        self._model_index: dict[str, ModelSpec] = {}
+
+    def hydrate(self, specs: list[ModelSpec]) -> None:
+        self._model_index = {s.id: s for s in specs}
+
+    def resolve_provider(self, model: str) -> str:
+        if model in self._model_index:
+            return self._model_index[model].provider
+        lower = model.lower()
+        for item in REGISTRY:
+            if lower.startswith(item.pattern):
+                return item.provider
+        return "openai"
+
+    def resolve_capabilities(self, model: str) -> Capabilities:
+        spec = self._model_index.get(model)
+        if spec:
+            return spec.to_capabilities()
+        lower = model.lower()
+        for item in REGISTRY:
+            if lower.startswith(item.pattern):
+                return item.caps
+        return REGISTRY[-1].caps
+
+
+_DEFAULT_RESOLVER = CapabilityResolver()
+
+
+def hydrate_with_specs(specs: list[ModelSpec]) -> None:
+    _DEFAULT_RESOLVER.hydrate(specs)
+
+
+def resolve_provider(model: str) -> str:
+    return _DEFAULT_RESOLVER.resolve_provider(model)
+
+
+def resolve_capabilities(model: str) -> Capabilities:
+    return _DEFAULT_RESOLVER.resolve_capabilities(model)

lm15-0.1.0/lm15/client.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterator
+
+from .capabilities import resolve_provider
+from .errors import ProviderError, UnsupportedFeatureError
+from .middleware import MiddlewarePipeline
+from .protocols import LMAdapter, LiveSession
+from .types import (
+    AudioGenerationRequest,
+    AudioGenerationResponse,
+    BatchRequest,
+    BatchResponse,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    FileUploadRequest,
+    FileUploadResponse,
+    ImageGenerationRequest,
+    ImageGenerationResponse,
+    LMRequest,
+    LMResponse,
+    LiveConfig,
+    StreamEvent,
+)
+
+
+@dataclass(slots=True)
+class UniversalLM:
+    adapters: dict[str, LMAdapter] = field(default_factory=dict)
+    middleware: MiddlewarePipeline = field(default_factory=MiddlewarePipeline)
+
+    def register(self, adapter: LMAdapter) -> None:
+        self.adapters[adapter.provider] = adapter
+
+    def _adapter(self, model: str, provider: str | None = None) -> LMAdapter:
+        p = provider or resolve_provider(model)
+        adapter = self.adapters.get(p)
+        if not adapter:
+            raise ProviderError(f"no adapter registered for provider '{p}'")
+        return adapter
+
+    def complete(self, request: LMRequest, provider: str | None = None) -> LMResponse:
+        adapter = self._adapter(request.model, provider)
+        if not adapter.supports.complete:
+            raise UnsupportedFeatureError(f"{adapter.provider}: complete not supported")
+        run = self.middleware.wrap_complete(adapter.complete)
+        return run(request)
+
+    def stream(self, request: LMRequest, provider: str | None = None) -> Iterator[StreamEvent]:
+        adapter = self._adapter(request.model, provider)
+        if not adapter.supports.stream:
+            raise UnsupportedFeatureError(f"{adapter.provider}: stream not supported")
+        run = self.middleware.wrap_stream(adapter.stream)
+        yield from run(request)
+
+    def live(self, config: LiveConfig, provider: str | None = None) -> LiveSession:
+        adapter = self._adapter(config.model, provider)
+        if not adapter.supports.live:
+            raise UnsupportedFeatureError(f"{adapter.provider}: live not supported")
+        return adapter.live(config)
+
+    def embeddings(self, request: EmbeddingRequest, provider: str | None = None) -> EmbeddingResponse:
+        adapter = self._adapter(request.model, provider)
+        if not adapter.supports.embeddings:
+            raise UnsupportedFeatureError(f"{adapter.provider}: embeddings not supported")
+        return adapter.embeddings(request)
+
+    def file_upload(self, request: FileUploadRequest, provider: str) -> FileUploadResponse:
+        adapter = self._adapter(request.model or "", provider)
+        if not adapter.supports.files:
+            raise UnsupportedFeatureError(f"{adapter.provider}: files not supported")
+        return adapter.file_upload(request)
+
+    def batch_submit(self, request: BatchRequest, provider: str | None = None) -> BatchResponse:
+        adapter = self._adapter(request.model, provider)
+        if not adapter.supports.batches:
+            raise UnsupportedFeatureError(f"{adapter.provider}: batches not supported")
+        return adapter.batch_submit(request)
+
+    def image_generate(self, request: ImageGenerationRequest, provider: str | None = None) -> ImageGenerationResponse:
+        adapter = self._adapter(request.model, provider)
+        if not adapter.supports.images:
+            raise UnsupportedFeatureError(f"{adapter.provider}: images not supported")
+        return adapter.image_generate(request)
+
+    def audio_generate(self, request: AudioGenerationRequest, provider: str | None = None) -> AudioGenerationResponse:
+        adapter = self._adapter(request.model, provider)
+        if not adapter.supports.audio:
+            raise UnsupportedFeatureError(f"{adapter.provider}: audio not supported")
+        return adapter.audio_generate(request)

lm15-0.1.0/lm15/errors.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+
+class ULMError(Exception):
+    pass
+
+
+class TransportError(ULMError):
+    pass
+
+
+class ProviderError(ULMError):
+    pass
+
+
+class AuthError(ProviderError):
+    pass
+
+
+class RateLimitError(ProviderError):
+    pass
+
+
+class TimeoutError(ProviderError):
+    pass
+
+
+class InvalidRequestError(ProviderError):
+    pass
+
+
+class ServerError(ProviderError):
+    pass
+
+
+class UnsupportedModelError(ProviderError):
+    pass
+
+
+class UnsupportedFeatureError(ProviderError):
+    pass
+
+
+class NotConfiguredError(ProviderError):
+    pass
+
+
+def map_http_error(status: int, message: str) -> ProviderError:
+    if status in (401, 403):
+        return AuthError(message)
+    if status == 408:
+        return TimeoutError(message)
+    if status == 429:
+        return RateLimitError(message)
+    if status in (400, 404, 409, 422):
+        return InvalidRequestError(message)
+    if 500 <= status <= 599:
+        return ServerError(message)
+    return ProviderError(message)