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

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

@@ -1,10 +1,65 @@
 # Changes
 
+## 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. Checked
+before publication; see the
+[release record](output/release-2.1.0-2026-10-19/README.md).
+
+- 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.
+
 ## 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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: consequa-x
-Version: 2.0.0
+Version: 2.1.0
 Summary: Evidence-aware explanation of consequential agent actions
 Author: Devrajsinh Jhala
 License-Expression: MIT
@@ -18,11 +18,19 @@ 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
@@ -53,7 +61,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
 
@@ -165,6 +175,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 +224,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) |