3tears-models 0.14.0__tar.gz

3tears_models-0.14.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code local state
+.claude/
+
+# prawduct session evidence (local governance artifacts, never shipped)
+.prawduct/
+
+# macOS folder metadata
+.DS_Store

3tears_models-0.14.0/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.

3tears_models-0.14.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,34 @@
+# 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/docs/migration-aibots.md

@@ -0,0 +1,136 @@
+# Migration Guide: aibots to threetears.models
+
+## Overview
+
+The `threetears.models` package extracts provider protocols, circuit breakers, error translation, and caching from the aibots Gateway into a shared library. After migration, the aibots Gateway becomes thinner -- it routes NATS requests, enforces ACLs, and handles billing, but delegates model lifecycle to `threetears.models`.
+
+**Moves to threetears.models:**
+- Circuit breaker state machine (`CircuitBreakerRegistry`)
+- Error translation (`friendly_api_error`, `identify_provider`)
+- Provider instance caching (`ModelCache`)
+- Chat/Embedding provider adapters and protocols
+
+**Stays in aibots:**
+- Wire error codes (`ERROR_PROVIDER_RATE_LIMITED`, `ERROR_PROVIDER_OVERLOADED`, etc.)
+- Billing and cost recording
+- NATS request routing and subject handling
+- ACL enforcement (customer/agent access control)
+- Agent lifecycle management
+
+## Dependency update
+
+Add to `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "3tears-models[anthropic,openai,voyageai]",
+    # ... existing deps
+]
+```
+
+## Files to delete
+
+### `gateway/circuit_breaker.py`
+
+Replaced entirely by `CircuitBreakerRegistry` from `threetears.models`.
+
+**Before (aibots):**
+```python
+from aibots.gateway.circuit_breaker import CircuitBreaker, CIRCUIT_OPEN
+
+breaker = CircuitBreaker(provider_name="anthropic", threshold=5, timeout=30)
+if breaker.is_open():
+    raise CircuitOpenException(provider_name)
+```
+
+**After (threetears.models):**
+```python
+from threetears.models import CircuitBreakerRegistry, CircuitOpenError
+
+registry = CircuitBreakerRegistry(failure_threshold=5, recovery_timeout_seconds=30.0)
+breaker = registry.get("anthropic")
+breaker.check()  # raises CircuitOpenError if open
+```
+
+## Files to modify
+
+### `gateway/provider_pool.py`
+
+Replace hand-rolled provider pool with `ModelCache` and provider adapters.
+
+**Before:**
+```python
+from aibots.gateway.provider_pool import ProviderPool
+
+pool = ProviderPool()
+model = pool.get_or_create("anthropic", "claude-sonnet-4-6", api_key)
+response = await model.ainvoke(messages)
+```
+
+**After:**
+```python
+from threetears.models import ModelCache
+from threetears.models.providers.anthropic import AnthropicChatProvider
+
+cache = ModelCache()
+provider = cache.get("anthropic", "claude-sonnet-4-6")
+if provider is None:
+    provider = AnthropicChatProvider("claude-sonnet-4-6", api_key)
+    cache.put("anthropic", "claude-sonnet-4-6", provider)
+
+messages = [ChatMessage(role=MessageRole.USER, content="Hello")]
+result = await provider.complete(messages)
+```
+
+### `gateway/handlers/completion.py`
+
+Add `friendly_api_error()` for user-facing error text in NATS error responses.
+
+**Before:**
+```python
+except Exception as exc:
+    error_text = f"Provider error: {exc}"
+    return NatsErrorResponse(code=ERROR_PROVIDER_UNKNOWN, message=error_text)
+```
+
+**After:**
+```python
+from threetears.models import friendly_api_error
+
+except Exception as exc:
+    error_text = friendly_api_error(exc)
+    return NatsErrorResponse(code=ERROR_PROVIDER_UNKNOWN, message=error_text)
+```
+
+### `gateway/handlers/embedding.py`
+
+Replace raw LangChain embedding calls with typed providers.
+
+**Before:**
+```python
+from langchain_openai import OpenAIEmbeddings
+
+model = OpenAIEmbeddings(model=model_name, api_key=api_key)
+vectors = await model.aembed_documents([text])
+result = {"vector": vectors[0], "dimensions": len(vectors[0])}
+```
+
+**After:**
+```python
+from threetears.models.providers.openai import OpenAIEmbeddingProvider
+
+provider = OpenAIEmbeddingProvider(model_name, api_key)
+result = await provider.embed(text)
+# result is EmbeddingResult with .vector, .dimensions, .model, .token_count
+```
+
+## What stays in aibots
+
+These concerns remain in the Gateway because they are platform-specific:
+
+- **Wire error codes**: `ERROR_PROVIDER_RATE_LIMITED`, `ERROR_PROVIDER_OVERLOADED`, `ERROR_PROVIDER_AUTH`, `ERROR_PROVIDER_UNAVAILABLE` -- these are NATS envelope codes, not model-layer concerns
+- **Billing**: Cost recording, credit deduction, usage aggregation per customer
+- **ACL**: Which agents can access which providers, model-level allowlists
+- **NATS routing**: Subject patterns, queue groups, request/reply envelopes
+- **Agent lifecycle**: Agent-to-provider mapping, hot-swap on key rotation

3tears_models-0.14.0/docs/migration-metallm.md

@@ -0,0 +1,188 @@
+# Migration Guide: metallm to threetears.models
+
+## Overview
+
+metallm has the most to migrate. The `threetears.models` package replaces metallm's provider layer, embedding service, whisper service, image backends, circuit breaker, and streaming recovery logic. After migration, metallm focuses on personality, NSFW handling, content pipeline, and frontend API.
+
+**Moves to threetears.models:**
+- Chat providers (Anthropic, OpenAI, OpenRouter)
+- Embedding service (OpenAI, VoyageAI)
+- Whisper transcription service
+- Image generation backends (OpenAI, HuggingFace, A1111, ModelsLab, ComfyUI)
+- Circuit breaker
+- Streaming chunk merging and tool call recovery
+- Message preprocessing (alternating roles, vision content)
+
+**Stays in metallm:**
+- NSFW content detection and filtering
+- Personality system and persona management
+- Content pipeline (summarization, extraction, formatting)
+- Frontend HTTP API
+- DuckDB local caching layer
+
+## Dependency update
+
+Add to `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "3tears-models[anthropic,openai,openrouter,voyageai,whisper,image]",
+    # ... existing deps
+]
+```
+
+## Files to delete
+
+### `graph/providers.py`
+
+Provider creation and management replaced by `threetears.models` adapters and `ModelCache`.
+
+### `services/embedding.py`
+
+Replaced by `OpenAIEmbeddingProvider` and `VoyageAIEmbeddingProvider`.
+
+**Before:**
+```python
+from metallm.services.embedding import EmbeddingService
+
+svc = EmbeddingService(provider="openai", model="text-embedding-3-small", api_key=key)
+vector = await svc.embed(text)
+```
+
+**After:**
+```python
+from threetears.models.providers.openai import OpenAIEmbeddingProvider
+
+provider = OpenAIEmbeddingProvider("text-embedding-3-small", api_key)
+result = await provider.embed(text)
+vector = result.vector
+```
+
+### `services/whisper.py`
+
+Replaced by `WhisperTranscriptionProvider`.
+
+**Before:**
+```python
+from metallm.services.whisper import WhisperService
+
+svc = WhisperService(api_key=key)
+text = await svc.transcribe(audio_bytes, mime_type="audio/mp3")
+```
+
+**After:**
+```python
+from threetears.models.providers.whisper import WhisperTranscriptionProvider
+
+provider = WhisperTranscriptionProvider(api_key=key)
+result = await provider.transcribe(audio_bytes, "audio/mp3")
+text = result.text
+segments = result.segments  # optional time-aligned segments
+```
+
+### `services/image_backends/*.py`
+
+All image generation backends replaced by `threetears.models.providers.image` module.
+
+**Before:**
+```python
+from metallm.services.image_backends.openai_backend import OpenAIImageBackend
+
+backend = OpenAIImageBackend(api_key=key)
+image_bytes = await backend.generate(prompt, size="1024x1024")
+```
+
+**After:**
+```python
+from threetears.models.providers.image import OpenAIImageProvider
+
+provider = OpenAIImageProvider(api_key=key)
+# provider implements ImageGenerationProvider protocol
+```
+
+### `cache/circuit_breaker.py`
+
+Replaced by `CircuitBreakerRegistry`.
+
+## Files to modify
+
+### `graph/nodes/personality.py`
+
+Replace inline streaming recovery with shared helpers.
+
+**Before:**
+```python
+# inline chunk accumulation and tool call fixup
+content_parts = []
+tool_calls = []
+for chunk in chunks:
+    content_parts.append(chunk.content)
+    if chunk.tool_calls:
+        tool_calls.extend(chunk.tool_calls)
+# manual split detection
+if len(tool_calls) >= 2:
+    fixed = _fix_split_tool_calls(tool_calls)
+```
+
+**After:**
+```python
+from threetears.models.streaming import merge_chunks, recover_split_tool_calls
+
+result = merge_chunks(chunks)
+if result.tool_calls:
+    result = ChatResult(
+        content=result.content,
+        tool_calls=recover_split_tool_calls(result.tool_calls),
+        model=result.model,
+        usage=result.usage,
+    )
+```
+
+Use `preprocess_messages()` before sending to providers that require alternating roles:
+
+```python
+from threetears.models.preprocessing import preprocess_messages
+from threetears.models.capabilities import ModelCapabilities
+
+capabilities = ModelCapabilities(
+    model_name="claude-sonnet-4-6",
+    model_type=ModelType.CHAT,
+    model_tier=ModelTier.LARGE,
+    model_status=ModelStatus.ACTIVE,
+    requires_alternating_roles=True,
+)
+processed = preprocess_messages(messages, capabilities)
+result = await provider.complete(processed)
+```
+
+### `services/media_adapters.py`
+
+Replace inline base64 encoding with `format_vision_content()`.
+
+**Before:**
+```python
+import base64
+b64 = base64.b64encode(image_bytes).decode()
+content = [
+    {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{b64}"}},
+    {"type": "text", "text": prompt},
+]
+```
+
+**After:**
+```python
+from threetears.models.preprocessing import format_vision_content
+
+content = format_vision_content(image_bytes, mime_type, prompt)
+```
+
+## What stays in metallm
+
+These concerns remain because they are application-specific:
+
+- **NSFW handling**: Content detection, filtering, and policy enforcement
+- **Personality system**: Persona definitions, system prompt generation, personality switching
+- **Content pipeline**: Summarization chains, extraction pipelines, output formatting
+- **Frontend API**: HTTP routes, WebSocket handlers, session management
+- **DuckDB caching**: Local query cache, conversation history, analytics aggregation