3tears-models 0.14.0__py3-none-any.whl

3tears_models-0.14.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: 3tears-models
+Version: 0.14.0
+Summary: LangChain-native AI model factories with capability metadata, circuit breakers, and usage tracking for the 3tears platform
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: 3tears-media-contracts
+Requires-Dist: 3tears-observe
+Requires-Dist: langchain-anthropic>=1.4
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-openai>=1.1
+Requires-Dist: langchain-openrouter>=0.1
+Requires-Dist: pydantic>=2.0
+Provides-Extra: claude-cli
+Requires-Dist: langchain-claude-code>=0.1.0; extra == 'claude-cli'
+Provides-Extra: image
+Requires-Dist: httpx>=0.27; extra == 'image'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
+Provides-Extra: voyageai
+Requires-Dist: langchain-voyageai>=0.3; extra == 'voyageai'
+Provides-Extra: whisper
+Requires-Dist: httpx>=0.27; extra == 'whisper'
+Description-Content-Type: text/markdown
+
+# 3tears-models
+
+LangChain-native AI model factories for the 3tears framework. Build chat and embedding models from a single call, with capability metadata, circuit breakers, error translation, and usage tracking wired in.
+
+```bash
+pip install 3tears-models
+```
+
+## What you get
+
+- **Factories** -- `create_chat_model()` and `create_embedding_model()` return standard LangChain `BaseChatModel` / `Embeddings` instances. No custom runtime protocols to learn.
+- **Providers** -- Anthropic, OpenAI, OpenRouter, VoyageAI, Whisper, and image backends (OpenAI Images, HuggingFace, A1111, ModelsLab, ComfyUI).
+- **Capability registry** -- `get_capabilities()`, `register_capabilities()`, and per-model overrides describe context windows, vision support, tool support, and tier.
+- **Circuit breakers** -- `CircuitBreaker` and `CircuitBreakerRegistry` trip on repeated provider failures and recover on a timer.
+- **Usage tracking** -- `UsageTracker.record()` emits an OpenTelemetry span plus Prometheus instruments, with optional per-application audit and counter sinks.
+- **Message hygiene** -- `preprocess_messages()`, `enforce_alternating_roles()`, `filter_invalid_tool_calls()`, and streaming chunk helpers (`parse_chunk`, `merge_chunks`).
+
+## Quickstart
+
+```python
+from threetears.models import create_chat_model, create_embedding_model
+
+chat = create_chat_model("claude-sonnet-4-6")
+reply = await chat.ainvoke("Summarize three-tier caching in one sentence.")
+
+embedder = create_embedding_model("voyage-3")
+vectors = await embedder.aembed_documents(["first doc", "second doc"])
+```
+
+Capabilities, circuit breakers, and usage tracking attach automatically. Reach for the registry and tracker APIs directly when you need to inspect or override them.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

3tears_models-0.14.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+threetears/models/__init__.py,sha256=cQyOaVkoaBJXPo_IL_sCeiNB4cFvHinEzah-SesDyHE,5657
+threetears/models/cache.py,sha256=DW4AJd1UevXfz1PdH8EMNTzBatQDWyhZw9m3RTLdC-I,3107
+threetears/models/capabilities.py,sha256=J3oRJk0Nb5h6B_JaxVdoqBiGKosnAllxi17zm6KPHEI,18304
+threetears/models/chunk_merging.py,sha256=xYAY3pjYzoiJJL_LXM-vf4q_fQ9v70vc533DjyCZvA8,3212
+threetears/models/chunk_parsing.py,sha256=0jsb0N0wNTSeOpxONqEiKHPX8MZEPiZFCehMacVvRMg,4940
+threetears/models/circuit_breaker.py,sha256=bsFOABv-NcMWgcRLEfalNZ-uBGF-XLwostE_I0HgqfU,12745
+threetears/models/defaults.py,sha256=XjSNKGCes1pWcnv-QxENrG-h2V23KfnKzLypumszFcE,2985
+threetears/models/enums.py,sha256=bMYt-u4TcEuxU8g5d_t-R7alJ8OV7oifI6e_9_rQSQ0,1414
+threetears/models/errors.py,sha256=zbMfwLHQRqQ7ItXErAKApj8ml7q4CbNdUy7Nry8jyss,5695
+threetears/models/factory.py,sha256=rD-63YsFmzrBVWh29aRUtzmUPhrIWMK0k4uPlFg4uEo,11709
+threetears/models/preprocessing.py,sha256=IWt2mK6ekja8ByjO9SEDDnjf7BqUFC8_ZXyhEEIZRHc,6784
+threetears/models/price_lookup.py,sha256=816Vr6HCz4eKHytOFhcpD-CxbSXLCBXGA_I5w1snDOM,26326
+threetears/models/registry.py,sha256=YqLHaXKllPySTdHNP84BMpXaY7u3QuO1DsdiFLnyacs,3951
+threetears/models/registry_loader.py,sha256=9tGewFaiWmElOPhOb6sb0xFCVODeBuIVaSuq4AJGAzw,8057
+threetears/models/tool_name_translation.py,sha256=JQhRmHUQBo0lEDikomYyYbaXXXAaO5hDtGWypnf1tZc,12800
+threetears/models/tool_name_validation.py,sha256=5ioli_7YiNO_uHyi-1Gqket3DP1EyS6uXvj4DwnELeA,8235
+threetears/models/tracking.py,sha256=oz03j3f2uvXhjQDsRwBRcWHxCA7f7Bj6SGjaqjj6Fdg,36681
+threetears/models/providers/__init__.py,sha256=NPwLiadG-79CDvCgQrRc7FcqAlnDTR3yw6lc5bEEGS0,361
+threetears/models/providers/_claude_cli.py,sha256=GlSl19krhGoOG8wKhh9S5RH4eZnz0oWsnzl2Tn3lKOg,5158
+threetears/models/providers/_voyageai_compat.py,sha256=POymh980gmoAlfzBys_QYo71x6H8n_ultkqGSOvpWt4,2936
+threetears/models/providers/anthropic.py,sha256=1d1GPbVNfg16XOXdKaFpCduBpsC5rZ1vVd0ivj-Ebys,23307
+threetears/models/providers/openai.py,sha256=uNYkzOj5S7kI-Hdz6a7bM3a66lWtkg2-NYQp52ANQXc,13000
+threetears/models/providers/openrouter.py,sha256=S8_m86yhKpMeDut8VSlNsENceulAAWxdKfa_6mFWJw4,25158
+threetears/models/providers/voyageai.py,sha256=ISTS2S9EFsl9eoJlOs2k5aDm4LD1iAqBr_Sb306dMQM,3783
+threetears/models/providers/whisper.py,sha256=-SAZ7xsV2n573MhdSR_QARwJIxDilyFC9HsKuzme9JY,6428
+threetears/models/providers/image/__init__.py,sha256=KD63m-c8RYPcM9izGx8EpkGgQ1gkeE2r3TEBC4AW6gY,824
+threetears/models/providers/image/a1111.py,sha256=VnbsY8KhDVqBDpdtEQ16nLVN4-I9ZmBxp38pTm7KklI,3813
+threetears/models/providers/image/comfyui.py,sha256=Poh-3rRYAysA_Mxv0qtyFZxk0VYJFI6jCA2SY4ImM9w,6645
+threetears/models/providers/image/huggingface.py,sha256=yaLAL2Hnw9jt_m3TtnOwYTcyg4dNZl29VKQkixAwYN8,3069
+threetears/models/providers/image/modelslab.py,sha256=7GZm1DYrPlsILD3MB9zCuCLUgDZYiTzEftCBDVseX7k,4866
+threetears/models/providers/image/openai.py,sha256=8hU4gjcC9_aaCO6y-V6Kgw5S4MbtBpwFX71517CiKvA,5847
+3tears_models-0.14.0.dist-info/METADATA,sha256=ckSKxqk5tO7k4pTCCXfZ3_RIpLx6IIcnIIHDcBWUj2o,2816
+3tears_models-0.14.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+3tears_models-0.14.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears_models-0.14.0.dist-info/RECORD,,

3tears_models-0.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

3tears_models-0.14.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+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.

threetears/models/__init__.py

@@ -0,0 +1,175 @@
+"""LangChain-native AI model factories with capability metadata, circuit
+breakers, and usage tracking.
+
+3tears v0.6.0+ exposes provider factory functions that return configured
+LangChain ``BaseChatModel`` and ``Embeddings`` instances. The legacy
+``ChatProvider`` / ``EmbeddingProvider`` / ``TranscriptionProvider`` /
+``SpeechProvider`` / ``RerankingProvider`` runtime protocols have been
+removed.
+
+Importing this package eagerly loads the builtin provider modules so
+their import-time :func:`register_capabilities` calls populate the
+shared registry. This makes :func:`create_chat_model` /
+:func:`create_embedding_model` work for every builtin model id without
+the caller manually importing ``threetears.models.providers.<name>``.
+The provider modules themselves keep ``langchain_<provider>`` imports
+inside ``TYPE_CHECKING`` and inside their factory bodies, so the
+eager-load only pulls capability metadata — actually instantiating a
+provider model still imports its langchain backend lazily, preserving
+the "install only the providers you use" property for production
+callers.
+
+v0.9.0 adds chat-model utility modules used across every consumer:
+:mod:`threetears.models.chunk_merging` (merge streamed AIMessageChunks
+into a single AIMessage), :mod:`threetears.models.chunk_parsing`
+(extract text + reasoning per chunk), and
+:mod:`threetears.models.tool_name_validation` (defend against
+malformed tool names emitted by misbehaving providers). The
+OpenRouter and Anthropic wrappers invoke the validator on every
+response so junk tool names never reach downstream dispatch.
+"""
+
+from __future__ import annotations
+
+from threetears.models.cache import ModelCache
+from threetears.models.capabilities import (
+    CapabilityOverride,
+    ModelCapabilities,
+    clear_capability_overrides,
+    get_capabilities,
+    get_capability_override,
+    list_capabilities,
+    register_capabilities,
+    register_capability_override,
+    unregister_capability_override,
+)
+from threetears.models.defaults import (
+    CURRENT_ANTHROPIC_CHAT_MODELS,
+    CURRENT_VOYAGEAI_EMBEDDING_MODELS,
+    DEFAULT_CHAT_MODEL,
+    DEFAULT_EMBEDDING_MODEL,
+    DEFAULT_FAST_MODEL,
+    DEFAULT_LARGE_MODEL,
+)
+from threetears.models.chunk_merging import merge_chunks
+from threetears.models.chunk_parsing import ChunkParsed, parse_chunk
+from threetears.models.circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerCallback,
+    CircuitBreakerRegistry,
+    CircuitOpenError,
+    CircuitState,
+)
+from threetears.models.enums import ModelStatus, ModelTier, ModelType
+from threetears.models.errors import friendly_api_error, identify_provider
+from threetears.models.factory import create_chat_model, create_embedding_model
+from threetears.models.preprocessing import (
+    enforce_alternating_roles,
+    format_vision_content,
+    preprocess_messages,
+)
+from threetears.models.price_lookup import (
+    OPENROUTER_MODELS_URL,
+    VOYAGE_PRICING_URL,
+    ModelOption,
+    OpenRouterPriceSource,
+    PriceLookup,
+    PriceSource,
+    VoyagePriceSource,
+    default_price_sources,
+    fetch_provider_models,
+    list_provider_models,
+    lookup_price,
+    match_price,
+    register_price_source,
+)
+from threetears.models.registry import BUILTIN_PROVIDERS, ProviderRegistry
+from threetears.models.tool_name_validation import (
+    ToolNameValidationError,
+    filter_invalid_tool_calls,
+    is_valid_tool_name,
+    validate_tool_name,
+)
+from threetears.models.tracking import (
+    LlmPurpose,
+    UsageAuditSink,
+    UsageCounterSink,
+    UsageRecord,
+    UsageTracker,
+    UsageTrackingCallback,
+)
+
+# Eager-import builtin provider modules so their import-time
+# `register_capabilities()` calls populate the shared registry. The
+# provider modules themselves do not import their respective
+# `langchain_<provider>` package at module scope (those imports live
+# inside TYPE_CHECKING + factory bodies) so this is metadata-only.
+from threetears.models.providers import (  # noqa: E402, F401
+    anthropic as _anthropic_caps,
+    openai as _openai_caps,
+    openrouter as _openrouter_caps,
+    voyageai as _voyageai_caps,
+    whisper as _whisper_caps,
+)
+
+__all__ = [
+    "BUILTIN_PROVIDERS",
+    "CURRENT_ANTHROPIC_CHAT_MODELS",
+    "CURRENT_VOYAGEAI_EMBEDDING_MODELS",
+    "DEFAULT_CHAT_MODEL",
+    "DEFAULT_EMBEDDING_MODEL",
+    "DEFAULT_FAST_MODEL",
+    "DEFAULT_LARGE_MODEL",
+    "CapabilityOverride",
+    "ChunkParsed",
+    "CircuitBreaker",
+    "CircuitBreakerCallback",
+    "CircuitBreakerRegistry",
+    "CircuitOpenError",
+    "CircuitState",
+    "LlmPurpose",
+    "ModelCache",
+    "ModelCapabilities",
+    "ModelOption",
+    "ModelStatus",
+    "ModelTier",
+    "ModelType",
+    "OPENROUTER_MODELS_URL",
+    "OpenRouterPriceSource",
+    "PriceLookup",
+    "PriceSource",
+    "ProviderRegistry",
+    "VOYAGE_PRICING_URL",
+    "VoyagePriceSource",
+    "ToolNameValidationError",
+    "UsageAuditSink",
+    "UsageCounterSink",
+    "UsageRecord",
+    "UsageTracker",
+    "UsageTrackingCallback",
+    "clear_capability_overrides",
+    "create_chat_model",
+    "create_embedding_model",
+    "default_price_sources",
+    "enforce_alternating_roles",
+    "fetch_provider_models",
+    "filter_invalid_tool_calls",
+    "format_vision_content",
+    "friendly_api_error",
+    "get_capabilities",
+    "get_capability_override",
+    "identify_provider",
+    "is_valid_tool_name",
+    "list_capabilities",
+    "list_provider_models",
+    "lookup_price",
+    "match_price",
+    "merge_chunks",
+    "parse_chunk",
+    "preprocess_messages",
+    "register_capabilities",
+    "register_capability_override",
+    "register_price_source",
+    "unregister_capability_override",
+    "validate_tool_name",
+]

threetears/models/cache.py

@@ -0,0 +1,99 @@
+"""thread-safe instance cache for model provider objects."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+__all__ = [
+    "ModelCache",
+]
+
+
+class ModelCache:
+    """thread-safe cache for model provider instances.
+
+    stores instantiated model objects keyed by (provider_name, model_name)
+    tuple to avoid re-instantiation on every request. supports selective
+    eviction for API key rotation and provider shutdown scenarios.
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[tuple[str, str], Any] = {}
+        self._lock: threading.Lock = threading.Lock()
+
+    def get(self, provider_name: str, model_name: str) -> Any | None:
+        """retrieve cached model instance.
+
+        :param provider_name: provider identifier (e.g. "anthropic")
+        :ptype provider_name: str
+        :param model_name: model identifier (e.g. "claude-sonnet-4-6")
+        :ptype model_name: str
+        :return: cached instance or None if not found
+        :rtype: Any | None
+        """
+        with self._lock:
+            result = self._cache.get((provider_name, model_name))
+        return result
+
+    def put(self, provider_name: str, model_name: str, instance: Any) -> None:
+        """store model instance in cache.
+
+        :param provider_name: provider identifier
+        :ptype provider_name: str
+        :param model_name: model identifier
+        :ptype model_name: str
+        :param instance: model instance to cache
+        :ptype instance: Any
+        """
+        with self._lock:
+            self._cache[(provider_name, model_name)] = instance
+
+    def evict(self, provider_name: str, model_name: str) -> bool:
+        """remove specific model instance from cache.
+
+        :param provider_name: provider identifier
+        :ptype provider_name: str
+        :param model_name: model identifier
+        :ptype model_name: str
+        :return: True if entry was found and removed, False if not found
+        :rtype: bool
+        """
+        with self._lock:
+            key = (provider_name, model_name)
+            if key in self._cache:
+                del self._cache[key]
+                found = True
+            else:
+                found = False
+        return found
+
+    def evict_provider(self, provider_name: str) -> int:
+        """remove all cached instances for given provider.
+
+        :param provider_name: provider identifier
+        :ptype provider_name: str
+        :return: number of entries removed
+        :rtype: int
+        """
+        with self._lock:
+            keys_to_remove = [key for key in self._cache if key[0] == provider_name]
+            for key in keys_to_remove:
+                del self._cache[key]
+            count = len(keys_to_remove)
+        return count
+
+    def clear(self) -> None:
+        """remove all entries from cache."""
+        with self._lock:
+            self._cache.clear()
+
+    def size(self) -> int:
+        """return number of cached entries.
+
+        :return: current cache size
+        :rtype: int
+        """
+        with self._lock:
+            result = len(self._cache)
+        return result