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

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

pip install ioc-cfn-mas-client-lib

Quick Start

Forwarding L9 Messages

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.

API Documentation

This SDK is auto-generated from the CFN Public API OpenAPI specification. 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.

License

This project is licensed under the Apache License, Version 2.0 - see the 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.