contextos-auditor 0.1.0__tar.gz

contextos_auditor-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.venv/
+.venv-fw/
+traces/
+__pycache__/
+*.pyc
+.pytest_cache/
+out/
+fixtures/java/
+*.class
+scripts/natbatch.jobs
+dashboard/web/node_modules/
+node_modules/
+dashboard/web/dist/
+dashboard/web/*.tsbuildinfo
+.tokcache/
+packages/agentcost-kit-js/dist/
+packages/agentcost-kit-js/*.tsbuildinfo
+packages/agentcost-kit-py/*.egg-info/
+packages/agentcost-kit-py/build/
+packages/agentcost-kit-py/dist/
+
+# contextos-auditor local session captures (contain raw tool args/results)
+.contextos/

contextos_auditor-0.1.0/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to `contextos-auditor` are documented here.
+
+## [0.1.0] — unreleased (pre-PyPI)
+
+Initial public release candidate. Not yet published to PyPI — install from
+source in the meantime (see README Quickstart).
+
+### Added
+- **Nested turn → tool-call trace (AUD-013)**: `report`/`watch` (terminal
+  and HTML/live dashboard) now render a per-turn breakdown of which tools
+  were called and which write triggered waste detection, instead of only
+  bottom-line totals -- built from data `shadow_session()` already
+  computes, no new instrumentation. Live-verified via screenshot.
+- **`contextos-auditor history` command (AUD-014)**: lists every recorded
+  session under `--audit-root`, newest first, with framework/model/status/
+  turns/tokens/cost/save% columns, `--limit N` (default 20, `0` = no cap).
+  Reads only the session files each run already writes; no new database
+  or aggregation step.
+- **Optional secret-pattern redaction (AUD-016)**: `attach(...,
+  redact_secrets=True)` (or `CONTEXTOS_REDACT_SECRETS=1`) scrubs
+  recognizable secret-shaped substrings (AWS/OpenAI/GitHub/Slack-style
+  keys, JWTs, PEM private keys, generic `api_key=`/`password=`/`token=`
+  assignments) from recorded tool args/results with `[REDACTED]`,
+  replacing only the matched value -- not the whole tool call, so real
+  file content the write-waste detector needs stays intact. Off by
+  default; live-verified that waste detection keeps working correctly
+  with it turned on.
+- **Optional OTel export (AUD-012)**: `pip install contextos-auditor[otel]`
+  plus `attach(..., otel_endpoint="http://localhost:4318/v1/traces")` (or
+  the `CONTEXTOS_OTEL_ENDPOINT` env var, zero code changes) makes every
+  adapter additionally export each turn as a real OTel span following the
+  GenAI semantic conventions (`gen_ai.system`, `gen_ai.request.model`,
+  `gen_ai.usage.input_tokens/output_tokens`, `gen_ai.tool.name`, ...) --
+  verified against a real local OTLP/HTTP receiver. Strictly additive and
+  opt-in: the local JSONL trail is unaffected either way, and a missing
+  package or unreachable collector degrades to one `UserWarning`, never a
+  crash in the agent's real run.
+- **Real $ cost estimate (AUD-011)**: sessions for models in a small,
+  hand-curated, dated pricing snapshot (`_internal/pricing.py`, sourced
+  from litellm's publicly maintained pricing table) now show an
+  estimated `$` figure alongside token counts in `watch`/`watch --serve`/
+  `report`, clearly labeled "list price as of DATE, not your negotiated
+  rate". Unpriced models show "no dated pricing available" rather than a
+  guessed number — the Auditor's honesty-culture rule (never invent a
+  billing figure) still holds, this just widens what counts as "real".
+- Fixed **AUD-018**: the model name is now backfilled from the first real
+  LLM event a framework reports (e.g. CrewAI's
+  `LLMCallCompletedEvent.model`) instead of staying `unknown` for the
+  entire session when no `model_hint` was passed to `attach()`.
+- Fixed **AUD-017/AUD-019**: `watch`/`watch --serve` now poll and wait for
+  a session to appear instead of exiting immediately if the dashboard is
+  opened before the agent run starts (at least as natural an order as the
+  reverse). Plain `watch` also now detects a finished/errored session and
+  stops on its own instead of refreshing forever until Ctrl-C.
+- Free, local-only Agent Auditor (**free for any use, commercial included
+  — licensed under PolyForm Shield 1.0.0, noncompete only, see LICENSE**):
+  attach one line to an
+  existing CrewAI / LangGraph / AutoGen / OpenAI Agents SDK agent and
+  watch its real token cost live. No signup, no telemetry, no data leaves
+  the machine it runs on.
+- **Crash isolation (AUD-009)**: every adapter handler and
+  `FrameworkAuditSession` entry point is now `@guarded` — an internal
+  Auditor failure (malformed usage dict, SDK version drift, full disk)
+  can never propagate into the agent's real execution path. Fixed a
+  critical case in the AutoGen adapter where a recording failure could
+  previously discard an already-successful, already-billed LLM call
+  result.
+- Public adapters for all 4 frameworks (`contextos_auditor.crewai`,
+  `.langgraph`, `.openai_agents`, `.autogen`), each vendoring (not
+  importing) the corresponding internal `dashboard/adapters/*` logic so
+  the package has zero dependency on the toku monorepo at runtime.
+- `contextos-auditor` CLI: `watch` (terminal table, auto-refreshing HTML,
+  or `--serve` for a localhost-only live browser view over Server-Sent
+  Events), `report` (one-shot static summary), `doctor` (checks which
+  framework SDKs are importable and whether their installed version falls
+  inside this release's tested range).
+- Project-local `.contextos/audit/` output directory by default (no
+  assumption the caller lives inside any particular repo layout).
+- Per-framework `[crewai]`/`[langgraph]`/`[autogen]`/`[openai-agents]`/
+  `[all]` optional extras; zero required runtime dependencies.
+- Hard, CI-enforced network-isolation test suite
+  (`tests/test_no_network_calls.py`): the live `--serve` view is proven,
+  not just claimed, to make outbound connections only to loopback.
+- SDK version-drift detection (`_internal/compat.py`): a one-time
+  `UserWarning` (never a hard failure) when an installed framework SDK
+  version falls outside the range the vendored adapter was last verified
+  against, surfaced proactively in `contextos-auditor doctor`.
+- `scripts/build_binary.sh`: builds a standalone, single-file CLI binary
+  (PyInstaller, built from a clean venv with zero framework extras) for
+  teammates who want to `watch`/`report`/`doctor` a session without any
+  Python/pip on their machine at all. Verified to run correctly in a fully
+  empty environment (`env -i`, no PATH/PYTHONHOME).
+
+### Fixed
+- **P0**: `watch --serve`'s live dashboard corrupted itself into visible
+  raw `\n`/quote-mark text after the very first live update. The server
+  correctly JSON-encodes each SSE fragment (`json.dumps(fragment)`) but
+  the injected client-side JS assigned the raw, still-encoded string
+  straight into `document.body.innerHTML` instead of decoding it first.
+  Found via a real headless-Chrome screenshot of the running dashboard,
+  not code review. Fixed: client now does `JSON.parse(e.data)` before
+  use. Regression test: `tests/test_server_sse_parse.py`.
+- Restyled `watch`/`watch --serve`/`--html`'s dashboard to match the
+  marketing site's dark theme (same background/panel/accent colors,
+  mono-font numeric table, teal-for-positive/red-for-negative percent)
+  instead of the previous unstyled light-mode default — this is now the
+  one visual identity used everywhere the product shows a UI. Deliberately
+  does not load the marketing site's Google Fonts (system-font fallback
+  only), keeping the dashboard's own zero-external-network guarantee
+  (AUD-005) intact for the actual tool, not just the marketing page.
+
+### Known limitations
+- The `_internal/*.py` vendor copies are manually synced against the
+  monorepo's `dashboard/`/`kit/`/`spike/` originals — not automatic. See
+  README.
+- No hosted/team dashboard in this package by design; that's a paid-tier
+  feature. This package is local-only, always.

contextos_auditor-0.1.0/LICENSE

@@ -0,0 +1,155 @@
+PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright Suraj Jha (https://github.com/surajJha)
+
+Licensor Line of Business: ContextOS agent token/cost auditing and
+optimisation tooling (contextos-auditor, contextos-optimiser)
+
+Plain-English summary (not a substitute for the terms below): you may use
+this software for **any** purpose, including inside a commercial company
+and on commercial products, free of charge. You may modify it and
+redistribute it. The one thing you may not do is use it to provide a
+product that competes with ContextOS.
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as
+both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do
+everything you might do with the software that would otherwise infringe
+the licensor's copyright in it for any permitted purpose. However, you may
+only distribute the software according to Distribution License and make
+changes or new works based on the software according to Changes and New
+Works License.
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute
+copies of the software. Your license to distribute covers distributing the
+software with changes and new works permitted by Changes and New Works
+License.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software
+from you also gets a copy of these terms or the URL for them above, as
+well as copies of any plain-text lines beginning with `Required Notice:`
+that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Suraj Jha (https://github.com/surajJha)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes
+and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers
+patent claims the licensor can license, or becomes able to license, that
+you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that
+competes with the software or any product the licensor or any of its
+affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through
+different kinds of interfaces or for different technical platforms.
+Applications can compete with services, libraries with plugins, frameworks
+with development tools, and so on, even if they're written in different
+programming languages or for different computer architectures. Goods and
+services compete even when provided free of charge. If you market a
+product as a practical substitute for the software or another product, it
+definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete,
+but the licensor or any of its affiliates brings your product into
+competition by providing a new version of the software or another product
+using the software, you may continue using versions of the software
+available under these terms beforehand to provide your competing product,
+but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that
+the licensor or any of its affiliates has stopped providing, unless the
+licensor includes a plain-text line beginning with `Licensor Line of
+Business:` with the software that mentions that line of business.
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business
+developing the software or using the software to provide a product, the
+buyer can also enforce Noncompete for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms
+do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your
+licenses to anyone else, or prevent the licensor from granting licenses to
+anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes
+to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a
+claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of
+these terms, or done anything with the software not covered by your
+licenses, your licenses can nonetheless continue if you come into full
+compliance with these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice. Otherwise, all your
+licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any
+warranty or condition, and the licensor will not be liable to you for any
+damages arising out of these terms or the use or nature of the software,
+under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the
+**software** is the software the licensor makes available under these
+terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations that an organization has
+control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software
+under these terms.
+
+**Use** means anything you do with the software requiring one of your
+licenses.