consequa-x 2.0.0__tar.gz → 2.1.1__tar.gz

{consequa_x-2.0.0 → consequa_x-2.1.1}/CHANGELOG.md

@@ -1,10 +1,85 @@
 # Changes
 
+## 2.1.1 - 19 October 2026
+
+A maintenance release; the API and trace schema are unchanged.
+
+- The project's name is written ConseqaX: README, documentation, report title
+  and footer, the trace schema's title and command-line text. The package,
+  command and import names stay `consequa-x` and `consequa_x`.
+- Python 3.13, 3.14 and 3.15 are tested and declared (PyPI classifiers and
+  documentation), alongside 3.11 and 3.12.
+- Each framework integration was also run with a real model in a real agent
+  loop (`scripts/check_live_integrations.py`); the recorded attempts matched
+  the tool calls that ran.
+- New example `examples/two_part_outcome.py`: an `all_of` contract over a refund
+  and a ticket closure, read back from two SQLite files.
+
+## 2.1.0 - 19 October 2026
+
+Additive: the roadmap features left out of 2.0.0 (verifier composition,
+framework integrations and OpenTelemetry). Schema `1.0` and the 2.0 API are
+unchanged, and the core still has no required runtime dependency. Published
+to PyPI with registry hashes verified; see the
+[release record](output/release-2.1.0-2026-10-19/README.md). Installed checks
+passed on Windows Python 3.11.9 and 3.12.10, on one Alpine Linux 3.24.2 QEMU
+guest with Python 3.14.8 and from a fresh PyPI install; the integrations passed against the installed wheel
+with each SDK present. macOS has never been tested.
+
+- Verifier composition. `all_of(contract_id, *parts)` and `any_of(...)` build
+  one outcome contract from part contracts, each with its own predicate,
+  expected values and timing; `contract_parts` decodes and checks them.
+  `CompositeVerifier({part_id: verifier}, sources={part_id: source})` checks
+  each part against the readback from its source and combines the receipts
+  with three-valued logic: `all_of` is violated when any part is violated and
+  satisfied when all are; `any_of` is satisfied when any part is and violated
+  when all are; otherwise the outcome stays `unknown`. A part without readback
+  is `unknown`. The receipt keeps each part's evidence (tagged with its part
+  ID, status, origin and reason), the union of the parts' effects and
+  findings, and adds `PART_VIOLATED`, `PART_UNKNOWN` and `PART_OTHER_ACTOR`.
+  Target matching is conservative, so an agent's report is judged only when
+  the deciding parts did target matching. Parts can nest.
+- Several readbacks per verification: `verify`, `averify`,
+  `ActionCapture.verify`/`averify` and `poll_readback` (whose `read` may return
+  one observation per source) accept a sequence of observations for a verifier
+  that provides `verify_readbacks`. Receipts are still checked against every
+  supplied observation.
+- Reports describe an `all_of`/`any_of` contract's structure (part count,
+  each part's deadline and horizon) and list each recorded part result, without
+  showing part payloads.
+- `consequa-x verify` takes `--readback` once per source, plus
+  `--part-source PART=SOURCE` and `--scope-field PART=FIELD` for composite
+  contracts.
+- OpenTelemetry (`consequa_x.otel`): `to_otlp` writes an OTLP/JSON document
+  with a span per action, an `execute_tool` span per attempt named as the GenAI
+  semantic conventions describe, and a span per verification, with
+  `consequa_x.*` attributes for state, origin, alignment and diagnosis codes.
+  Payloads are opt-in (`include_payloads=True`, which also embeds the complete
+  trace for `from_otlp`). `emit` creates the spans through `opentelemetry-api`
+  (extra `otel`). `record_tool_spans` turns `execute_tool` spans from any
+  GenAI instrumentation into recorded actions for the contracts the
+  application supplies. New commands: `otel-export` and `otel-import`.
+- Framework integrations (`consequa_x.integrations`): `ToolCallCapture` and
+  `ToolCall` record framework tool calls for the calls `contract_for` makes
+  consequential, grouping retries through `action_id_for`. Optional extras:
+  `openai-agents` (`consequential_tool`, in place of `function_tool`),
+  `langchain` (`ConsequaCallbackHandler`) and `claude-agent-sdk`
+  (`consequa_hooks` for `PreToolUse`, `PostToolUse` and
+  `PostToolUseFailure`). Tested offline with openai-agents 0.24.0,
+  langchain-core 1.6.12, claude-agent-sdk 0.2.168 and opentelemetry 1.45.1; no
+  live model was called.
+- Report tables scroll inside their frame on narrow screens; their cells no
+  longer collapse to one character per line (present since 2.0).
+
 ## 2.0.0 - 19 October 2026 (breaking)
 
 See [the 2.0 design](docs/design-2.0.md) and the
 [migration guide](docs/migrating-to-2.0.md). Deferred to 2.1: verifier
 composition, optional framework integrations and OpenTelemetry export.
+Published to PyPI with registry hashes verified; see the
+[release record](output/release-2.0.0-2026-10-19/README.md). Installed checks
+passed on Windows Python 3.11.9 and 3.12.10, on one Alpine Linux 3.24.2 QEMU guest
+with Python 3.14.8 and from a fresh PyPI install. macOS has never been tested.
 
 - Typed exceptions: every intentional error derives from `ConsequaError` and
   still from `ValueError` or `TypeError`. `ValidationError` (invalid records,
@@ -209,7 +284,7 @@ preselected complete traces. The
 [derived findings](output/interaction-sampling-findings-2026-10-15/FINDINGS.md)
 retain coverage, width, detection and refusal denominators. The defined
 framework and protocol/software paper scope is complete on 16 October 2026:
-the [illustrated eight-page IEEE PDF](output/pdf/Consequa-X_IEEE_Paper.pdf) compiled and all
+the [illustrated eight-page IEEE PDF](output/pdf/ConseqaX_IEEE_Paper.pdf) compiled and all
 rendered pages passed visual review. The [QA receipt](output/pdf/qa.json) binds
 it to the frozen [editable source](paper/consequa-x-ieee.tex) and four vector
 figures. Actual venue selection, final human

{consequa_x-2.0.0 → consequa_x-2.1.1}/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to Consequa-X
+# Contributing to ConseqaX
 
 Thanks for helping. This public repository holds the Python package, its tests
 and documentation, the website, and the research records behind the paper. The
@@ -23,7 +23,7 @@ to a pull request. Report vulnerabilities privately as described in
 
 ## Set up a development environment
 
-Fork and clone the repository, then create a branch for your change. Use Python 3.11 or 3.12:
+Fork and clone the repository, then create a branch for your change. Use Python 3.11 or newer:
 
 ```sh
 python -m venv .venv

{consequa_x-2.0.0 → consequa_x-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: consequa-x
-Version: 2.0.0
+Version: 2.1.1
 Summary: Evidence-aware explanation of consequential agent actions
 Author: Devrajsinh Jhala
 License-Expression: MIT
@@ -14,18 +14,29 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.2.168; extra == "claude-agent-sdk"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: jsonschema>=4.23; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.6; extra == "langchain"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.24; extra == "openai-agents"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.45; extra == "otel"
 Dynamic: license-file
 
-# Consequa-X
+# ConseqaX
 
 **Evidence-aware explanation of consequential agent actions.**
 
@@ -34,7 +45,7 @@ database write), the tool's response is only part of the story. A timeout can
 hide a refund that went through. A "success" can hide one that never landed.
 Another actor can produce the very outcome the agent was asked for.
 
-Consequa-X keeps four things apart: the **tool response**, what the **agent
+ConseqaX keeps four things apart: the **tool response**, what the **agent
 reported**, the outcome established by an **independent read-only readback**, and
 **who produced the effect**. Missing, stale or incomplete evidence stays
 `unknown` instead of being guessed.
@@ -53,7 +64,9 @@ python -m pip install consequa-x
 consequa-x --version
 ```
 
-Use `python -m consequa_x` wherever a command below uses `consequa-x`.
+Use `python -m consequa_x` wherever a command below uses `consequa-x`. Optional
+extras add framework integrations and OpenTelemetry: `consequa-x[openai-agents]`,
+`consequa-x[langchain]`, `consequa-x[claude-agent-sdk]` and `consequa-x[otel]`.
 
 ## See it in a minute
 
@@ -156,7 +169,7 @@ receipt = verify(action, observation, verifier=MyVerifier())
 ```
 
 Your application owns source trust, scope, completeness, timing and provenance;
-Consequa-X checks that receipts bind to the supplied action, contract and
+ConseqaX checks that receipts bind to the supplied action, contract and
 observation, and keeps the evidence structured. The
 [artifact-delivery example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/artifact_delivery.py)
 implements a verifier with public APIs only, and the
@@ -165,6 +178,37 @@ describes the boundary in detail. The
 [stable API](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/stable-api.md)
 page lists what version 2 guarantees.
 
+An outcome with several required effects (a refund *and* a closed ticket, or a
+refund *or* store credit) is one contract: `all_of(...)` or `any_of(...)` over
+part contracts, checked by `CompositeVerifier` with one readback per source.
+Unknown parts keep the whole outcome unknown unless another part already
+settles it.
+
+## Agent frameworks and OpenTelemetry
+
+Optional integrations record an agent framework's tool calls through the same
+recorder. Your `contract_for(call)` decides which calls are consequential:
+
+```python
+from consequa_x.integrations import ToolCallCapture
+calls = ToolCallCapture(rec, contract_for=contract_for)
+
+# OpenAI Agents SDK: use in place of @function_tool
+from consequa_x.integrations.openai_agents import consequential_tool
+# LangChain: config={"callbacks": [ConsequaCallbackHandler(calls)]}
+from consequa_x.integrations.langchain import ConsequaCallbackHandler
+# Claude Agent SDK: ClaudeAgentOptions(hooks=consequa_hooks(calls))
+from consequa_x.integrations.claude_agent_sdk import consequa_hooks
+```
+
+`consequa_x.otel` writes traces as OTLP/JSON with `execute_tool` spans named as
+the OpenTelemetry GenAI conventions describe, emits them through
+`opentelemetry-api`, and turns tool spans from other instrumentation into
+recorded actions. See the
+[framework guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/framework-integration.md)
+and the
+[OpenTelemetry guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/opentelemetry.md).
+
 ## Upgrading from 1.x
 
 Version 2.0 changes the trace schema to `1.0` (several actions per trace, a
@@ -183,7 +227,8 @@ lists every change and its replacement.
 | `consequa-x report TRACE --output FILE` | Render a self-contained HTML report; `--include-details` embeds the full capture, `--redact KEY` blanks named keys in it |
 | `consequa-x summarize PATH... [--format markdown]` | Count outcomes, alignment and divergences across trace files, folders and `.jsonl` stores |
 | `consequa-x compare A B` | Compare two traces action by action |
-| `consequa-x verify TRACE --readback OBS --output NEW` | Verify a captured readback file with a built-in verifier |
+| `consequa-x verify TRACE --readback OBS --output NEW` | Verify captured readback with built-in verifiers; repeat `--readback` for an `all_of`/`any_of` contract |
+| `consequa-x otel-export TRACE --output FILE` / `consequa-x otel-import FILE --output-dir DIR` | Write a trace as OpenTelemetry OTLP/JSON spans; restore traces exported with `--include-payloads` |
 | `consequa-x validate TRACE...` / `consequa-x migrate OLD --output NEW` | Check traces; convert schema `0.1` traces |
 | `consequa-x experiment …` and research commands | Paired replay, decision attribution and calibration studies (see Research) |
 
@@ -210,8 +255,8 @@ and the [paper notes](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/p
 ## Platforms
 
 The package is pure Python. Released wheels have been install-tested on Windows
-with Python 3.11 and 3.12 and on one Alpine Linux virtual machine with Python
-3.14. macOS has not been tested yet. See the
+with Python 3.11, 3.12, 3.13, 3.14 and 3.15, and on one Alpine Linux virtual
+machine with Python 3.14. macOS has not been tested yet. See the
 [release notes](https://consequa-x.onrender.com/changelog.html) for exact
 environments.