cendor-core 0.1.12__tar.gz

cendor_core-0.1.12/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.uv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+.DS_Store
+*.log
+
+# MkDocs build output (local preview only)
+site/

cendor_core-0.1.12/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog — cendor-core
+
+All notable changes to this package. Format: [Keep a Changelog](https://keepachangelog.com).
+Consumers pin `cendor-core>=0.1,<0.2`, so the `0.1.x` line stays additive and backward-compatible.
+
+## [0.1.12] — 2026-07-01
+### Added
+- **Reasoning-token accounting.** `Usage` gains a `reasoning_tokens` field — the portion of the output a reasoning/thinking model spent on internal reasoning. `instrument()` populates it from every adapter that reports it: OpenAI's `completion_tokens_details.reasoning_tokens` and Gemini's `thoughts_token_count` (both non-streaming and streaming). It's a **subset of** `output_tokens` (like `cached_tokens` is a subset of input), so it's a breakdown, not extra tokens — `total_tokens` and cost are unchanged (reasoning is already billed inside `output_tokens` at the output rate). Anthropic/Bedrock/Ollama fold thinking into `output_tokens` with no separate count, so `reasoning_tokens` stays `0` there. Flows automatically into `acttrace` audit records.
+### Fixed
+- **Gemini reasoning-model under-count.** Gemini reports `thoughts_token_count` **separately** from `candidates_token_count`, and both are billed as output. `_extract_usage` previously read only `candidates_token_count`, so thinking-model calls were under-counted (and under-costed). Thoughts are now folded into the output total and surfaced as `reasoning_tokens`. Non-thinking Gemini calls are unaffected (no `thoughts_token_count` → `0`).
+
+All additive and backward-compatible — `reasoning_tokens` defaults to `0`, so existing `Usage(...)` construction and equality are unchanged.
+
+## [0.1.11] — 2026-06-27
+### Added
+- **Live price-source adapters.** `prices.refresh(source="litellm"|"openrouter"|"azure")` pulls current rates from unauthenticated static-JSON sources — a community aggregator (LiteLLM), a gateway (OpenRouter), and the Azure Retail Prices catalog — with **no credentials, no SDKs, and no new dependencies**. The direct model labs (OpenAI/Anthropic) expose no pricing API, so those sources fill the gap. `refresh(url=…, mapper=…)` maps any other source onto our schema, and source ids are normalized to bare keys (`openai/gpt-4o` → `gpt-4o`) so refreshed rates line up with `estimate()`. Still offline-safe: static http(s) only, mapped **in memory** (nothing persisted), silent fallback to the last-good table. New `prices.sources()`, `prices.source_name()`, `prices.source_url()`.
+- **Price staleness signal.** `prices.age_days()` and `prices.is_stale(max_age_days=30)` let callers tell when the offline snapshot is old. The bundled snapshot was expanded with more current models and re-dated.
+- **Cost provenance labeling.** `instrument()` now prefers a provider-/gateway-reported cost when the response carries one (e.g. OpenRouter's `usage.cost`) and tags `call.metadata["cost_reported"]=True`; otherwise it prices from the snapshot and tags `call.metadata["cost_estimated"]=True` — so a real billed figure is distinguishable from an estimate (mirrors the existing `usage_estimated` flag). An unknown model with no reported cost still leaves `cost=None`.
+- **Real streamed usage for OpenAI.** `instrument()` auto-injects `stream_options={"include_usage": True}` for OpenAI streams (unless the caller set `stream_options`), so streamed usage is the provider's real billed count instead of an offline estimate.
+
+All additive and backward-compatible — `prices.refresh()` keeps its existing signature and offline-safe contract.
+
+## [0.1.10] — 2026-06-25
+### Added
+- **Streaming responses.** `instrument()` now handles `stream=True` for sync and async clients: the chunk iterator is passed through to the caller **unchanged** while usage is accumulated, and the `LLMCall` is emitted **once when the stream completes** (or is closed early) — with usage, cost, and true end-to-end latency. Usage is read from the provider's own stream reporting where present (OpenAI's final usage chunk via `stream_options={"include_usage": True}`, Anthropic's `message_start`/`message_delta` events, Bedrock's `metadata` event, Gemini/Ollama final-chunk usage); when a provider streams no usage, it falls back to an **offline token estimate** flagged `call.metadata["usage_estimated"] = True`. Streamed calls carry `call.metadata["streamed"] = True`, with the collected chunks at `call.metadata["response"]` so `cassette` can record/replay them. Previously a streamed call returned an unconsumed iterator and emitted no usable usage/cost (so `tokenguard` saw `$0` per streamed call). Bedrock's separate `converse_stream` entrypoint is still not wrapped — use `converse`.
+
+### Fixed
+- **Thread-safety.** The event bus (`subscribe`/`unsubscribe`/`emit`) and the `instrument` interceptor registry (`add_interceptor`/`remove_interceptor`) are now lock-guarded, and `emit`/`_intercept` fan out over a snapshot taken under the lock then **released before** invoking subscribers — so a subscriber may safely (un)subscribe from another thread, or from inside its own callback, without corrupting the list or deadlocking. Closes a latent race when subscribers were registered/removed concurrently with dispatch.
+
+## [0.1.9] — 2026-06-24
+### Added
+- `bus.unsubscribe(fn)` — the inverse of `bus.subscribe`, so a tool can register a *temporary* subscriber and tear it down cleanly (e.g. cassette's per-run recorder) instead of reaching into the internal subscriber list. Idempotent; no error if the callable isn't registered.
+
+### Fixed
+- `bus.emit` now runs **every** subscriber even if one raises — one tool's failure can no longer starve another (a logging subscriber's bug skipping `tokenguard`'s enforcement, or vice versa, depending on registration order). The first `Exception` is re-raised after all subscribers run, so intentional control flow (`tokenguard`'s post-flight `BudgetExceeded`/`_Truncated`) still propagates; `BaseException` (`KeyboardInterrupt`/`SystemExit`) is not caught.
+- Price tables are parsed with `parse_float=Decimal`, so per-token rates are exact from the JSON text and never round-trip through `float` (the stack's money-is-Decimal rule). Bundled values were already float-exact; this protects high-precision refreshed tables.
+- `prices.refresh()` fetches static JSON over **http(s) only** and rejects other URL schemes (e.g. `file://`), so it can't be pointed at a local file; still never raises and falls back to the bundled snapshot.
+
+## [0.1.8] — 2026-06-23
+### Changed
+- Packaging: `LICENSE` and `NOTICE` are now bundled in the distribution (`dist-info/licenses/`), so the Apache-2.0 terms — including the §7 warranty disclaimer and §8 liability limitation — travel inside every wheel/sdist. The README footer states the "as is" / no-warranty / use-at-your-own-risk terms. No code changes.
+
+## [0.1.7] — 2026-06-23
+### Added
+- `tokens.method(model)` and `tokens.is_exact(model)` report which counting path is active — `exact` (OpenAI + tiktoken), `bpe-estimate`, `registered`, or `heuristic` — so callers can surface their confidence.
+### Changed
+- Token counting is **accurate-first**. With the `[tiktoken]` extra installed, Claude/Gemini now use tiktoken's `o200k` BPE as a close cross-tokenizer estimate (far better than the character heuristic) rather than the offline subword fallback; OpenAI stays exact. The char/subword heuristic is now explicitly the offline-only fallback, and the docs drop the fixed "~10-15%" accuracy claim for it (a single constant can't track modern tokenizers across prose/code/JSON — install `[tiktoken]` for accuracy).
+
+## [0.1.6] — 2026-06-23
+### Changed
+- Relicensed from MIT to Apache-2.0 — adds an explicit patent grant and contribution terms, a better fit for a public library suite.
+- README links to the docs page and CHANGELOG are now absolute GitHub URLs so they resolve on PyPI (they previously broke as repo-relative paths).
+
+## [0.1.5] — 2026-06-23
+### Fixed
+- Gemini: `instrument()` now reads the model id from the `GenerativeModel` (`model_name`, `models/` prefix stripped), so the emitted `LLMCall` carries a real, priceable model instead of an empty one.
+
+## [0.1.4] — 2026-06-23
+### Added
+- `instrument()` adapters for AWS Bedrock (`converse`), Google Gemini (`generate_content`), and Ollama (`chat`), on top of OpenAI + Anthropic.
+- `tokens.family` detects the `google` family and Bedrock-style prefixed ids (e.g. `anthropic.claude-…`).
+- Bundled prices for `gemini-2.0-flash`, `gemini-1.5-pro`, and `llama3` (local, $0).
+- `otel.ingest(attributes)` — turns OpenTelemetry `gen_ai.*` span attributes into a normalized `LLMCall` on the bus (the managed-runtime capture path).
+
+## [0.1.3] — 2026-06-23
+### Changed
+- Anthropic/Gemini token counting now uses a blended char + subword-piece estimator (structure-aware; deterministic, offline). Best-effort; register a precise counter for exactness.
+
+## [0.1.2] — 2026-06-23
+### Added
+- `prices.SNAPSHOT_URL` — `prices.refresh()` defaults to a hosted static snapshot, with silent fallback to the bundled table when offline.
+
+## [0.1.1] — 2026-06-23
+### Added
+- `Reroute` interceptor directive (lets an interceptor rewrite the outgoing request, e.g. swap the model); request kwargs exposed on `call.metadata`.
+
+## [0.1.0] — 2026-06-23
+### Added
+- Initial release: `types` (`LLMCall`, `ToolCall`, `Usage`, Decimal `Money`), provider-aware `tokens.count`, offline `prices` + `estimate`, `instrument`/`instrument_tool` (sync + async, idempotent, with record/replay hooks), in-process `bus`, minimal `otel`, and structural `protocols` (`Compressor`, `EvictionStrategy`, `Sink`, `Subscriber`, `Handle`).
+
+[0.1.12]: https://pypi.org/project/cendor-core/0.1.12/
+[0.1.11]: https://pypi.org/project/cendor-core/0.1.11/
+[0.1.10]: https://pypi.org/project/cendor-core/0.1.10/
+[0.1.9]: https://pypi.org/project/cendor-core/0.1.9/
+[0.1.8]: https://pypi.org/project/cendor-core/0.1.8/
+[0.1.7]: https://pypi.org/project/cendor-core/0.1.7/
+[0.1.6]: https://pypi.org/project/cendor-core/0.1.6/
+[0.1.5]: https://pypi.org/project/cendor-core/0.1.5/
+[0.1.4]: https://pypi.org/project/cendor-core/0.1.4/
+[0.1.3]: https://pypi.org/project/cendor-core/0.1.3/
+[0.1.2]: https://pypi.org/project/cendor-core/0.1.2/
+[0.1.1]: https://pypi.org/project/cendor-core/0.1.1/
+[0.1.0]: https://pypi.org/project/cendor-core/0.1.0/

cendor_core-0.1.12/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Raghav Mishra (PowerAI Labs)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cendor_core-0.1.12/NOTICE

@@ -0,0 +1,7 @@
+PowerAI Labs
+Copyright 2026 Raghav Mishra (PowerAI Labs)
+
+This product includes software developed by Raghav Mishra (PowerAI Labs).
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file for the
+full terms.

cendor_core-0.1.12/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: cendor-core
+Version: 0.1.12
+Summary: Foundation for the PowerAI Labs stack: shared types, token counting, offline-first & refreshable prices, instrument(), event bus, OTel.
+Author: Raghav Mishra
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+# cendor-core
+
+The shared foundation for the Cendor stack: canonical types, provider-aware token counting,
+an offline price table, one `instrument()` interception point, an in-process event bus, and
+OpenTelemetry GenAI emitters. Tiny on purpose — it's the blast radius for every other tool.
+
+**One `instrument()` call, every sibling tool observes the stream — no per-call wiring, offline by default.**
+
+![PyPI](https://img.shields.io/pypi/v/cendor-core) ![license](https://img.shields.io/badge/license-Apache_2.0-blue) · usually installed transitively · `import cendor.core`
+
+```python
+from cendor.core import tokens, prices, instrument, bus
+
+# Count tokens and price a call — fully offline, no API key, no network:
+n = tokens.count([{"role": "user", "content": "Summarize the attached report in 3 bullets."}],
+                 model="claude-opus-4-8")
+cost = prices.estimate("claude-opus-4-8", input_tokens=n, output_tokens=200)
+
+# Instrument any client once; tools subscribe to the normalized event stream:
+@bus.subscribe
+def on_call(call):                   # normalized LLMCall with usage + cost
+    print(call.provider, call.model, call.cost)
+
+client = instrument(openai_or_anthropic_client)   # idempotent, additive · sync · async · streaming
+```
+
+## Highlights
+
+- **`instrument()`** — wrap any client once: **OpenAI · Anthropic · AWS Bedrock · Google Gemini · Ollama**, detected by *shape*; sync, async, **and streaming**; idempotent + additive. `instrument_tool()` does the same for tools.
+- **Event bus** — `subscribe` / `emit`; **thread-safe within a process**; one failing subscriber never starves another.
+- **Interceptor seam** — `add_interceptor` + `Reroute` / `MISS` powers replay (cassette) and reroute / block (tokenguard) **without a second patch point**.
+- **Token counting, three tiers** — exact (`[tiktoken]`) / BPE-estimate (o200k for Claude/Gemini) / offline heuristic; `tokens.method(model)` reports which is active; `tokens.register()` plugs in a precise counter.
+- **Reasoning-token accounting** — `Usage.reasoning_tokens` breaks out a reasoning/thinking model's internal reasoning (OpenAI `reasoning_tokens`, Gemini `thoughts_token_count`), non-streaming and streaming. A subset of `output_tokens`, so cost is unchanged; Gemini's separately-reported thoughts are now folded into the output total (fixing an under-count).
+- **Offline-first, refreshable prices** — bundled dated snapshot; `estimate() -> Decimal Money` (never `float`); optional `refresh(source="litellm"|"openrouter"|"azure")` from live no-auth sources, with `age_days()`/`is_stale()` staleness signals. A gateway-reported cost (e.g. OpenRouter's `usage.cost`) is preferred over the estimate and labeled `cost_reported` vs `cost_estimated`.
+- **OpenTelemetry** — emit `gen_ai.*` spans, or `otel.ingest()` a managed runtime's spans onto the bus. Structural protocols (`Compressor` / `EvictionStrategy` / `Sink` / `Subscriber` / `Handle`) let the tools interlock without coupling.
+
+Install `cendor-core[tiktoken]` for **exact** OpenAI counts (heuristic fallback otherwise), or `[otel]` to emit spans. Provider SDKs are always optional extras.
+
+A rendered architecture diagram lives in [`docs/core.md`](https://github.com/PowerAI-Labs/Cendor/blob/main/docs/core.md) (GitHub renders Mermaid; PyPI shows code as text).
+
+See [`docs/core.md`](https://github.com/PowerAI-Labs/Cendor/blob/main/docs/core.md) · [CHANGELOG](https://github.com/PowerAI-Labs/Cendor/blob/main/packages/cendor-core/CHANGELOG.md). *Part of the Cendor stack — [github.com/PowerAI-Labs/Cendor](https://github.com/PowerAI-Labs/Cendor). Powered by PowerAI Labs. Apache-2.0; provided "as is", without warranty — use at your own risk (LICENSE §7–8).*

cendor_core-0.1.12/README.md

@@ -0,0 +1,41 @@
+# cendor-core
+
+The shared foundation for the Cendor stack: canonical types, provider-aware token counting,
+an offline price table, one `instrument()` interception point, an in-process event bus, and
+OpenTelemetry GenAI emitters. Tiny on purpose — it's the blast radius for every other tool.
+
+**One `instrument()` call, every sibling tool observes the stream — no per-call wiring, offline by default.**
+
+![PyPI](https://img.shields.io/pypi/v/cendor-core) ![license](https://img.shields.io/badge/license-Apache_2.0-blue) · usually installed transitively · `import cendor.core`
+
+```python
+from cendor.core import tokens, prices, instrument, bus
+
+# Count tokens and price a call — fully offline, no API key, no network:
+n = tokens.count([{"role": "user", "content": "Summarize the attached report in 3 bullets."}],
+                 model="claude-opus-4-8")
+cost = prices.estimate("claude-opus-4-8", input_tokens=n, output_tokens=200)
+
+# Instrument any client once; tools subscribe to the normalized event stream:
+@bus.subscribe
+def on_call(call):                   # normalized LLMCall with usage + cost
+    print(call.provider, call.model, call.cost)
+
+client = instrument(openai_or_anthropic_client)   # idempotent, additive · sync · async · streaming
+```
+
+## Highlights
+
+- **`instrument()`** — wrap any client once: **OpenAI · Anthropic · AWS Bedrock · Google Gemini · Ollama**, detected by *shape*; sync, async, **and streaming**; idempotent + additive. `instrument_tool()` does the same for tools.
+- **Event bus** — `subscribe` / `emit`; **thread-safe within a process**; one failing subscriber never starves another.
+- **Interceptor seam** — `add_interceptor` + `Reroute` / `MISS` powers replay (cassette) and reroute / block (tokenguard) **without a second patch point**.
+- **Token counting, three tiers** — exact (`[tiktoken]`) / BPE-estimate (o200k for Claude/Gemini) / offline heuristic; `tokens.method(model)` reports which is active; `tokens.register()` plugs in a precise counter.
+- **Reasoning-token accounting** — `Usage.reasoning_tokens` breaks out a reasoning/thinking model's internal reasoning (OpenAI `reasoning_tokens`, Gemini `thoughts_token_count`), non-streaming and streaming. A subset of `output_tokens`, so cost is unchanged; Gemini's separately-reported thoughts are now folded into the output total (fixing an under-count).
+- **Offline-first, refreshable prices** — bundled dated snapshot; `estimate() -> Decimal Money` (never `float`); optional `refresh(source="litellm"|"openrouter"|"azure")` from live no-auth sources, with `age_days()`/`is_stale()` staleness signals. A gateway-reported cost (e.g. OpenRouter's `usage.cost`) is preferred over the estimate and labeled `cost_reported` vs `cost_estimated`.
+- **OpenTelemetry** — emit `gen_ai.*` spans, or `otel.ingest()` a managed runtime's spans onto the bus. Structural protocols (`Compressor` / `EvictionStrategy` / `Sink` / `Subscriber` / `Handle`) let the tools interlock without coupling.
+
+Install `cendor-core[tiktoken]` for **exact** OpenAI counts (heuristic fallback otherwise), or `[otel]` to emit spans. Provider SDKs are always optional extras.
+
+A rendered architecture diagram lives in [`docs/core.md`](https://github.com/PowerAI-Labs/Cendor/blob/main/docs/core.md) (GitHub renders Mermaid; PyPI shows code as text).
+
+See [`docs/core.md`](https://github.com/PowerAI-Labs/Cendor/blob/main/docs/core.md) · [CHANGELOG](https://github.com/PowerAI-Labs/Cendor/blob/main/packages/cendor-core/CHANGELOG.md). *Part of the Cendor stack — [github.com/PowerAI-Labs/Cendor](https://github.com/PowerAI-Labs/Cendor). Powered by PowerAI Labs. Apache-2.0; provided "as is", without warranty — use at your own risk (LICENSE §7–8).*

cendor_core-0.1.12/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "cendor-core"
+version = "0.1.12"
+description = "Foundation for the PowerAI Labs stack: shared types, token counting, offline-first & refreshable prices, instrument(), event bus, OTel."
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Raghav Mishra" }]
+readme = "README.md"
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.30"]
+otel = ["opentelemetry-api>=1.25", "opentelemetry-sdk>=1.25"]
+tiktoken = ["tiktoken>=0.7"]   # optional: exact OpenAI token counts (heuristic fallback otherwise)
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cendor"]     # contributes cendor/core only — NEVER add src/cendor/__init__.py

cendor_core-0.1.12/src/cendor/core/__init__.py

@@ -0,0 +1,22 @@
+"""cendor.core — the shared foundation. Keep this public surface small and stable."""
+
+from __future__ import annotations
+
+from . import bus, otel, prices, protocols, tokens
+from .instrument import Reroute, instrument, instrument_tool
+from .types import LLMCall, Money, ToolCall, Usage
+
+__all__ = [
+    "LLMCall",
+    "ToolCall",
+    "Usage",
+    "Money",
+    "bus",
+    "tokens",
+    "prices",
+    "otel",
+    "protocols",
+    "instrument",
+    "instrument_tool",
+    "Reroute",
+]

cendor_core-0.1.12/src/cendor/core/bus.py

@@ -0,0 +1,66 @@
+"""In-process pub/sub event bus: one instrument() emits, many tools subscribe. docs/core.md §6.
+
+Thread-safe within a process: the subscriber list is guarded by a lock for registration changes,
+and :func:`emit` fans out over a snapshot taken under that lock — so subscribers may (un)subscribe
+from other threads (or from inside a callback) without corrupting the list or deadlocking.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any
+
+_subscribers: list[Callable[[Any], None]] = []
+_lock = threading.Lock()
+
+
+def subscribe(fn: Callable[[Any], None]) -> Callable[[Any], None]:
+    """Register a subscriber. Usable as a decorator. Idempotent: re-registering the
+    same callable is a no-op, so a sibling tool can safely ensure its subscription."""
+    with _lock:
+        if fn not in _subscribers:
+            _subscribers.append(fn)
+    return fn
+
+
+def unsubscribe(fn: Callable[[Any], None]) -> None:
+    """Remove a subscriber (no error if absent) — the inverse of :func:`subscribe`.
+
+    Lets a tool register a *temporary* subscriber (e.g. cassette's recorder) and tear it down
+    cleanly, without reaching into the internal subscriber list."""
+    with _lock:
+        if fn in _subscribers:
+            _subscribers.remove(fn)
+
+
+def emit(event: Any) -> None:
+    """Publish an event to every subscriber (synchronous).
+
+    Every subscriber runs even if an earlier one raises, so one tool's failure can't starve
+    another (a logging subscriber's bug must not skip ``tokenguard``'s enforcement, or vice versa).
+    The first ``Exception`` raised is re-raised after all subscribers have run, so intentional
+    control flow (e.g. ``tokenguard``'s post-flight ``BudgetExceeded``) still reaches the caller.
+    ``BaseException`` (``KeyboardInterrupt``/``SystemExit``) is not caught — it propagates at once.
+
+    The fan-out runs over a snapshot taken under the lock, then *releases* it before invoking any
+    subscriber — so a subscriber is free to (un)subscribe without deadlocking, and a slow one never
+    blocks registration on another thread.
+    """
+    with _lock:
+        subscribers = list(_subscribers)
+    first_exc: Exception | None = None
+    for fn in subscribers:
+        try:
+            fn(event)
+        except Exception as exc:  # noqa: BLE001 - isolate subscribers, re-raise first after all run
+            if first_exc is None:
+                first_exc = exc
+    if first_exc is not None:
+        raise first_exc
+
+
+def _reset() -> None:
+    """Test helper: clear all subscribers."""
+    with _lock:
+        _subscribers.clear()