langchaint 0.3.0__tar.gz

langchaint-0.3.0/LICENSE

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

langchaint-0.3.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: langchaint
+Version: 0.3.0
+Summary: It ain't langchain.
+Keywords: llm,anthropic,openai,claude,async
+Author: John Hopfensperger
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: anthropic>=0.116.0 ; extra == 'all'
+Requires-Dist: openai>=2.45.0 ; extra == 'all'
+Requires-Dist: anthropic>=0.116.0 ; extra == 'anthropic'
+Requires-Dist: openai>=2.45.0 ; extra == 'openai'
+Requires-Dist: opentelemetry-api>=1.30.0 ; extra == 'otel'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/s-banach/langchaint
+Project-URL: Repository, https://github.com/s-banach/langchaint
+Project-URL: Issues, https://github.com/s-banach/langchaint/issues
+Provides-Extra: all
+Provides-Extra: anthropic
+Provides-Extra: openai
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+# langchaint
+
+Provider-neutral async LLM client over the official provider SDKs (anthropic >= 0.116.0, openai >= 2.45.0).
+Alpha: the API is unstable and may change without notice.
+
+## Design
+
+**Generation only via binding.**
+`LLM` has no generate methods.
+`LLM.bind(...) -> BoundLLM[OutputT]` freezes everything that determines the cacheable prompt prefix: `system_prompt`, `tool_manager`, `inference_params`, `tool_choice`, `parallel_tool_calls`, `automatic_prompt_caching`.
+`response_format` is frozen too, as the field that fixes the output type.
+`automatic_prompt_caching` has no default: caching changes billing, so every `bind` states it.
+A `TextPart` or `ImagePart` with `cache_breakpoint=True` places a prompt-cache boundary at exactly that part, under either `automatic_prompt_caching` value, so binding `False` and marking parts is the fully user-specified caching configuration.
+`generate_many(conversations, warm_cache=True)` runs the first conversation to completion before admitting the rest, so a batch sharing a cached prefix pays one cache write instead of one per in-flight item; it is opt-in because it costs one item of serial latency.
+`system_prompt` also binds as a sequence of `TextPart`s, so a boundary can sit inside the frozen prefix (stable instructions marked, semi-stable context after).
+There are no per-call parameter overrides; changing parameters is `rebind(...)`, which returns a new `BoundLLM` with the SDK keyword arguments converted again.
+`bind(response_format=Model)` returns `BoundLLM[Model]`; without `response_format` it returns `BoundLLM[str]`, selected by overload.
+`rebind` carries the same overload, so `rebind(response_format=Model)` switches the output type to `BoundLLM[Model]`, `rebind(response_format=None)` switches it back to `BoundLLM[str]`, and leaving it out keeps the current type.
+Every generate and stream method takes a conversation of `Message`s; a bare `str` is accepted as shorthand for a conversation of one `UserMessage` holding that text.
+
+**The catalog is a constructor function per backend returning a ready LLM (anthropic adds a second for Bedrock).**
+`from langchaint.openai import openai_model` then `openai_model("gpt-5.6-terra")`, and `from langchaint.anthropic import anthropic_model` then `anthropic_model("claude-sonnet-5")`, take the provider's own model identifier (a `Literal`, so typos fail the type check), look up the public prices, construct the adapter, and wrap it in an `LLM`.
+`client=None` constructs the native first-party SDK client from environment credentials.
+Anthropic Bedrock is a second sibling constructor, `anthropic_bedrock_model(model, aws_region=...)`: it names the same catalog model and reads the model's Bedrock surface (which of two SDK client classes) and wire model id from a table, so the application names neither the client class nor the Bedrock id.
+Constructing an adapter directly covers models outside the catalog.
+
+**The SDKs are optional dependencies, one extra per backend.**
+The neutral core (`LLM`, the message tree, the error taxonomy) imports no SDK, so `import langchaint` needs neither package.
+Each backend lives in its own subpackage that imports its SDK at module top: install `langchaint[openai]` or `langchaint[anthropic]` (or `langchaint[all]`) for the ones you use, and importing `langchaint.openai` without the openai package raises a `ModuleNotFoundError` naming the extra to install.
+The import path is the boundary: only code that reaches for a backend requires its SDK, and a type checker following `langchaint.openai` never resolves anthropic's types.
+OTel tracing follows the same pattern: `langchaint.tracing` imports only opentelemetry-api, install `langchaint[otel]`, and it stays off `import langchaint`.
+
+**Adapters wrap SDK clients and delegate to the SDK.**
+`AnthropicMessagesProvider(client=AsyncAnthropic(...))` and `OpenAIResponsesProvider(client=AsyncOpenAI(...))` call `messages.create/parse/stream` and `responses.create/parse/stream`; stream assembly and structured-output parsing are the SDK's, not hand-written.
+Adapters store a `with_options(max_retries=0)` copy of the client, so the SDK never retries beneath the package's retry loop.
+OpenAI support is the Responses API only: every supported OpenAI model speaks it, so there is no Chat Completions adapter.
+The adapter always sends `store=False` because conversation state is the caller's conversation argument.
+Anthropic Bedrock is two distinct SDK surfaces, the legacy `InvokeModel` client `AsyncAnthropicBedrock` and the Messages-API client `AsyncAnthropicBedrockMantle`, and the catalog models split across them, so `anthropic_bedrock_model` reads the client class and wire model id per model from `ANTHROPIC_BEDROCK`.
+OpenAI on Bedrock is the bundled `AsyncBedrockOpenAI` passed as `client`; there is no Converse adapter.
+Requests travel as typed frozen dataclasses whose optional fields are `X | Omit`, passed to the SDK as explicit keywords: no `**kwargs`, no hand-written wire TypedDicts, and the SDK overloads resolve without casts.
+
+**Anthropic prompt caching is placed by the adapter.**
+A bind-time `cache_control` marker goes on the system block (or the last tool when there is no system prompt), and a per-request marker goes on the last block of the last message, so the breakpoint follows a growing conversation.
+Placement is manual because `messages.parse` lacks the top-level `cache_control` parameter; manual placement keeps create/parse/stream uniform.
+Every marker's TTL is the adapter's `cache_ttl` (`"5m"` default, `"1h"` for entries that must survive longer gaps at 2x write cost), a keyword of `anthropic_model` and `anthropic_bedrock_model`.
+
+**Usage counters partition, cost is the adapter's job.**
+`Usage` stores `input_tokens_cache_read`, `input_tokens_cache_write`, `input_tokens_cache_none`, and `output_tokens`; the three input counters are a disjoint partition and `input_tokens_total` is derived.
+`input_tokens_total_provider_reported` holds what the provider itself reported: openai's `input_tokens` includes cached and cache-write tokens, so the adapter fills it and a validator cross-checks the partition; anthropic reports no all-inclusive total, so it stays None.
+The counters are validated non-negative, which is what guards the openai path: there the partition is derived by subtraction and sums to the reported total by construction.
+`cost_in_usd` is computed inside the adapter from raw provider counts against a `PricingTable`, because providers split counters the normalized `Usage` collapses: anthropic bills 5-minute and 1-hour cache writes at different rates, and an adapter that sees 1-hour writes without `cache_write_1h_usd_per_million_tokens` raises `AbortBatchError` rather than misbill.
+
+**Success is a `Response`, failure is a `GenerationError`.**
+A generate that succeeds returns a frozen `Response[OutputT]` with every field present; one that ends terminally raises (or, in a batch, returns) a `GenerationError`.
+Its three leaves are the terminal per-item outcomes: `RetriesExhaustedError` (transient budget spent), `RefusalError` (the model refused on the structured path), and `ExceededMaxCompletionTokensError` (the structured response hit the token cap before its JSON parsed).
+On the base, `stop_reason` is `StopReason | None`: `"refusal"` or `"max_tokens"` on those two leaves, `None` on `RetriesExhaustedError`, whose attempts never reached a completed turn.
+Both hold `attempt_records`, one `AttemptRecord` per request sent: raw `time.monotonic()` start and end readings bracketing the send only (slot waits and backoff sleeps excluded, so rate limiting is distinguishable from slow requests), the attempt's `TransientError` (None on the attempt that succeeded or a rejected 200), and the attempt's `usage`/`cost_in_usd` (None for a transport failure that billed nothing).
+On a `Response` every record but the last failed; on a `GenerationError` the records describe the terminal outcome.
+`attempts` is derived from the records on both.
+Both also carry `model`, `provider_name`, and `elapsed_seconds` (first request to completion, waits included, so stored rather than derived), so the module-level `to_row(result)` flattens either to the same scalar keys and a mixed list of successes and failures is one table.
+A `GenerationError` derives `usage`/`cost_in_usd` from its records, so a refusal or truncation reports its real cost while a retry-exhausted item whose attempts billed nothing reports zero; `error_text` carries the failure reason.
+On a `Response`, `usage`, `cost_in_usd` (the successful attempt's own), `stop_reason`, `assistant_message`, and `raw` are always present.
+`raw` is the SDK's own response model held by reference; it is never dumped to a dict, because dumping deep-copies every response body per request.
+
+**One RateLimiter owns retrying and pacing.**
+`RateLimiter` holds `max_attempts`, `backoff_base_seconds`, `backoff_max_seconds`, and `max_in_flight`; it is stateful and shareable, so one instance passed to several `LLM`s is one shared budget for the account they hit.
+Its slot gates every request start on every path (first attempts, retries, batch items, stream openings); backoff sleeps outside the slot.
+There is deliberately no `requests_per_minute`: an in-flight bound self-adjusts throughput along request duration, while a client-side rate number models one dimension of the provider's multi-dimensional limit and goes stale with the account tier.
+A rate-limit error (`Provider.classify` returning `"rate_limit"`, or any error naming a server-stated retry-after) pauses admission for everyone sharing the limiter: for the server-stated wait when one was sent (parsed from the `retry-after-ms` / `retry-after` headers onto `TransientError.retry_after_seconds`, capped at 60 seconds), else for the failing task's backoff delay.
+After the pause, admission stays limited to one probe request at a time until the probe succeeds; other transient errors (timeouts, 5xx) pause nobody, because they say nothing about the account's quota.
+
+**Retry stays in the package, classification in the adapter.**
+Adapters raise `TransientError`, `AbortBatchError`, or a `GenerationError` leaf directly where they know the answer: rate limits and overload (transient), a bad request (abort), and an empty structured parse, which splits three ways (a refusal is `RefusalError`, a token-cap truncation is `ExceededMaxCompletionTokensError`, anything else is `TransientError`).
+The retry loop retries only `TransientError`; it honors the rest without asking.
+Unrecognized exceptions go through `Provider.classify`, which returns `"rate_limit"`, `"transient"`, or `"abort"`, and anything it does not recognize is abort.
+`generate_one` raises `RetriesExhaustedError` for transient exhaustion, `RefusalError` or `ExceededMaxCompletionTokensError` on the structured path, and `AbortBatchError` for an abort classification; the first three share the `GenerationError` base a caller can catch at once.
+`generate_many` returns `list[Response[OutputT] | GenerationError]`, so a terminal per-item failure is a row in its slot rather than a raise, while an `AbortBatchError` still cancels the siblings and raises; results stay order-aligned.
+
+**Streaming is a handle.**
+`stream_one` returns a `StreamHandle`: an async iterator of `StreamItem = str | ToolCall`, an idempotent `await handle.final()` returning the assembled `Response`, and an async context manager so abandoning a stream closes the connection.
+Text chunks are the provider SDK's own strings passed through without a wrapper class or copy, and each `ToolCall` is yielded once, complete, when its block closes.
+There are deliberately no tool-call delta items (a consumer cannot act on partial argument JSON, and both SDKs accumulate the arguments and hand over the finished call) and no usage or stop items (usage, `cost_in_usd`, and `stop_reason` live on `final()`'s `Response`, and a bare-`str` stop reason could not share a union with bare-`str` text chunks).
+Connection failures before the first yielded item retry under the `RateLimiter`; after the first yielded item nothing retries, because replaying chunks the caller already consumed would duplicate output.
+An open stream holds one `RateLimiter` slot from opening until it closes or exhausts, so long-lived streams count against `max_in_flight`.
+
+**Tools are explicit, dispatch is owned.**
+A `Tool` is an async function taking one pydantic model and returning str or a sequence of content parts (text and images the model then sees), plus an explicit name and description; the args model is the schema source, so there is no signature introspection and no docstring scraping.
+Tool content is model-facing, so it is exactly `MessageContent` (`str | Sequence[Part]`, the model-facing message body, aliased in `messages.py`): a function with a typed result serializes it to that form itself.
+A function may instead return a `ToolOutputExplicit` wrapping that content plus `is_error` and `app_data` (the app-facing channel, which does carry a typed `BaseModel` or `Mapping` the model never sees).
+`Tool.validate_and_run` validates raw call JSON against `args_model` and runs the function; it lives on `Tool` because there the args type parameter is concrete, so the validated arguments reach the function fully typed.
+`Tool.dispatch` returns `DispatchHandled[AppDataT] | DispatchInvalidToolArgs`, so on the handled outcome a caller that dispatched a known tool reads `app_data` back at its concrete type with no `isinstance`.
+`ToolManager` serializes the tools provider-neutrally, resolves the called name, and returns each outcome as a `DispatchOutcome`, a three-arm union over a heterogeneous tool set (where `app_data` erases to `BaseModel | Mapping[str, object] | None`): `DispatchHandled` carries the model-facing `ToolMessage` the caller appends to the conversation, paired with the function's `app_data` (data the model never sees); `DispatchInvalidToolArgs` carries a default `is_error` `ToolMessage` plus the pydantic `ValidationError` as a required field, so a caller that authors its own reply reads `validation_error.errors()` with no narrowing crutch; `DispatchUnknownTool` carries a default `is_error` `ToolMessage` naming the held tools plus the off-list `called_name`.
+Every arm carries `tool_message`, so a caller that only appends the reply reads `result.tool_message` with no `match`.
+An off-list tool name becomes a `DispatchUnknownTool` outcome rather than a raise, just like argument JSON the model got wrong becomes a `DispatchInvalidToolArgs` outcome: both are model data the model can correct (a provider can emit a name outside the sent schemas, and a rebind can strand an earlier turn's `tool_call`).
+`tool_choice` is the neutral vocabulary `"auto" | "required" | SpecificTool | "none"` (anthropic's `"any"` maps from `"required"`); `parallel_tool_calls: bool` maps to anthropic `disable_parallel_tool_use` and openai `parallel_tool_calls`.
+
+**The ReAct loop is a recipe, not vendored code.**
+There is no agent class.
+The loop is ~15 lines and is correct because the hard parts (retries, pacing, classification, validation) live below `generate_one` and `dispatch`, so a hand-copied loop cannot be subtly wrong.
+The non-streaming loop runs over `generate_one`; the streaming loop runs over `stream_one`, printing text chunks as they arrive and dispatching the completed `ToolCall`s between turns, reading `dispatch(call).tool_message` for the ToolMessage it appends and matching `DispatchHandled` for the function's model-invisible `app_data` or `DispatchInvalidToolArgs` for the `validation_error`.
+Owning the loop is what lets a caller enforce a budget mid-run, stream tokens, or swap the binding on a tool result, none of which a fixed agent surface exposes.
+
+## Layout
+
+    CLAUDE.md                design, naming, and review rules
+    README.md                this file
+    src/langchaint/
+        messages.py          message and part models, StopReason
+        usage.py             Usage counters
+        inference_params.py  InferenceParams
+        exceptions.py        error vocabulary: TransientError,
+                             AbortBatchError, AttemptRecord,
+                             GenerationError and its leaves
+        response.py          Response[OutputT], to_row
+        rate_limiter.py      RateLimiter
+        tools.py             Tool, ToolSchema, ToolManager
+        provider.py          Binding, ToolChoice, PricingTable,
+                             StreamItem, ProviderResult,
+                             ProviderStream, BoundProvider, Provider
+        streaming.py         StreamHandle
+        llm.py               LLM, BoundLLM, the retry loop
+        anthropic/           the anthropic backend (needs the anthropic
+                             SDK): __init__ has anthropic_model,
+                             ANTHROPIC_PRICING, AnthropicModelName;
+                             messages_provider.py has the adapter
+                             AnthropicMessagesProvider
+        openai/              the openai backend (needs the openai SDK):
+                             __init__ has openai_model, OPENAI_PRICING,
+                             OpenAIModelName; responses_provider.py has
+                             the adapter OpenAIResponsesProvider
+        tracing/             OTel span tracing (needs opentelemetry-api,
+                             install langchaint[otel]): __init__ has
+                             TracedLLM, TracedBoundLLM, TracedStreamHandle
+
+## Verification
+
+Run `scripts/CI.sh`; it runs `pyrefly check`, `ruff check`, and `pytest` through `uv run`, so the tools resolve from the locked dev dependency group, not a hand-activated `.venv`.
+All must pass with zero errors.
+The tests are offline: they feed constructed SDK objects into the adapter helpers and drive `BoundLLM`/`StreamHandle` with stub providers, so they need no API keys.

langchaint-0.3.0/README.md

@@ -0,0 +1,139 @@
+# langchaint
+
+Provider-neutral async LLM client over the official provider SDKs (anthropic >= 0.116.0, openai >= 2.45.0).
+Alpha: the API is unstable and may change without notice.
+
+## Design
+
+**Generation only via binding.**
+`LLM` has no generate methods.
+`LLM.bind(...) -> BoundLLM[OutputT]` freezes everything that determines the cacheable prompt prefix: `system_prompt`, `tool_manager`, `inference_params`, `tool_choice`, `parallel_tool_calls`, `automatic_prompt_caching`.
+`response_format` is frozen too, as the field that fixes the output type.
+`automatic_prompt_caching` has no default: caching changes billing, so every `bind` states it.
+A `TextPart` or `ImagePart` with `cache_breakpoint=True` places a prompt-cache boundary at exactly that part, under either `automatic_prompt_caching` value, so binding `False` and marking parts is the fully user-specified caching configuration.
+`generate_many(conversations, warm_cache=True)` runs the first conversation to completion before admitting the rest, so a batch sharing a cached prefix pays one cache write instead of one per in-flight item; it is opt-in because it costs one item of serial latency.
+`system_prompt` also binds as a sequence of `TextPart`s, so a boundary can sit inside the frozen prefix (stable instructions marked, semi-stable context after).
+There are no per-call parameter overrides; changing parameters is `rebind(...)`, which returns a new `BoundLLM` with the SDK keyword arguments converted again.
+`bind(response_format=Model)` returns `BoundLLM[Model]`; without `response_format` it returns `BoundLLM[str]`, selected by overload.
+`rebind` carries the same overload, so `rebind(response_format=Model)` switches the output type to `BoundLLM[Model]`, `rebind(response_format=None)` switches it back to `BoundLLM[str]`, and leaving it out keeps the current type.
+Every generate and stream method takes a conversation of `Message`s; a bare `str` is accepted as shorthand for a conversation of one `UserMessage` holding that text.
+
+**The catalog is a constructor function per backend returning a ready LLM (anthropic adds a second for Bedrock).**
+`from langchaint.openai import openai_model` then `openai_model("gpt-5.6-terra")`, and `from langchaint.anthropic import anthropic_model` then `anthropic_model("claude-sonnet-5")`, take the provider's own model identifier (a `Literal`, so typos fail the type check), look up the public prices, construct the adapter, and wrap it in an `LLM`.
+`client=None` constructs the native first-party SDK client from environment credentials.
+Anthropic Bedrock is a second sibling constructor, `anthropic_bedrock_model(model, aws_region=...)`: it names the same catalog model and reads the model's Bedrock surface (which of two SDK client classes) and wire model id from a table, so the application names neither the client class nor the Bedrock id.
+Constructing an adapter directly covers models outside the catalog.
+
+**The SDKs are optional dependencies, one extra per backend.**
+The neutral core (`LLM`, the message tree, the error taxonomy) imports no SDK, so `import langchaint` needs neither package.
+Each backend lives in its own subpackage that imports its SDK at module top: install `langchaint[openai]` or `langchaint[anthropic]` (or `langchaint[all]`) for the ones you use, and importing `langchaint.openai` without the openai package raises a `ModuleNotFoundError` naming the extra to install.
+The import path is the boundary: only code that reaches for a backend requires its SDK, and a type checker following `langchaint.openai` never resolves anthropic's types.
+OTel tracing follows the same pattern: `langchaint.tracing` imports only opentelemetry-api, install `langchaint[otel]`, and it stays off `import langchaint`.
+
+**Adapters wrap SDK clients and delegate to the SDK.**
+`AnthropicMessagesProvider(client=AsyncAnthropic(...))` and `OpenAIResponsesProvider(client=AsyncOpenAI(...))` call `messages.create/parse/stream` and `responses.create/parse/stream`; stream assembly and structured-output parsing are the SDK's, not hand-written.
+Adapters store a `with_options(max_retries=0)` copy of the client, so the SDK never retries beneath the package's retry loop.
+OpenAI support is the Responses API only: every supported OpenAI model speaks it, so there is no Chat Completions adapter.
+The adapter always sends `store=False` because conversation state is the caller's conversation argument.
+Anthropic Bedrock is two distinct SDK surfaces, the legacy `InvokeModel` client `AsyncAnthropicBedrock` and the Messages-API client `AsyncAnthropicBedrockMantle`, and the catalog models split across them, so `anthropic_bedrock_model` reads the client class and wire model id per model from `ANTHROPIC_BEDROCK`.
+OpenAI on Bedrock is the bundled `AsyncBedrockOpenAI` passed as `client`; there is no Converse adapter.
+Requests travel as typed frozen dataclasses whose optional fields are `X | Omit`, passed to the SDK as explicit keywords: no `**kwargs`, no hand-written wire TypedDicts, and the SDK overloads resolve without casts.
+
+**Anthropic prompt caching is placed by the adapter.**
+A bind-time `cache_control` marker goes on the system block (or the last tool when there is no system prompt), and a per-request marker goes on the last block of the last message, so the breakpoint follows a growing conversation.
+Placement is manual because `messages.parse` lacks the top-level `cache_control` parameter; manual placement keeps create/parse/stream uniform.
+Every marker's TTL is the adapter's `cache_ttl` (`"5m"` default, `"1h"` for entries that must survive longer gaps at 2x write cost), a keyword of `anthropic_model` and `anthropic_bedrock_model`.
+
+**Usage counters partition, cost is the adapter's job.**
+`Usage` stores `input_tokens_cache_read`, `input_tokens_cache_write`, `input_tokens_cache_none`, and `output_tokens`; the three input counters are a disjoint partition and `input_tokens_total` is derived.
+`input_tokens_total_provider_reported` holds what the provider itself reported: openai's `input_tokens` includes cached and cache-write tokens, so the adapter fills it and a validator cross-checks the partition; anthropic reports no all-inclusive total, so it stays None.
+The counters are validated non-negative, which is what guards the openai path: there the partition is derived by subtraction and sums to the reported total by construction.
+`cost_in_usd` is computed inside the adapter from raw provider counts against a `PricingTable`, because providers split counters the normalized `Usage` collapses: anthropic bills 5-minute and 1-hour cache writes at different rates, and an adapter that sees 1-hour writes without `cache_write_1h_usd_per_million_tokens` raises `AbortBatchError` rather than misbill.
+
+**Success is a `Response`, failure is a `GenerationError`.**
+A generate that succeeds returns a frozen `Response[OutputT]` with every field present; one that ends terminally raises (or, in a batch, returns) a `GenerationError`.
+Its three leaves are the terminal per-item outcomes: `RetriesExhaustedError` (transient budget spent), `RefusalError` (the model refused on the structured path), and `ExceededMaxCompletionTokensError` (the structured response hit the token cap before its JSON parsed).
+On the base, `stop_reason` is `StopReason | None`: `"refusal"` or `"max_tokens"` on those two leaves, `None` on `RetriesExhaustedError`, whose attempts never reached a completed turn.
+Both hold `attempt_records`, one `AttemptRecord` per request sent: raw `time.monotonic()` start and end readings bracketing the send only (slot waits and backoff sleeps excluded, so rate limiting is distinguishable from slow requests), the attempt's `TransientError` (None on the attempt that succeeded or a rejected 200), and the attempt's `usage`/`cost_in_usd` (None for a transport failure that billed nothing).
+On a `Response` every record but the last failed; on a `GenerationError` the records describe the terminal outcome.
+`attempts` is derived from the records on both.
+Both also carry `model`, `provider_name`, and `elapsed_seconds` (first request to completion, waits included, so stored rather than derived), so the module-level `to_row(result)` flattens either to the same scalar keys and a mixed list of successes and failures is one table.
+A `GenerationError` derives `usage`/`cost_in_usd` from its records, so a refusal or truncation reports its real cost while a retry-exhausted item whose attempts billed nothing reports zero; `error_text` carries the failure reason.
+On a `Response`, `usage`, `cost_in_usd` (the successful attempt's own), `stop_reason`, `assistant_message`, and `raw` are always present.
+`raw` is the SDK's own response model held by reference; it is never dumped to a dict, because dumping deep-copies every response body per request.
+
+**One RateLimiter owns retrying and pacing.**
+`RateLimiter` holds `max_attempts`, `backoff_base_seconds`, `backoff_max_seconds`, and `max_in_flight`; it is stateful and shareable, so one instance passed to several `LLM`s is one shared budget for the account they hit.
+Its slot gates every request start on every path (first attempts, retries, batch items, stream openings); backoff sleeps outside the slot.
+There is deliberately no `requests_per_minute`: an in-flight bound self-adjusts throughput along request duration, while a client-side rate number models one dimension of the provider's multi-dimensional limit and goes stale with the account tier.
+A rate-limit error (`Provider.classify` returning `"rate_limit"`, or any error naming a server-stated retry-after) pauses admission for everyone sharing the limiter: for the server-stated wait when one was sent (parsed from the `retry-after-ms` / `retry-after` headers onto `TransientError.retry_after_seconds`, capped at 60 seconds), else for the failing task's backoff delay.
+After the pause, admission stays limited to one probe request at a time until the probe succeeds; other transient errors (timeouts, 5xx) pause nobody, because they say nothing about the account's quota.
+
+**Retry stays in the package, classification in the adapter.**
+Adapters raise `TransientError`, `AbortBatchError`, or a `GenerationError` leaf directly where they know the answer: rate limits and overload (transient), a bad request (abort), and an empty structured parse, which splits three ways (a refusal is `RefusalError`, a token-cap truncation is `ExceededMaxCompletionTokensError`, anything else is `TransientError`).
+The retry loop retries only `TransientError`; it honors the rest without asking.
+Unrecognized exceptions go through `Provider.classify`, which returns `"rate_limit"`, `"transient"`, or `"abort"`, and anything it does not recognize is abort.
+`generate_one` raises `RetriesExhaustedError` for transient exhaustion, `RefusalError` or `ExceededMaxCompletionTokensError` on the structured path, and `AbortBatchError` for an abort classification; the first three share the `GenerationError` base a caller can catch at once.
+`generate_many` returns `list[Response[OutputT] | GenerationError]`, so a terminal per-item failure is a row in its slot rather than a raise, while an `AbortBatchError` still cancels the siblings and raises; results stay order-aligned.
+
+**Streaming is a handle.**
+`stream_one` returns a `StreamHandle`: an async iterator of `StreamItem = str | ToolCall`, an idempotent `await handle.final()` returning the assembled `Response`, and an async context manager so abandoning a stream closes the connection.
+Text chunks are the provider SDK's own strings passed through without a wrapper class or copy, and each `ToolCall` is yielded once, complete, when its block closes.
+There are deliberately no tool-call delta items (a consumer cannot act on partial argument JSON, and both SDKs accumulate the arguments and hand over the finished call) and no usage or stop items (usage, `cost_in_usd`, and `stop_reason` live on `final()`'s `Response`, and a bare-`str` stop reason could not share a union with bare-`str` text chunks).
+Connection failures before the first yielded item retry under the `RateLimiter`; after the first yielded item nothing retries, because replaying chunks the caller already consumed would duplicate output.
+An open stream holds one `RateLimiter` slot from opening until it closes or exhausts, so long-lived streams count against `max_in_flight`.
+
+**Tools are explicit, dispatch is owned.**
+A `Tool` is an async function taking one pydantic model and returning str or a sequence of content parts (text and images the model then sees), plus an explicit name and description; the args model is the schema source, so there is no signature introspection and no docstring scraping.
+Tool content is model-facing, so it is exactly `MessageContent` (`str | Sequence[Part]`, the model-facing message body, aliased in `messages.py`): a function with a typed result serializes it to that form itself.
+A function may instead return a `ToolOutputExplicit` wrapping that content plus `is_error` and `app_data` (the app-facing channel, which does carry a typed `BaseModel` or `Mapping` the model never sees).
+`Tool.validate_and_run` validates raw call JSON against `args_model` and runs the function; it lives on `Tool` because there the args type parameter is concrete, so the validated arguments reach the function fully typed.
+`Tool.dispatch` returns `DispatchHandled[AppDataT] | DispatchInvalidToolArgs`, so on the handled outcome a caller that dispatched a known tool reads `app_data` back at its concrete type with no `isinstance`.
+`ToolManager` serializes the tools provider-neutrally, resolves the called name, and returns each outcome as a `DispatchOutcome`, a three-arm union over a heterogeneous tool set (where `app_data` erases to `BaseModel | Mapping[str, object] | None`): `DispatchHandled` carries the model-facing `ToolMessage` the caller appends to the conversation, paired with the function's `app_data` (data the model never sees); `DispatchInvalidToolArgs` carries a default `is_error` `ToolMessage` plus the pydantic `ValidationError` as a required field, so a caller that authors its own reply reads `validation_error.errors()` with no narrowing crutch; `DispatchUnknownTool` carries a default `is_error` `ToolMessage` naming the held tools plus the off-list `called_name`.
+Every arm carries `tool_message`, so a caller that only appends the reply reads `result.tool_message` with no `match`.
+An off-list tool name becomes a `DispatchUnknownTool` outcome rather than a raise, just like argument JSON the model got wrong becomes a `DispatchInvalidToolArgs` outcome: both are model data the model can correct (a provider can emit a name outside the sent schemas, and a rebind can strand an earlier turn's `tool_call`).
+`tool_choice` is the neutral vocabulary `"auto" | "required" | SpecificTool | "none"` (anthropic's `"any"` maps from `"required"`); `parallel_tool_calls: bool` maps to anthropic `disable_parallel_tool_use` and openai `parallel_tool_calls`.
+
+**The ReAct loop is a recipe, not vendored code.**
+There is no agent class.
+The loop is ~15 lines and is correct because the hard parts (retries, pacing, classification, validation) live below `generate_one` and `dispatch`, so a hand-copied loop cannot be subtly wrong.
+The non-streaming loop runs over `generate_one`; the streaming loop runs over `stream_one`, printing text chunks as they arrive and dispatching the completed `ToolCall`s between turns, reading `dispatch(call).tool_message` for the ToolMessage it appends and matching `DispatchHandled` for the function's model-invisible `app_data` or `DispatchInvalidToolArgs` for the `validation_error`.
+Owning the loop is what lets a caller enforce a budget mid-run, stream tokens, or swap the binding on a tool result, none of which a fixed agent surface exposes.
+
+## Layout
+
+    CLAUDE.md                design, naming, and review rules
+    README.md                this file
+    src/langchaint/
+        messages.py          message and part models, StopReason
+        usage.py             Usage counters
+        inference_params.py  InferenceParams
+        exceptions.py        error vocabulary: TransientError,
+                             AbortBatchError, AttemptRecord,
+                             GenerationError and its leaves
+        response.py          Response[OutputT], to_row
+        rate_limiter.py      RateLimiter
+        tools.py             Tool, ToolSchema, ToolManager
+        provider.py          Binding, ToolChoice, PricingTable,
+                             StreamItem, ProviderResult,
+                             ProviderStream, BoundProvider, Provider
+        streaming.py         StreamHandle
+        llm.py               LLM, BoundLLM, the retry loop
+        anthropic/           the anthropic backend (needs the anthropic
+                             SDK): __init__ has anthropic_model,
+                             ANTHROPIC_PRICING, AnthropicModelName;
+                             messages_provider.py has the adapter
+                             AnthropicMessagesProvider
+        openai/              the openai backend (needs the openai SDK):
+                             __init__ has openai_model, OPENAI_PRICING,
+                             OpenAIModelName; responses_provider.py has
+                             the adapter OpenAIResponsesProvider
+        tracing/             OTel span tracing (needs opentelemetry-api,
+                             install langchaint[otel]): __init__ has
+                             TracedLLM, TracedBoundLLM, TracedStreamHandle
+
+## Verification
+
+Run `scripts/CI.sh`; it runs `pyrefly check`, `ruff check`, and `pytest` through `uv run`, so the tools resolve from the locked dev dependency group, not a hand-activated `.venv`.
+All must pass with zero errors.
+The tests are offline: they feed constructed SDK objects into the adapter helpers and drive `BoundLLM`/`StreamHandle` with stub providers, so they need no API keys.

langchaint-0.3.0/pyproject.toml

@@ -0,0 +1,203 @@
+[project]
+name = "langchaint"
+version = "0.3.0"
+description = "It ain't langchain."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "John Hopfensperger" }]
+requires-python = ">=3.13"
+keywords = ["llm", "anthropic", "openai", "claude", "async"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.13.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/s-banach/langchaint"
+Repository = "https://github.com/s-banach/langchaint"
+Issues = "https://github.com/s-banach/langchaint/issues"
+
+[project.optional-dependencies]
+# One extra per backend: the langchaint.anthropic / langchaint.openai subpackages
+# import their SDK at module top, so an application installs only the backends it uses.
+anthropic = ["anthropic>=0.116.0"]
+openai = ["openai>=2.45.0"]
+all = ["anthropic>=0.116.0", "openai>=2.45.0"]
+# The langchaint.tracing subpackage imports only opentelemetry-api (trace, Tracer,
+# Status, StatusCode); a production app installs the api and wires its own SDK,
+# matching OTel's api/sdk split. Deliberately not folded into all, which stays
+# backends-only: an app that wants both SDKs but no tracing must not pull OTel.
+otel = ["opentelemetry-api>=1.30.0"]
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "langchaint[all]",
+    "langchaint[otel]",
+    # opentelemetry-sdk is needed only by the tracing tests' in-memory exporter
+    # (InMemorySpanExporter, SimpleSpanProcessor, TracerProvider); the wrapper
+    # itself imports only opentelemetry-api.
+    "opentelemetry-sdk>=1.30.0",
+    "pytest>=9.0.2",
+    "pyrefly>=1.2.0.dev2",
+    "ruff>=0.15.20",
+    "typos>=1.48.0",
+]
+
+[tool.pyrefly]
+preset = "strict"
+# project-includes bounds type checking to exactly these trees (leaving the developer
+# tooling under scripts/ out); search-path is the separate import-resolution setting, "src"
+# being the langchaint import root.
+project-includes = ["src", "tests", "examples"]
+# src is the langchaint import root; the repo root is added so cross-module test
+# imports (tests.test_bound_llm reused by tests.test_tracing) resolve the same way
+# pytest resolves them at runtime.
+search-path = ["src", "."]
+
+# Enabled above strict: redundant-cast enforces the "no cast" smell's
+# stale half (every finding is a deletable cast), and deprecated flags
+# stdlib/library deprecations before an upgrade breaks them.
+# explicit-any stays off: the remaining Any sites are deliberate
+# existential typing (overload implementations, SDK stream generics,
+# the heterogeneous Tool collection), and suppressions on deliberate
+# Any would only add noise. When pyrefly 1.2.0 lands, also enable
+# implicit-any-variable (inference gaps that silently make a variable
+# Any): the tree is clean for it since Tool.validate_and_run owns the
+# typed validate-then-call pair, but 1.1.1 rejects the rule name.
+[tool.pyrefly.errors]
+redundant-cast = "error"
+deprecated = "error"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 99
+format.preview = true
+
+lint.preview = true
+lint.explicit-preview-rules = true
+lint.select = [
+    "ANN",
+    "BLE",
+    "FBT",
+    "PERF",
+    "A",
+    "B",
+    "INP",
+    "PIE",
+    "PT",
+    "RET",
+    "RSE",
+    "SLF",
+    "SIM",
+    "SLOT",
+    "TID",
+    "TC",
+    "ARG",
+    "LOG",
+    "G",
+    "PTH",
+    "FLY",
+    "I",
+    "N",
+    "F",
+    "PL",
+    "UP",
+    "FURB",
+    "RUF",
+    "TRY",
+    "W505",  # doc-line-too-long, capped by pycodestyle.max-doc-length below
+    # Docstrings, selected as exact codes with no pydocstyle convention.
+    # The dropped google convention was an ignore-overlay whose removals
+    # the code satisfies anyway, and it ignored D401, which then needed an
+    # exact-code select to win over the convention. Deliberately absent:
+    # D203 and D213, which conflict with D211 and D212; D405-D414 and
+    # D416, which enforce underlined rst/numpy section headers instead of
+    # the Args:/Raises:/Yields: prose sections used here; and the preview
+    # rules D420 (incorrect-section-order) and D421
+    # (property-docstring-starts-with-verb), not opted into: D421 flags a
+    # verb-first property docstring, which the imperative mood used
+    # everywhere here (D401) would otherwise produce.
+    "D100",  # undocumented-public-module
+    "D101",  # undocumented-public-class
+    "D102",  # undocumented-public-method
+    "D103",  # undocumented-public-function
+    "D104",  # undocumented-public-package
+    "D105",  # undocumented-magic-method
+    "D106",  # undocumented-public-nested-class
+    "D107",  # undocumented-public-init
+    "D200",  # unnecessary-multiline-docstring
+    "D201",  # blank-line-before-function
+    "D202",  # blank-line-after-function
+    "D204",  # incorrect-blank-line-after-class
+    "D205",  # missing-blank-line-after-summary
+    "D206",  # docstring-tab-indentation
+    "D207",  # under-indentation
+    "D208",  # over-indentation
+    "D209",  # new-line-after-last-paragraph
+    "D210",  # surrounding-whitespace
+    "D211",  # blank-line-before-class
+    "D212",  # multi-line-summary-first-line
+    "D214",  # overindented-section
+    "D215",  # overindented-section-underline
+    "D300",  # triple-single-quotes
+    "D301",  # escape-sequence-in-docstring
+    "D400",  # missing-trailing-period
+    "D401",  # non-imperative-mood
+    "D402",  # signature-in-docstring
+    "D403",  # first-word-uncapitalized
+    "D404",  # docstring-starts-with-this
+    "D415",  # missing-terminal-punctuation
+    "D417",  # undocumented-param
+    "D418",  # overload-with-docstring
+    "D419",  # empty-docstring
+    # Preview docstring features
+    "DOC202",  # docstring documents a return that does not exist
+    "DOC402",  # missing "Yields" in docstring
+    "DOC403",  # docstring documents a yield that does not exist
+    # DOC501 (raised exception missing) and DOC502 (documents an exception not
+    # raised) are deliberately absent. Both resolve a raise only for the literal
+    # `raise SomeError(...)` / `raise SomeError` shapes; they cannot see through
+    # `raise type(exc)(...)` (re-raising the same leaf class enriched) or
+    # `raise Class.factory(...)` (they read the last attribute, `factory`, as the
+    # exception name), both of which this package uses. Under them a correctly
+    # documented raise reports as extraneous and a real raise reports as missing,
+    # so documenting raises is a CLAUDE.md convention (see "Document what a
+    # function raises") checked in review instead.
+]
+lint.ignore = [
+    "ANN401",
+    "SIM105",
+    "PLR2004",
+    "TRY003",
+]
+
+# Docstrings and comments break lines at sentence boundaries, not at a column
+# width; a sentence longer than this cap breaks at a clause boundary. Code
+# stays at line-length 99 via the formatter; E501 is deliberately unselected.
+lint.pycodestyle.max-doc-length = 120
+lint.flake8-tidy-imports.ban-relative-imports = "all"
+lint.pylint.max-args = 7
+
+# The tests exercise private helpers and attributes directly (Provider._request,
+# BoundLLM._bound_provider); those accesses are the unit under test, so SLF001
+# (private-member-access) cannot be satisfied without exposing internals.
+lint.per-file-ignores."tests/*" = ["SLF001"]
+
+# The examples are standalone scripts run by path (python examples/01_basics.py),
+# deliberately not an importable package, so INP001 (implicit-namespace-package,
+# which would demand an examples/__init__.py) does not apply.
+lint.per-file-ignores."examples/*" = ["INP001"]
+
+[tool.typos.default.extend-words]

langchaint-0.3.0/src/langchaint/__init__.py

@@ -0,0 +1,98 @@
+"""langchaint: a provider-neutral LLM client.
+
+Adapters wrap the official anthropic/openai SDK clients; generation happens only through LLM.bind(...) -> BoundLLM.
+"""
+
+from langchaint.exceptions import (
+    AbortBatchError,
+    AttemptRecord,
+    ExceededMaxCompletionTokensError,
+    GenerationError,
+    InvalidToolArgsError,
+    RefusalError,
+    RetriesExhaustedError,
+    StreamProtocolError,
+    TransientError,
+)
+from langchaint.inference_params import InferenceParams, ReasoningEffort
+from langchaint.llm import LLM, BoundLLM
+from langchaint.messages import (
+    AssistantMessage,
+    ImagePart,
+    Message,
+    MessageContent,
+    Part,
+    ReasoningTrace,
+    StopReason,
+    TextPart,
+    ToolCall,
+    ToolMessage,
+    TurnElement,
+    UserMessage,
+)
+from langchaint.provider import (
+    PricingTable,
+    SpecificTool,
+    StreamItem,
+    ToolChoice,
+)
+from langchaint.rate_limiter import RateLimiter
+from langchaint.response import Response, RowValue, to_row
+from langchaint.streaming import StreamHandle
+from langchaint.tools import (
+    DispatchHandled,
+    DispatchInvalidToolArgs,
+    DispatchOutcome,
+    DispatchUnknownTool,
+    Tool,
+    ToolManager,
+    ToolOutput,
+    ToolOutputExplicit,
+)
+from langchaint.usage import Usage
+
+__all__ = [
+    "LLM",
+    "AbortBatchError",
+    "AssistantMessage",
+    "AttemptRecord",
+    "BoundLLM",
+    "DispatchHandled",
+    "DispatchInvalidToolArgs",
+    "DispatchOutcome",
+    "DispatchUnknownTool",
+    "ExceededMaxCompletionTokensError",
+    "GenerationError",
+    "ImagePart",
+    "InferenceParams",
+    "InvalidToolArgsError",
+    "Message",
+    "MessageContent",
+    "Part",
+    "PricingTable",
+    "RateLimiter",
+    "ReasoningEffort",
+    "ReasoningTrace",
+    "RefusalError",
+    "Response",
+    "RetriesExhaustedError",
+    "RowValue",
+    "SpecificTool",
+    "StopReason",
+    "StreamHandle",
+    "StreamItem",
+    "StreamProtocolError",
+    "TextPart",
+    "Tool",
+    "ToolCall",
+    "ToolChoice",
+    "ToolManager",
+    "ToolMessage",
+    "ToolOutput",
+    "ToolOutputExplicit",
+    "TransientError",
+    "TurnElement",
+    "Usage",
+    "UserMessage",
+    "to_row",
+]