Metadata-Version: 2.4
Name: cxp
Version: 4.0.0
Summary: Capability Exchange Protocol
Author: Vicente Ruiz
License-Expression: MIT
Project-URL: Homepage, https://github.com/menudoproblema/cxp
Project-URL: Repository, https://github.com/menudoproblema/cxp
Project-URL: Issues, https://github.com/menudoproblema/cxp/issues
Keywords: capabilities,catalogs,interoperability,protocol,telemetry
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: msgspec<1,>=0.20.0
Provides-Extra: exchange
Requires-Dist: jsonschema<5,>=4.23; extra == "exchange"
Requires-Dist: referencing<1,>=0.35; extra == "exchange"
Requires-Dist: rfc8785<1,>=0.1.4; extra == "exchange"
Provides-Extra: dev
Requires-Dist: cxp[exchange]; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: types-jsonschema; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: jsonschema-rs<1,>=0.46; extra == "dev"
Dynamic: license-file

# CXP: Capability Exchange Protocol

![Version](https://img.shields.io/badge/version-4.0.0-blue)
![Python](https://img.shields.io/badge/python-3.12+-green)
[![CI](https://github.com/menudoproblema/cxp/actions/workflows/ci.yml/badge.svg)](https://github.com/menudoproblema/cxp/actions/workflows/ci.yml)

**CXP** is a semantic interoperability protocol for software components. It allows libraries, runtimes, and services to publish their capabilities and telemetry through a small shared contract.

## Why CXP?
Modern components are often black boxes. CXP gives them two explicit surfaces:

- **Capabilities**: So an orchestrator can understand what a component *can* do.
- **Telemetry**: So an orchestrator can observe what is happening at *runtime*.

CXP acts as a semantic bridge, allowing tools like AI agents, test runners, or orchestrators to operate against a shared contract instead of provider-specific assumptions.

## Design Goals
- **Small Core**: Keep the protocol surface narrow and stable.
- **High Fidelity**: Support expressive catalogs with metadata schemas, shared DTOs, and structured telemetry vocabularies.
- **Data-Oriented**: Exchange typed data using `msgspec` for high performance.
- **Omnichannel**: From cloud runtimes (ASGI/SQL) to industrial hardware (Zebra/Konica).

## Installation
```bash
pip install cxp
```

The base package only requires msgspec. Document exchange is optional:

```bash
pip install 'cxp[exchange]'
```

To pin this release, use `pip install 'cxp[exchange]==4.0.0'`.

## Catalog Layers
CXP includes a growing suite of first-party catalogs organized in six logical layers:

Each layer exposes a family catalog (the abstract contract) plus one or more concrete catalogs that satisfy it.

1. **Computing**: `execution/plan-run`, `runtime/environment` (secrets/resources), and the `application/http` family with concrete `application/asgi`, `application/wsgi`, and `application/http-framework` catalogs.
2. **Persistence**: `database/sql`, `database/mongodb` (both satisfying `database/common`), `storage/blob`, `cache/key-value`.
3. **Communications**: `transport/http` (with the `transport/http-family` umbrella and `transport/websocket` sibling), `messaging/event-bus` (concrete: `messaging/nats`), and `notification/common` (concrete: `notification/web-push`, `notification/mobile-push`).
4. **Queueing**: `queue/task-engine` for background processing.
5. **Experience & Media**: `browser/automation` (concrete: `browser/playwright`), `media/video-streaming` (HLS/DASH).
6. **Industrial**: `printing/manager` (concrete: `printing/label` for Zebra/ZPL, `printing/production` for Konica Minolta).

For the full list of registered interfaces and operations, see [docs/catalogs/index.md](docs/catalogs/index.md).

## Quick Start
```python
from cxp import (
    Capability,
    CapabilityMatrix,
    ComponentIdentity,
    HandshakeRequest,
    get_catalog,
    negotiate_with_provider_catalog,
)

# Resolve the standard catalog for the interface
catalog = get_catalog("database/sql")
assert catalog is not None

# Build the orchestrator request
request = HandshakeRequest(
    client_identity=ComponentIdentity(
        interface="database/sql",
        provider="my-orchestrator",
        version="1.0.0",
    ),
    required_capabilities=("transactions",),
)

# Negotiate with a provider
# response = negotiate_with_provider_catalog(request, my_sql_provider, catalog)
```

## Key Features
### Versioned document exchange (4.0)

`cxp.exchange` adds strict, portable documents and deterministic three-valued
requirements evaluation alongside the preserved legacy API. It includes exact
quantities, immutable snapshots, content-bound catalogs and opt-in protocol v2
format negotiation. Document specification version 1 is independent of both.

Run the packaged, hardware-free examples with:

```bash
python -m cxp.exchange.examples
```

See the [exchange specification](docs/protocol/exchange-v1.md),
[integration guide](docs/protocol/exchange-integration.md) and
[4.0 migration guide](docs/migration-4.0.md). Consumers should review their
dependency constraints and integration tests before adopting this major release.

### 1. Structured Error Reporting (`CxpError`)
Shared machine-readable error envelopes for catalogs that opt into the semantic layer.
```python
# retryable describes the error, not permission to repeat side effects.
# Reconcile an uncertain outcome first. Only the caller can authorize a retry
# under a reviewed idempotency guarantee and its key/scope/time conditions.
```

### 2. High-Fidelity Results
Many first-party operations return structured data defined in `results.py` (for example `HttpResponse`, `DbCursor`, `AsyncWorkReport`).

### 3. Bidirectional Validation
Catalogs can define `input_schema` and `result_schema` for operations when the domain benefits from explicit request/response contracts.

## Documentation
See [docs/index.md](docs/index.md) for the full documentation set:
- [Protocol Overview](docs/protocol/descriptors.md)
- [Structured Errors](docs/protocol/errors.md)
- [Interface Catalogs](docs/catalogs/index.md)

## License
MIT

## Contributing

CXP is standalone. See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks,
artifact verification and the separate publication gate. No sibling repositories
or internal infrastructure are required.
