Release execlave-sdk v1.4.0

Squashed export from the Execlave monorepo — see CHANGELOG.md for details.

Author: Execlave Release Bot

.env.example

@@ -0,0 +1,11 @@
+# Execlave Python SDK — environment variables
+#
+# Read by execlave-sdk client when arguments are not passed explicitly.
+
+# Your Execlave API key. Live keys are prefixed `exe_dev_`, `exe_stg_`, or `exe_prod_`.
+# Generate one in the dashboard: https://www.execlave.com/dashboard/api-keys
+EXECLAVE_API_KEY=
+
+# Optional. Override the API base URL (defaults to https://api.execlave.com).
+# Set to http://localhost:4000 for local development against the dev backend.
+EXECLAVE_BASE_URL=

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,62 @@
+name: "Bug report"
+description: "Report a reproducible defect in execlave-sdk"
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. Security issues: please email security@execlave.com instead.
+  - type: input
+    id: sdk-version
+    attributes:
+      label: "execlave-sdk version"
+      description: "Output of `pip show execlave-sdk | grep Version`"
+      placeholder: "1.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: "Python version"
+      placeholder: "3.12.2"
+    validations:
+      required: true
+  - type: dropdown
+    id: integration
+    attributes:
+      label: "Integration in use (if any)"
+      options:
+        - "None (core SDK only)"
+        - "LangChain (ExeclaveCallbackHandler)"
+        - "OpenAI Agents SDK (ExeclaveTracingProcessor)"
+        - "CrewAI (instrument_crew)"
+        - "OpenTelemetry"
+        - "Other"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: "Minimal reproduction"
+      description: "The smallest code sample that reproduces the issue. Redact API keys."
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected behaviour"
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: "Actual behaviour"
+      description: "Include full traceback if any."
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: "Additional context"
+      description: "OS, LLM provider, network constraints, etc."

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "Security vulnerability"
+    url: https://github.com/execlave-ai/execlave-python-sdk/security/advisories/new
+    about: "Report a security issue privately. Do not open a public issue."
+  - name: "Question / usage help"
+    url: https://github.com/execlave-ai/execlave-python-sdk/discussions
+    about: "Ask a question in GitHub Discussions."
+  - name: "Dashboard / API / billing"
+    url: https://www.execlave.com/support
+    about: "For the hosted service (api.execlave.com, the dashboard, or billing)."

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: "Feature request"
+description: "Suggest a capability for execlave-sdk"
+labels: ["enhancement", "triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: "What problem are you trying to solve?"
+      description: "Describe the use case. Avoid prescribing a specific solution here."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: "Proposed API or behaviour"
+      description: "Code snippets welcome. Be explicit about compatibility."
+      render: python
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternatives considered"
+  - type: checkboxes
+    id: willing-to-pr
+    attributes:
+      label: "Are you willing to open a PR?"
+      options:
+        - label: "Yes, I can implement this"
+        - label: "Yes, with guidance from a maintainer"

CHANGELOG.md

@@ -0,0 +1,134 @@
+# Changelog
+
+All notable changes to `execlave-sdk` (Python) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.4.0] - 2026-06-08
+
+### Added
+
+- **Optional HMAC request signing.** New `sign_requests` client argument (default
+  `False`). When enabled, every request body is signed with HMAC-SHA256 keyed by
+  the API key and sent with `X-Execlave-Timestamp` and `X-Execlave-Signature`
+  (`sha256=<hex>`) headers. Implemented as a `requests` session auth callable, so
+  it covers every call from a single point and signs the exact serialized body
+  bytes (`${timestamp}.${body}`) the server verifies. Defense-in-depth on top of
+  TLS + API-key auth; opt-in and fully backward-compatible (unsigned requests are
+  unaffected when the server has not made signing mandatory).
+
+## [1.3.0] - 2026-06-03
+
+### Added
+
+- **Agent identity stamping.** New `stamp_identity` client argument (default
+  `False`). When enabled, the client issues and caches a short-lived RS256
+  `exe_agt_` credential per agent and attaches it to each trace on ingest
+  (`agentCredential` field), so the platform can cryptographically stamp who
+  produced the trace. Best-effort and non-breaking: if a credential cannot be
+  issued, traces are still sent unstamped — stamping never blocks or drops ingest.
+- **MCP tool-integrity surfaces.** Optional, backwards-compatible additions for
+  MCP tool-supply-chain governance:
+  - `tool_descriptor(server, tool, descriptor, description=None)` — computes the
+    stable SHA-256 descriptor hash (canonical, key-order independent) used to pin
+    and diff a tool.
+  - `report_tool_baseline(agent_id, descriptors, reason="manual")` — pins the
+    approved set of `(server, tool, descriptorHash)` tuples for an agent; re-pin
+    with `reason="baseline_update"` after a reviewed tool update.
+  - `enforce_policy()` accepts an optional `tool_descriptors` argument that is
+    diffed against the agent's pinned baseline at runtime.
+  - New `ToolIntegrityError` (subclass of `PolicyBlockedError`) is raised when an
+    enforcement is denied by a `tool_integrity` policy. Callers that do not use
+    these fields are unaffected.
+
+### Changed
+
+- No telemetry. The SDK does not phone home, emit anonymous usage events, or
+  fetch remote configuration. Every network call goes to the Execlave backend
+  URL configured by the caller.
+
+## [1.2.1] - 2026-05-29
+
+### Added
+
+- **AI Agent Management Platform (AMP) surfaces.** Optional, backwards-compatible
+  additions for the governance features:
+  - `register_agent()` accepts an optional `autonomy_level`
+    (`observe` | `advise` | `act_with_approval` | `autonomous`) that maps the
+    agent onto a tiered-governance template.
+  - New `report_agent_metadata()` method that records a version snapshot in the
+    agent registry (`version_label` / `git_commit` / `deployed_at` / `notes` /
+    `activate`) — call it from a deploy pipeline to build version history for
+    diff/rollback.
+  - Available on both `ExeclaveClient` and `AsyncExeclaveClient`. Callers that do
+    not set these fields are unaffected.
+
+## [1.2.0] - 2026-05-28
+
+### Added
+
+- **Framework auto-instrumentation modules** (opt-in via `execlave.integrations`,
+  each with its own install extra): LangChain (`[langchain]`), OpenAI Agents SDK
+  (`[openai-agents]`), CrewAI (`[crewai]`), LlamaIndex (`[llamaindex]`), Model
+  Context Protocol (`[mcp]`), OpenAI Chat Completions (`[openai]`), and AutoGen
+  (`[autogen]`). Each routes the framework's tool calls / completions through
+  policy enforcement and trace ingestion without changing the host app's call
+  sites.
+
+## [1.1.5] - 2026-05-05
+
+### Added
+
+- `ValidatorDeniedError` (extends `PolicyBlockedError`) for programmatic handling
+  of denials originating from a Custom Validator (BYOV). The `from_violations()`
+  factory returns a `ValidatorDeniedError` when any violation is validator-sourced
+  and a plain `PolicyBlockedError` otherwise, so existing `except` sites keep working.
+
+### Fixed
+
+- `http://api.execlave.com` is normalized to `https://api.execlave.com` so
+  POST-based calls are not downgraded to GET by an HTTP-to-HTTPS redirect.
+- `enforce_policy()` now sends the client environment by default, matching
+  `register_agent()` and avoiding accidental production-policy enforcement from
+  development SDK clients.
+
+## [1.1.4] - 2026-05-05
+
+### Fixed
+
+- `register_agent()` now handles agent responses wrapped as `{ "data": [...] }`
+  by selecting the matching `agentId` instead of passing the list into `Agent`.
+  Malformed list responses now raise `ExeclaveError` with a clear response-shape
+  message instead of surfacing `AttributeError: 'list' object has no attribute 'get'`.
+
+## [1.0.0] — 2026-04
+
+### Added
+
+- Initial public release of `execlave-sdk` on PyPI.
+- `ExeclaveClient` class with `enforce()`, `ingest_trace()`, and
+  `register_agent()` methods.
+- Async variants via `AsyncExeclaveClient` (httpx-based).
+- Type hints throughout the public API, verified with `mypy --strict`.
+- PEP 621 `pyproject.toml` with a hatchling build backend.
+- Python 3.10+ supported; tested against 3.10, 3.11, and 3.12.
+- Support for API keys via the `exe_` / `exe_test_` prefix.
+
+### Security
+
+- TLS certificate verification is always enabled. Callers who need to
+  target a self-signed local environment must set `verify=False` on the
+  client explicitly and are warned on construction.
+- The SDK refuses to accept API keys that do not match the `exe_*` prefix,
+  preventing accidental use of unrelated credentials.
+
+[Unreleased]: https://github.com/rishitmavani/agentguard/compare/sdk-python-v1.3.0...HEAD
+[1.3.0]: https://github.com/rishitmavani/agentguard/compare/sdk-python-v1.2.1...sdk-python-v1.3.0
+[1.2.1]: https://github.com/rishitmavani/agentguard/compare/sdk-python-v1.2.0...sdk-python-v1.2.1
+[1.2.0]: https://github.com/rishitmavani/agentguard/compare/sdk-python-v1.1.5...sdk-python-v1.2.0
+[1.1.5]: https://github.com/rishitmavani/agentguard/compare/sdk-python-v1.1.4...sdk-python-v1.1.5
+[1.1.4]: https://github.com/rishitmavani/agentguard/compare/sdk-python-v1.1.3...sdk-python-v1.1.4
+[1.0.0]: https://github.com/rishitmavani/agentguard/releases/tag/sdk-python-v1.0.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Code of Conduct
+
+## Our Pledge
+
+We, as members, contributors, and maintainers of the `execlave-sdk` project, pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologising to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behaviour:
+
+- The use of sexualised language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behaviour and will take appropriate and fair corrective action in response to any behaviour that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the project team at **conduct@execlave.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to `execlave-sdk`
+
+Thanks for wanting to contribute! This project is the official Python SDK for the Execlave AI Governance Platform.
+
+## Ground rules
+
+1. **By contributing, you agree your work will be released under the MIT licence** (see `LICENSE`).
+2. **Be kind.** See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+3. **Security issues go to `security@execlave.com`**, never to a public issue. See [SECURITY.md](SECURITY.md).
+
+## Development setup
+
+```bash
+# Fork, then clone
+git clone https://github.com/<you>/execlave-python-sdk
+cd execlave-python-sdk
+
+# Editable install with dev + test extras
+python -m venv .venv
+source .venv/bin/activate   # or .venv\Scripts\activate on Windows
+pip install -e ".[test]"
+
+# Run the full test suite
+pytest
+
+# Run a single file
+pytest tests/test_client.py -v
+```
+
+Python 3.11+ is required. The project uses `flit` for packaging and `pytest` for testing.
+
+## Project layout
+
+```
+execlave/
+├── client.py              # Main Execlave client + enforce_policy
+├── trace.py               # Trace class (chainable API)
+├── instrumentation/       # Span + event helpers (shared across integrations)
+├── integrations/
+│   ├── langchain.py       # LangChain callback handler
+│   ├── openai_agents.py   # OpenAI Agents SDK tracing processor
+│   └── crewai.py          # CrewAI instrument_crew helper
+├── otel.py                # OpenTelemetry bridge
+└── connectors.py          # (Deprecated) run_langchain
+tests/                     # pytest suite
+```
+
+## Pull request checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Type hints added on any new public function signatures
+- [ ] Docstrings added or updated
+- [ ] `CHANGELOG.md` updated under *Unreleased* if the change is user-visible
+- [ ] No unrelated reformatting (keep diffs small)
+- [ ] For new integrations: pin the target framework's version range in `pyproject.toml` optional-deps
+
+## Adding a new framework integration
+
+1. Add a new module under `execlave/integrations/`.
+2. Import the framework at runtime only (inside `__init__` or a helper). The top-level `execlave` import must never require the framework.
+3. Use `execlave.instrumentation` helpers (`record_llm_call`, `record_tool_call`, `record_agent_action`) rather than driving `Trace` directly. This keeps span semantics consistent.
+4. Call `Execlave.enforce_policy(...)` on every external action (tool call, outbound HTTP, database write).
+5. Add an optional-dependency group in `pyproject.toml` with a pinned range.
+6. Add unit tests that mock the framework — CI does not install the real framework.
+7. Add a docs page at `frontend/app/docs/integrations/<name>/page.tsx` in the monorepo PR.
+
+## Style
+
+- `black` formatting, `ruff` linting (configured in `pyproject.toml`).
+- Prefer composition over inheritance.
+- No `print()` in library code; use `logging`.
+- Never swallow exceptions without logging — fail-open is acceptable for telemetry paths only, and must be logged at `warning`.
+
+## Release process
+
+Releases are driven from the monorepo. Tag `sdk-python/vX.Y.Z` publishes to PyPI via the `sdk-publish.yml` workflow. Versioning follows SemVer.
+
+## Questions?
+
+Open a discussion at <https://github.com/execlave-ai/execlave-python-sdk/discussions> or email `support@execlave.com`.

LICENSE

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