Metadata-Version: 2.4
Name: ioc-cfn-mas-client-lib
Version: 0.3.1
Summary: Python SDK client library for IoC Cognition Fabric Node
Author-email: Outshift Open <oss@cisco.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/outshift-open/ioc-cfn-mas-client-lib
Project-URL: Documentation, https://github.com/outshift-open/ioc-cfn-mas-client-lib/blob/main/README.md
Project-URL: Repository, https://github.com/outshift-open/ioc-cfn-mas-client-lib
Project-URL: Issues, https://github.com/outshift-open/ioc-cfn-mas-client-lib/issues
Project-URL: Changelog, https://github.com/outshift-open/ioc-cfn-mas-client-lib/blob/main/CHANGELOG.md
Keywords: ioc,cognition-fabric,mas,multi-agent-system,sdk,cfn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pydantic>=2.5
Requires-Dist: urllib3>=1.26
Requires-Dist: python-dateutil>=2.8
Requires-Dist: typing-extensions>=4.7
Requires-Dist: uvicorn>=0.44.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: grpcio>=1.60
Requires-Dist: grpcio-tools>=1.60
Requires-Dist: xds-protos>=1.60
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# Internet of Cognition (IOC) - Cognition Fabric Node (CFN) MAS Client Library

[![PyPI version](https://badge.fury.io/py/ioc-cfn-mas-client-lib.svg)](https://badge.fury.io/py/ioc-cfn-mas-client-lib)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Python SDK client library for the Internet of Cognition (IoC) Cognition Fabric Node.

## Compatibility

**Current Version: 0.3.1** supports **CFN Public API v0.2.1**

## Overview

This library provides a Python client for forwarding **L9 protocol messages** to the CFN (Cognition Fabric Node) service, which routes them to appropriate Cognition Engines based on the message header.

The **L9 protocol (SSTP - Semantic State Transfer Protocol)** enables standardized communication between Multi-Agent Systems and Cognition Engines in the IoC ecosystem.

## Installation

**Requires Python >= 3.10**

```bash
pip install ioc-cfn-mas-client-lib
```

## Quick Start

### Forwarding L9 Messages

```python
from ioc_cfn_mas_client import Client

# Initialize the CFN client
client = Client(cfn_url="http://localhost:9002")

# Construct and forward an L9 message
response = client.forward_l9_message(
    message={
        "header": {
            "protocol": "sstp",           # Always "sstp" for L9
            "version": "1.0",              # Protocol version
            "subprotocol": "TFP",          # Subprotocol: TFP, CIP, SIEP, SAB, etc.
            "kind": "exchange",            # Message kind: intent, contingency, exchange, commit, knowledge
            "participants": {
                "actors": [                # Participating agents/actors
                    {
                        "id": "monitoring-agent",
                        "role": "sender"
                    },
                    {
                        "id": "metrics-processor",
                        "role": "receiver"
                    }
                ],
                "groups": {                # Routing information
                    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",  # Target workspace UUID
                    "mas_id": "660e8400-e29b-41d4-a716-446655440001"         # Target MAS UUID
                }
            }
        },
        "payload": {
            "type": "application/json",    # Payload MIME type
            "data": {                      # Custom payload data
                "operation": "query_metrics",
                "parameters": {
                    "metric_types": ["cpu", "memory", "disk"],
                    "time_range": "last_hour"
                },
                "metadata": {
                    "source": "monitoring-agent",
                    "timestamp": "2026-07-15T10:30:00Z"
                }
            }
        }
    }
)

print(f"Message forwarded successfully: {response}")
```

### L9 Message Structure

L9 messages follow the **SSTP specification** and consist of two main components:

#### Header (Required)
- **`protocol`**: Always `"sstp"` for L9 messages
- **`version`**: Protocol version (e.g., `"1.0"`)
- **`subprotocol`**: Subprotocol identifier - one of:
  - `"TFP"` - Team Formation via Polling
  - `"CIP"` - Contingency Interaction Protocol
  - `"SIEP"` - Semantic Interoperability and Epistemic Protocol
  - `"SAB"` - Semantic Alignment via Bargaining
  - Or any custom subprotocol identifier
- **`kind`**: Message type - one of:
  - `intent` - Opens an episode; declares concept and participating group
  - `contingency` - Signals a grounding problem that requires repair
  - `exchange` - Substantive contribution (assertion, counter, data transfer)
  - `commit` - Closes an episode or contingency branch
  - `knowledge` - Single-message episode for knowledge base updates
- **`subkind`** (optional): Qualifies the `kind` field - common values:
  - For `commit`: `converged` (agreement reached), `rejected` (no agreement), `resolved` (repair complete), `ready` (done signal)
  - For `exchange`: `ready` (final contribution + done)
  - For subprotocols: Each subprotocol may define its own (e.g., TFP uses `team-formation`)
  - Can be `null` or omitted for most messages
- **`participants`**: Routing and actor information
  - **`actors`**: Array of participating agents/actors with `id` and `role`
  - **`groups`**: Routing groups with **`workspace_id`** and **`mas_id`** (both UUIDs)

#### Payload (Required)
- **`type`**: Payload MIME type - depends on subprotocol:
  - `"application/json"` - Generic JSON data
  - `"json-schema"` - Structured data conforming to a schema (TFP, SAB)
  - `"cip"` - CIP-specific payload (utterance, grounding, belief)
  - `"siep"` - SIEP-specific payload (epistemic negotiation)
  - `"text/plain"` - Plain text messages
- **`data`**: Payload content - structure depends on subprotocol and `type`

## Configuration

The `Client` constructor accepts:

- **`cfn_url`** (required): CFN API endpoint URL (e.g., `"http://localhost:9002"`)
- **`timeout`** (optional): Request timeout in seconds
- **`configuration`** (optional): Pre-configured `Configuration` object (advanced)
- **`api_client`** (optional): Pre-configured `ApiClient` object (advanced)

### Environment Variables

Optional environment variable:

- **`CFN_URL`**: CFN API endpoint URL (defaults to `http://localhost:9002`)

## Development

For development setup, OpenAPI code generation, and contribution guidelines, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## API Documentation

This SDK is auto-generated from the [CFN Public API OpenAPI specification](https://github.com/outshift-open/ioc-cfn-svc/tree/main/docs/public-api). For detailed API documentation, see the upstream repository.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `uv run pytest`
5. Submit a pull request

For more details, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## License

This project is licensed under the Apache License, Version 2.0 - see the [LICENSE.md](LICENSE.md) file for full details.

Copyright (c) 2024-2026 Cisco Systems, Inc. and its affiliates. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
