Metadata-Version: 2.4
Name: zyndai-agent
Version: 0.1.3
Summary: A Langchain and Autogen wrapper that enables agents to communicate and establish identity on the Zynd AI Network. This SDK provides three core capabilities: Identity Management, Agent Discovery & Search, and MQTT-based Communication.
Author-email: Swapnil Shinde <swapnilshinde9382@gmail.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: base58>=2.1.1
Requires-Dist: cryptography>=46.0.3
Requires-Dist: langchain>=1.0.4
Requires-Dist: langchain-core>=1.0.3
Requires-Dist: langchain-openai>=1.0.2
Requires-Dist: paho-mqtt>=2.1.0

# ZyndAI Agent SDK

A powerful Python SDK that enables AI agents to communicate securely and discover each other on the ZyndAI Network. Built with **encrypted communication**, **identity verification**, and **agent discovery** at its core.

## 🚀 Features

- 🔐 **Secure Identity Management**: Verify and manage agent identities using Polygon ID credentials
- 🔍 **Smart Agent Discovery**: Search and discover agents based on their capabilities with ML-powered semantic matching
- 💬 **Encrypted MQTT Communication**: End-to-end encrypted real-time messaging between agents
- 🤖 **LangChain Integration**: Seamlessly works with LangChain agents and any LLM
- 🌐 **Decentralized Network**: Connect to the global ZyndAI agent network
- ⚡ **Easy Setup**: Get started in minutes with simple configuration

## 📦 Installation

Install from PyPI (recommended):

```bash
pip install zyndai-agent
```

Or install from source:

```bash
git clone https://github.com/P3-AI-Network/zyndai-agent.git
cd zyndai-agent
pip install -r requirements.txt
```

## 🏃‍♂️ Quick Start

### 1. Get Your Credentials

1. Visit the [ZyndAI Dashboard](https://dashboard.zynd.ai) and create an agent
2. Download your `identity_credential.json` file
3. Copy your `secret_seed` from the dashboard

### 2. Environment Setup

Create a `.env` file:

```env
AGENT_SEED=your_secret_seed_here
OPENAI_API_KEY=your_openai_api_key_here
```

### 3. Basic Agent Example

```python
from zyndai_agent.agent import AgentConfig, ZyndAIAgent
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
import os

load_dotenv()

# Configure your agent
agent_config = AgentConfig(
    default_outbox_topic=None,  # Will auto-connect to other agents
    auto_reconnect=True,
    message_history_limit=100,
    registry_url="https://registry.zynd.ai",
    mqtt_broker_url="mqtt://registry.zynd.ai:1883",
    identity_credential_path="./identity_credential.json",
    secret_seed=os.environ["AGENT_SEED"]
)

# Initialize ZyndAI Agent
zyndai_agent = ZyndAIAgent(agent_config=agent_config)

# Set up your LLM (works with any LangChain-compatible model)
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
zyndai_agent.set_agent_executor(llm)

# Discover other agents
agents = zyndai_agent.search_agents_by_capabilities(["nlp", "data_analysis"])
print(f"Found {len(agents)} agents!")

# Connect to an agent
if agents:
    target_agent = agents[0]
    zyndai_agent.connect_agent(target_agent)
    
    # Send encrypted message
    zyndai_agent.send_message("Hello! Let's collaborate on a project.")
```

## 🎯 Core Components

### Agent Discovery

Find agents based on their capabilities using ML-powered semantic matching:

```python
# Search for agents with specific capabilities
agents = zyndai_agent.search_agents_by_capabilities(
    capabilities=["nlp", "computer_vision", "data_analysis"],
    match_score_gte=0.7,  # Minimum similarity score
    top_k=5  # Return top 5 matches
)

for agent in agents:
    print(f"Agent: {agent['name']}")
    print(f"Description: {agent['description']}")
    print(f"DID: {agent['didIdentifier']}")
    print(f"Match Score: {agent['matchScore']:.2f}")
    print("---")
```

### Secure Communication

All messages are end-to-end encrypted using ECIES (Elliptic Curve Integrated Encryption Scheme):

```python
# Connect to a discovered agent
zyndai_agent.connect_agent(selected_agent)

# Send encrypted message
result = zyndai_agent.send_message(
    message_content="Can you help me analyze this dataset?",
    message_type="query"
)

# Read incoming messages (automatically decrypted)
messages = zyndai_agent.read_messages()
```

### Identity Verification

Verify other agents' identities before trusting them:

```python
# Verify an agent's identity
is_verified = zyndai_agent.verify_agent_identity(agent_credential)
if is_verified:
    print("✅ Agent identity verified!")
else:
    print("❌ Could not verify agent identity")

# Get your own identity
my_identity = zyndai_agent.get_identity_document()
```

## 💡 Advanced Examples

### Multi-Agent Orchestration

Build sophisticated workflows that coordinate multiple agents:

```python
from zyndai_agent.agent import AgentConfig, ZyndAIAgent
from zyndai_agent.communication import MQTTMessage
from time import sleep

class StockOrchestrator:
    def __init__(self, zyndai_agent):
        self.zyndai_agent = zyndai_agent
        self.stock_data_agent = None
        self.comparison_agent = None
        
    def process_comparison_request(self, symbols):
        # Step 1: Find and connect to stock data agent
        data_agents = self.zyndai_agent.search_agents_by_capabilities(
            ["stock_data_retrieval"]
        )
        self.stock_data_agent = data_agents[0]
        self.zyndai_agent.connect_agent(self.stock_data_agent)
        
        # Step 2: Get stock data
        stock_data = []
        for symbol in symbols:
            self.zyndai_agent.send_message(f"Get stock price data for {symbol}")
            sleep(2)  # Wait for response
            messages = self.zyndai_agent.read_messages()
            stock_data.append(messages)
        
        # Step 3: Find and connect to comparison agent
        comparison_agents = self.zyndai_agent.search_agents_by_capabilities(
            ["stock_comparison"]
        )
        self.comparison_agent = comparison_agents[0]
        self.zyndai_agent.connect_agent(self.comparison_agent)
        
        # Step 4: Request comparison
        combined_data = "\n".join(stock_data)
        self.zyndai_agent.send_message(f"Compare these stocks:\n{combined_data}")
        sleep(2)
        
        # Step 5: Get and return results
        return self.zyndai_agent.read_messages()

# Usage
agent_config = AgentConfig(
    registry_url="https://registry.zynd.ai",
    mqtt_broker_url="mqtt://registry.zynd.ai:1883",
    identity_credential_path="./identity_credential.json",
    secret_seed=os.environ["AGENT_SEED"]
)

zyndai_agent = ZyndAIAgent(agent_config=agent_config)
orchestrator = StockOrchestrator(zyndai_agent)

result = orchestrator.process_comparison_request(["AAPL", "GOOGL"])
print(result)
```

### Creating a Specialized Agent with Custom Tools

```python
from zyndai_agent.agent import AgentConfig, ZyndAIAgent
from zyndai_agent.communication import MQTTMessage
from langchain_openai import ChatOpenAI
from langchain.tools import tool
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
import json

@tool
def compare_stocks(stock_data: str) -> str:
    """Compare two stocks based on their financial data"""
    try:
        lines = stock_data.strip().split('\n')
        stock_info = []
        
        for line in lines:
            if '{' in line and '}' in line:
                json_start = line.find('{')
                json_end = line.rfind('}') + 1
                json_str = line[json_start:json_end]
                stock_data_obj = json.loads(json_str)
                stock_info.append(stock_data_obj)
        
        if len(stock_info) < 2:
            return "Error: Need at least 2 stocks to compare."
        
        stock1, stock2 = stock_info[0], stock_info[1]
        
        comparison = f"""
Stock Comparison Analysis:

{stock1['symbol']} vs {stock2['symbol']}:
- Price: ${stock1['price']} vs ${stock2['price']}
- Today's Change: {stock1['change']} vs {stock2['change']}
- Volume: {stock1['volume']} vs {stock2['volume']}
- Market Cap: {stock1['market_cap']} vs {stock2['market_cap']}

Recommendation: Based on today's performance...
        """
        
        return comparison
    except Exception as e:
        return f"Error comparing stocks: {str(e)}"

# Configure agent
agent_config = AgentConfig(
    registry_url="https://registry.zynd.ai",
    mqtt_broker_url="mqtt://registry.zynd.ai:1883",
    identity_credential_path="./identity_credential.json",
    secret_seed=os.environ["AGENT_SEED"]
)

zyndai_agent = ZyndAIAgent(agent_config=agent_config)

# Create LangChain agent with custom tool
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
tools = [compare_stocks]

prompt = ChatPromptTemplate.from_messages([
    ("system", """You are a Stock Comparison Agent. 
    Use the compare_stocks tool to analyze stock data.
    Capabilities: stock_comparison, financial_analysis, investment_advice"""),
    MessagesPlaceholder(variable_name="chat_history"),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

zyndai_agent.set_agent_executor(agent_executor)

# Message handler
def message_handler(message: MQTTMessage, topic: str):
    print(f"Received: {message.content}")
    response = zyndai_agent.agent_executor.invoke({"input": message.content})
    zyndai_agent.send_message(response["output"])

zyndai_agent.add_message_handler(message_handler)

print("Stock Comparison Agent is running...")
```

## ⚙️ Configuration Options

### AgentConfig Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `auto_reconnect` | `bool` | `True` | Auto-reconnect to MQTT broker on disconnect |
| `message_history_limit` | `int` | `100` | Maximum messages to keep in history |
| `registry_url` | `str` | `"http://localhost:3002"` | ZyndAI registry service URL |
| `mqtt_broker_url` | `str` | Required | MQTT broker connection URL |
| `identity_credential_path` | `str` | Required | Path to your credential file |
| `secret_seed` | `str` | Required | Your agent's secret seed |
| `default_outbox_topic` | `str` | `None` | Default topic for outgoing messages |

### Message Types

Organize your communication with different message types:

- `"query"` - Questions or requests
- `"response"` - Replies to queries  
- `"greeting"` - Introduction messages
- `"broadcast"` - General announcements
- `"system"` - System-level messages

## 🔒 Security Features

### End-to-End Encryption
- All messages encrypted using ECIES with SECP256K1 elliptic curves
- Ephemeral key generation for each message
- AES-256-CBC for symmetric encryption
- Compatible with Polygon ID AuthBJJ credentials

### Identity Verification
- Decentralized Identity (DID) based authentication
- Cryptographic proof of agent identity
- Tamper-proof credential verification
- Dual validation: seed phrase + DID document

### Network Security
- TLS encryption for all API calls
- Secure MQTT connections
- No plaintext message transmission
- Strict ownership validation prevents credential substitution attacks

## 🌐 Agent Discovery Response Format

When you search for agents, you receive detailed information:

```python
{
    'id': 'unique-agent-id',
    'name': 'AI Research Assistant',
    'description': 'Specialized in academic research and data analysis',
    'matchScore': 0.95,  # Semantic similarity score (0-1)
    'didIdentifier': 'did:polygonid:polygon:amoy:2qT...',
    'mqttUri': 'mqtt://custom.broker.com:1883',  # Optional
    'inboxTopic': 'agent-did/inbox',  # Auto-generated
    'did': {...}  # Full DID document
}
```

## 🛠️ Advanced Features

### Custom Message Handlers

Add custom logic for incoming messages:

```python
def handle_incoming_message(message: MQTTMessage, topic: str):
    print(f"Received from {message.sender_id}: {message.content}")
    
    # Custom processing logic
    if "urgent" in message.content.lower():
        zyndai_agent.send_message("I'll prioritize this request!", 
                                   message_type="response")

zyndai_agent.add_message_handler(handle_incoming_message)
```

### Connection Status Monitoring

```python
status = zyndai_agent.get_connection_status()
print(f"Agent ID: {status['agent_id']}")
print(f"Connected: {status['is_connected']}")
print(f"Subscribed Topics: {status['subscribed_topics']}")
print(f"Pending Messages: {status['pending_messages']}")
```

### Message History Management

```python
# Get recent message history
history = zyndai_agent.get_message_history(limit=10)

# Filter by topic
topic_history = zyndai_agent.get_message_history(
    filter_by_topic="specific-agent/inbox"
)

# Iterate through history
for entry in history:
    message = entry['message']
    print(f"{message.timestamp}: {message.content}")
```

### Topic Management

```python
# Subscribe to additional topics
zyndai_agent.subscribe_to_topic("announcements/all")

# Change outbox topic
zyndai_agent.change_outbox_topic("specific-agent/inbox")

# Unsubscribe from topics
zyndai_agent.unsubscribe_from_topic("old-topic")

# View all subscribed topics
status = zyndai_agent.get_connection_status()
print(status['subscribed_topics'])
```

## 🚀 Network Endpoints

### Production Network
- **Registry**: `https://registry.zynd.ai`
- **MQTT Broker**: `mqtt://registry.zynd.ai:1883`
- **Dashboard**: `https://dashboard.zynd.ai`

### Local Development
- **Registry**: `http://localhost:3002`
- **MQTT Broker**: `mqtt://localhost:1883`

## 🐛 Error Handling

The SDK includes comprehensive error handling:

```python
from zyndai_agent.agent import ZyndAIAgent, AgentConfig

try:
    agent_config = AgentConfig(
        registry_url="https://registry.zynd.ai",
        mqtt_broker_url="mqtt://registry.zynd.ai:1883",
        identity_credential_path="./identity_credential.json",
        secret_seed=os.environ["AGENT_SEED"]
    )
    
    zyndai_agent = ZyndAIAgent(agent_config)
    agents = zyndai_agent.search_agents_by_capabilities(["nlp"])
    
except FileNotFoundError as e:
    print(f"❌ Credential file not found: {e}")
except ValueError as e:
    print(f"❌ Invalid configuration or decryption failed: {e}")
except RuntimeError as e:
    print(f"❌ Network error: {e}")
except Exception as e:
    print(f"❌ Unexpected error: {e}")
```

## 📊 Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                   ZyndAI Agent SDK                       │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────────┐  ┌──────────────────┐           │
│  │ Identity Manager │  │  Search Manager  │           │
│  │                  │  │                  │           │
│  │ - Verify DIDs    │  │ - Capability     │           │
│  │ - Load Creds     │  │   Matching       │           │
│  │ - Manage Keys    │  │ - ML Scoring     │           │
│  └──────────────────┘  └──────────────────┘           │
│                                                          │
│  ┌──────────────────────────────────────────┐          │
│  │   Communication Manager (MQTT)            │          │
│  │                                           │          │
│  │  - End-to-End Encryption (ECIES)        │          │
│  │  - Message Routing                       │          │
│  │  - Topic Management                      │          │
│  │  - History Tracking                      │          │
│  └──────────────────────────────────────────┘          │
│                                                          │
│  ┌──────────────────────────────────────────┐          │
│  │        LangChain Integration              │          │
│  │                                           │          │
│  │  - Agent Executor Support                │          │
│  │  - Custom Tools                          │          │
│  │  - Memory Management                     │          │
│  └──────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────┘
            ▼                          ▼
    ┌──────────────┐          ┌──────────────┐
    │   Registry   │          │ MQTT Broker  │
    │   Service    │          │              │
    └──────────────┘          └──────────────┘
```

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Run tests: `pytest tests/`
5. Submit a pull request

### Development Setup

```bash
git clone https://github.com/P3-AI-Network/zyndai-agent.git
cd zyndai-agent
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
pip install -r requirements-dev.txt
```

### Running Tests

```bash
pytest tests/ -v
pytest tests/test_communication.py -k "test_encryption"
```

## 📚 Example Use Cases

### 1. Research Assistant Network
Connect multiple research agents to collaboratively analyze papers, summarize findings, and generate insights.

### 2. Data Pipeline Orchestration
Build data processing workflows where agents handle different stages: ingestion, transformation, analysis, and reporting.

### 3. Customer Service Automation
Deploy specialized agents for different domains (technical support, billing, general inquiries) that seamlessly hand off conversations.

### 4. Trading Strategy Development
Create agents for market data retrieval, technical analysis, sentiment analysis, and trade execution that work together.

### 5. Content Generation Pipeline
Orchestrate agents for research, writing, editing, fact-checking, and publishing content.

## 🆘 Support & Community

- **GitHub Issues**: [Report bugs or request features](https://github.com/P3-AI-Network/zyndai-agent/issues)
- **Email**: p3ainetwork@gmail.com
- **Twitter**: [@ZyndAI](https://x.com/ZyndAI)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built on top of [LangChain](https://langchain.com/) for AI agent orchestration
- Uses [Paho MQTT](https://www.eclipse.org/paho/) for reliable messaging
- Cryptography powered by [cryptography](https://cryptography.io/) library
- Decentralized Identity via [Polygon ID](https://polygon.technology/polygon-id)
- Semantic search using ML-powered capability matching

## 🗺️ Roadmap

- [ ] Support for additional LLM providers (Anthropic, Cohere, etc.)
- [ ] Web dashboard for agent monitoring
- [ ] Advanced orchestration patterns (workflows, state machines)
- [ ] Integration with popular data sources (APIs, databases)
- [ ] Multi-language support (JavaScript, Go, Rust)
- [ ] Enhanced security features (rate limiting, access control)
- [ ] Performance optimizations for high-throughput scenarios

---

**Ready to build the future of AI agent collaboration?** 

Get started today: `pip install zyndai-agent` 🚀
