sdk-python/README.md

# AIPM Python SDK

**Agent Interoperability Protocol Models** - Python reference implementation

## Overview

AIPM is the first open ecosystem for interoperable AI agents, enabling agents from different vendors (OpenAI, Claude, LangGraph, AutoGen, CrewAI, etc.) to communicate securely and consistently using the same protocol.

## Features

✅ **Identity Layer** - Standardized agent identification and capabilities  
✅ **Secure Handshake** - TLS-inspired connection establishment  
✅ **Capability Discovery** - Automatic discovery of skills and tools  
✅ **Task Negotiation** - Accept/decline work based on capability  
✅ **Memory Exchange** - Efficient context sharing  
✅ **Trust Layer** - Reputation and reliability tracking  
✅ **Cryptographic Security** - Ed25519 signatures and verification  

## Installation

```bash
pip install aipm
```

Or from source:

```bash
git clone https://github.com/aipm/aipm.git
cd aipm/sdk-python
pip install -e .
```

## Quick Start

```python
from aipm import AIPMAgent, AgentIdentity, AgentReference, Capabilities

# Create agent identity
identity = AgentIdentity(
    agent_id="my-agent-001",
    organization_id="my-org",
    name="My AI Agent",
    version="1.0.0",
    capabilities=Capabilities(
        skills=["text-generation", "code-review"],
        models=["gpt-4"],
        tools=["code-interpreter"],
    )
)

# Initialize agent
agent = AIPMAgent(identity)

# Initiate handshake with another agent
peer = AgentReference(
    agent_id="peer-agent-001",
    organization_id="peer-org"
)
hello_msg = agent.initiate_handshake(peer)

# Process messages
response = agent.process_message(hello_msg)

# Check if ready
if agent.is_ready(peer):
    # Send task request
    task_msg = agent.create_task_request(
        peer,
        task_description="Process customer data",
        priority="high"
    )
```

## Examples

See `examples/basic_handshake.py` for a complete handshake between two agents:

```bash
cd examples
python basic_handshake.py
```

## Architecture

### Core Components

- **AgentIdentity** - Complete agent profile with capabilities
- **MessageEnvelope** - Standard message format
- **HandshakeManager** - State machine for secure handshake
- **AIPMAgent** - Base agent implementation
- **CryptoManager** - Cryptographic operations

### Handshake Protocol

```
Agent A                          Agent B
   |                                |
   |------- HELLO ----------------->|
   |<--- CAPABILITY_EXCHANGE -------|
   |------- AUTHENTICATION -------->|
   |<--- PUBLIC_KEY_EXCHANGE -------|
   |------- TRUST_VERIFICATION ---->|
   |<--- READY ---------------------|
   |                                |
   [Ready for task delegation]
```

## API Reference

### AgentIdentity

```python
identity = AgentIdentity(
    agent_id="unique-id",
    organization_id="org-id",
    name="Agent Name",
    version="1.0.0",
    capabilities=Capabilities(...),
    trust_score=TrustScore(...),
)
```

### AIPMAgent

```python
agent = AIPMAgent(identity)

# Initiate handshake
msg = agent.initiate_handshake(peer_reference)

# Process incoming messages
response = agent.process_message(incoming_msg)

# Check handshake status
is_ready = agent.is_ready(peer_reference)

# Get peer identity
peer_identity = agent.get_peer_identity(peer_reference)

# Create task request
task_msg = agent.create_task_request(
    peer_reference,
    task_description="Process data",
    priority="high"
)
```

## Development

Install development dependencies:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

Format code:

```bash
black aipm/
ruff check aipm/
```

## Roadmap

- [x] Core protocol schemas
- [x] Identity and handshake models
- [x] Basic agent implementation
- [ ] Async support
- [ ] HTTP/WebSocket transport
- [ ] Task negotiation framework
- [ ] Memory exchange protocol
- [ ] Trust scoring system
- [ ] Economic layer
- [ ] Comprehensive test suite

## Contributing

Contributions welcome! Please see CONTRIBUTING.md

## License

Apache 2.0

## Links

- Documentation: https://docs.aipm.org
- Repository: https://github.com/aipm/aipm
- Issues: https://github.com/aipm/aipm/issues