traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/registry/readmes/IATP_SEARCH_API_GUIDE.md

@@ -0,0 +1,257 @@
+# IATP Search API Guide
+
+The `iatp_search_api.py` module provides a high-level API for searching and retrieving information about utility agents and MCP servers from the IATP registry.
+
+## Overview
+
+This API provides read-only access to the MongoDB registry without requiring direct database dependencies. It automatically handles authentication using X.509 certificates or username/password.
+
+## Authentication
+
+The API automatically detects and uses the appropriate authentication method:
+
+1. **X.509 Certificate** (if `MONGODB_X509_CERT_FILE` is set)
+2. **Username/Password** (if `MONGODB_USER` and `MONGODB_PASSWORD` are set)
+3. **Connection String** (if `MONGODB_CONNECTION_STRING` is set)
+
+## Available Functions
+
+### Utility Agent Functions
+
+#### `find_utility_agent(name=None, capability=None, tag=None, query=None)`
+Find a single utility agent by specific criteria.
+
+```python
+from traia_iatp.registry.iatp_search_api import find_utility_agent
+
+# Find by exact name
+agent = find_utility_agent(name="hyperliquid-mcp-traia-utility-agency")
+
+# Find by capability
+agent = find_utility_agent(capability="market_info")
+
+# Find by tag
+agent = find_utility_agent(tag="trading")
+
+# Find by text query
+agent = find_utility_agent(query="trading bot")
+```
+
+#### `list_utility_agents(limit=10, tags=None, capabilities=None, active_only=True)`
+List utility agents with optional filters.
+
+```python
+from traia_iatp.registry.iatp_search_api import list_utility_agents
+
+# List all active agents
+agents = list_utility_agents(limit=20)
+
+# Filter by tags
+agents = list_utility_agents(tags=["trading", "defi"])
+
+# Filter by capabilities
+agents = list_utility_agents(capabilities=["market_info", "trading_orders"])
+```
+
+#### `search_utility_agents(query, limit=10, active_only=True, embedding_fields=None)`
+Search utility agents using vector search.
+
+```python
+from traia_iatp.registry.iatp_search_api import search_utility_agents
+
+# Search using default search_text embedding (recommended for best performance)
+agents = await search_utility_agents("trading hyperliquid", limit=5)
+
+# Search using specific embedding fields
+agents = await search_utility_agents(
+    "trading hyperliquid", 
+    limit=5,
+    embedding_fields=["description", "tags"]
+)
+
+# Search across all embedding fields (slower but more comprehensive)
+agents = await search_utility_agents(
+    "market data", 
+    limit=5,
+    embedding_fields=["description", "tags", "capabilities", "agent_card"]
+)
+```
+
+### MCP Server Functions
+
+#### `find_mcp_server(name=None, capability=None, tag=None, query=None)`
+Find a single MCP server by specific criteria.
+
+```python
+from traia_iatp.registry.iatp_search_api import find_mcp_server
+
+# Find by exact name
+server = find_mcp_server(name="hyperliquid-mcp")
+
+# Find by capability
+server = find_mcp_server(capability="trading_orders")
+```
+
+#### `list_mcp_servers(limit=10, tags=None, capabilities=None)`
+List MCP servers with optional filters.
+
+```python
+from traia_iatp.registry.iatp_search_api import list_mcp_servers
+
+# List all servers
+servers = list_mcp_servers(limit=10)
+
+# Filter by capabilities
+servers = list_mcp_servers(capabilities=["market_info"])
+```
+
+#### `search_mcp_servers(query, limit=10, embedding_fields=None)`
+Search MCP servers using vector search.
+
+```python
+from traia_iatp.registry.iatp_search_api import search_mcp_servers
+
+# Search using default embedding fields (description and capabilities)
+servers = await search_mcp_servers("trading", limit=5)
+
+# Search using only description embedding
+servers = await search_mcp_servers(
+    "trading", 
+    limit=5,
+    embedding_fields=["description"]
+)
+```
+
+#### `get_mcp_server(name)`
+Get detailed MCP server information by name (returns raw MongoDB document).
+
+```python
+from traia_iatp.registry.iatp_search_api import get_mcp_server
+
+# Get full server details
+server_doc = get_mcp_server("hyperliquid-mcp")
+if server_doc:
+    print(f"Server ID: {server_doc['_id']}")
+    print(f"Capabilities: {server_doc['capabilities']}")
+```
+
+## Data Models
+
+### UtilityAgentInfo
+```python
+@dataclass
+class UtilityAgentInfo:
+    agent_id: str
+    name: str
+    description: str
+    base_url: str
+    capabilities: List[str]
+    tags: List[str]
+    is_active: bool
+    metadata: Dict[str, Any]
+    skills: List[Dict[str, Any]]
+```
+
+### MCPServerInfo
+```python
+@dataclass
+class MCPServerInfo:
+    id: str
+    name: str
+    url: str
+    description: str
+    server_type: str
+    capabilities: List[str]
+    metadata: Dict[str, Any]
+    tags: List[str]
+```
+
+## Complete Example
+
+```python
+#!/usr/bin/env python
+import asyncio
+import os
+from traia_iatp.registry.iatp_search_api import (
+    find_utility_agent,
+    list_utility_agents,
+    search_utility_agents,
+    find_mcp_server,
+    list_mcp_servers,
+    search_mcp_servers
+)
+
+
+async def main():
+    # Set authentication (choose one)
+    os.environ["MONGODB_X509_CERT_FILE"] = "/path/to/cert.pem"
+    # OR
+    # os.environ["MONGODB_USER"] = "username"
+    # os.environ["MONGODB_PASSWORD"] = "password"
+
+    # Search for trading agents using vector search (default search_text embedding)
+    print("Trading agents:")
+    agents = await search_utility_agents("trading", limit=5)
+    for agent in agents:
+        print(f"- {agent.name}: {agent.base_url}")
+
+    # Find specific agent
+    agent = find_utility_agent(name="hyperliquid-mcp-traia-utility-agency")
+    if agent:
+        print(f"\nFound agent: {agent.name}")
+        print(f"Capabilities: {', '.join(agent.capabilities)}")
+        print(f"Tags: {', '.join(agent.tags)}")
+
+    # List MCP servers
+    print("\nMCP Servers:")
+    servers = list_mcp_servers(limit=5)
+    for server in servers:
+        print(f"- {server.name}: {server.url}")
+    
+    # Search MCP servers with specific embedding field
+    print("\nSearching MCP servers by description:")
+    servers = await search_mcp_servers("trading", limit=3, embedding_fields=["description"])
+    for server in servers:
+        print(f"- {server.name}: {server.description}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Environment Configuration
+
+Set the environment to control which MongoDB collections are used:
+
+```bash
+export ENV=test      # Uses test collections (default)
+export ENV=staging   # Uses staging collections  
+export ENV=prod      # Uses production collections
+```
+
+## Error Handling
+
+The API will raise a `ValueError` if no authentication method is configured:
+
+```python
+try:
+    agents = list_utility_agents()
+except ValueError as e:
+    print(f"Authentication error: {e}")
+```
+
+## Performance Notes
+
+- The API uses connection pooling for efficiency
+- Results are returned as Python dataclasses for easy access
+- Text search requires MongoDB text indexes to be configured
+- Consider using `limit` parameter to control result size
+
+## Testing
+
+Run the example script to test the API:
+
+```bash
+cd traia-centralized-backend
+uv run python tests/test_mongodb_registry/example_iatp_registry_api.py
+``` 

traia_iatp/registry/readmes/MONGODB_X509_AUTH.md

@@ -0,0 +1,208 @@
+# MongoDB X.509 Certificate Authentication Guide
+
+This guide explains how to set up and use X.509 certificate authentication for MongoDB access in the IATP registry.
+
+## Overview
+
+X.509 certificate authentication provides a secure way to authenticate to MongoDB without using passwords or API keys. It uses SSL/TLS certificates for both encryption and authentication.
+
+## Prerequisites
+
+1. **MongoDB Atlas Cluster** with X.509 authentication enabled
+2. **Certificate file** (.pem) containing both the certificate and private key
+3. **Certificate user** created in MongoDB's `$external` database
+
+## Setup Steps
+
+### 1. Obtain Your X.509 Certificate
+
+If you've already created a certificate-based user via MongoDB Atlas UI:
+
+```bash
+# Your certificate file should contain both the certificate and private key
+# It typically looks like this:
+#
+# -----BEGIN CERTIFICATE-----
+# [certificate content]
+# -----END CERTIFICATE-----
+# -----BEGIN PRIVATE KEY-----
+# [private key content]
+# -----END PRIVATE KEY-----
+```
+
+### 2. Configure Environment Variable
+
+Set the path to your certificate file:
+
+```bash
+export MONGODB_X509_CERT_FILE="/path/to/your/certificate.pem"
+```
+
+For permanent configuration, add to your `.env` file:
+
+```env
+MONGODB_X509_CERT_FILE=/path/to/your/certificate.pem
+```
+
+### 3. Verify Certificate Setup
+
+Extract the certificate subject (this should match your MongoDB user):
+
+```bash
+openssl x509 -in /path/to/your/certificate.pem -noout -subject
+```
+
+Example output:
+```
+subject=CN=myapp,OU=myteam,O=mycompany,L=city,ST=state,C=US
+```
+
+### 4. Test the Connection
+
+Run the test script to verify authentication:
+
+```bash
+cd traia-centralized-backend
+uv run python tests/test_mongodb_registry/test_mongodb_x509_auth.py
+```
+
+## Authentication Priority
+
+The registries support multiple authentication methods with the following priority:
+
+1. **X.509 Certificate** (if `MONGODB_X509_CERT_FILE` is set)
+2. **Username/Password** (if `MONGODB_USER` and `MONGODB_PASSWORD` are set)
+3. **Connection String** (if `MONGODB_CONNECTION_STRING` is set)
+
+## Security Best Practices
+
+### Certificate File Protection
+
+1. **Restrict file permissions**:
+   ```bash
+   chmod 600 /path/to/your/certificate.pem
+   ```
+
+2. **Store securely**:
+   - Never commit certificate files to version control
+   - Use secure secret management systems for production
+   - Consider using environment-specific certificates
+
+### Certificate Management
+
+1. **Rotation**: Plan for certificate rotation before expiration
+2. **Monitoring**: Set up alerts for certificate expiration
+3. **Backup**: Keep secure backups of certificates
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failed**
+   - Verify the certificate user exists in MongoDB's `$external` database
+   - Check certificate hasn't expired: `openssl x509 -in cert.pem -noout -dates`
+   - Ensure certificate was issued by the correct CA
+
+2. **Connection Refused**
+   - Verify MongoDB cluster allows connections from your IP
+   - Check that TLS is enabled on the cluster
+
+3. **Invalid Certificate Format**
+   - Ensure the .pem file contains both certificate and private key
+   - Verify no extra whitespace or formatting issues
+
+### Debug Commands
+
+```bash
+# Check certificate validity
+openssl x509 -in cert.pem -noout -text
+
+# Verify private key matches certificate
+openssl x509 -noout -modulus -in cert.pem | openssl md5
+openssl rsa -noout -modulus -in cert.pem | openssl md5
+
+# Test SSL connection to MongoDB
+openssl s_client -connect your-cluster.mongodb.net:27017 -CAfile cert.pem
+```
+
+## Integration with IATP Services
+
+### Using with Registry API
+
+The registry automatically detects and uses X.509 authentication when configured:
+
+```python
+from traia_iatp.registry.mongodb_registry import UtilityAgentRegistry
+
+# No need to pass credentials - uses MONGODB_X509_CERT_FILE automatically
+registry = UtilityAgentRegistry()
+```
+
+### Docker Deployment
+
+When deploying in Docker, mount the certificate file:
+
+```yaml
+# docker-compose.yml
+services:
+  api:
+    environment:
+      - MONGODB_X509_CERT_FILE=/certs/mongodb.pem
+    volumes:
+      - ./certs/mongodb.pem:/certs/mongodb.pem:ro
+```
+
+### Kubernetes Deployment
+
+Use Kubernetes secrets for certificate management:
+
+```yaml
+# Create secret
+kubectl create secret generic mongodb-cert --from-file=mongodb.pem=/path/to/cert.pem
+
+# Mount in deployment
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  template:
+    spec:
+      containers:
+      - name: app
+        env:
+        - name: MONGODB_X509_CERT_FILE
+          value: /certs/mongodb.pem
+        volumeMounts:
+        - name: mongodb-cert
+          mountPath: /certs
+          readOnly: true
+      volumes:
+      - name: mongodb-cert
+        secret:
+          secretName: mongodb-cert
+```
+
+## Migration from Username/Password
+
+To migrate from username/password to X.509 certificate authentication:
+
+1. Create certificate-based user in MongoDB Atlas
+2. Update environment configuration:
+   ```bash
+   # Remove or comment out
+   # MONGODB_USER=...
+   # MONGODB_PASSWORD=...
+   
+   # Add
+   MONGODB_X509_CERT_FILE=/path/to/cert.pem
+   ```
+3. Test with `test_mongodb_x509_auth.py`:
+   ```bash
+   uv run python tests/test_mongodb_registry/test_mongodb_x509_auth.py
+   ```
+
+## Support
+
+For issues with X.509 authentication:
+1. Check MongoDB Atlas documentation
+2. Verify certificate configuration with `test_mongodb_x509_auth.py`
+3. Review MongoDB connection logs in Atlas UI 

traia_iatp/registry/readmes/README.md

@@ -0,0 +1,251 @@
+# IATP Registry Module
+
+The IATP Registry provides a centralized database for discovering and managing:
+- **Utility Agents**: IATP-enabled AI agents exposed via the A2A protocol
+- **MCP Servers**: Model Context Protocol servers that can be wrapped as utility agents
+
+## Architecture
+
+The registry module has a layered architecture:
+
+```
+┌─────────────────────────────────────┐
+│     External Clients / Services      │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│      iatp_registry_api.py           │  ← High-level API (no MongoDB write dependency)
+│   (find_*, list_*, search_*)        │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│       mongodb_registry.py           │  ← MongoDB implementation
+│  (UtilityAgentRegistry, etc.)       │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│        MongoDB Atlas Cloud          │  ← Database backend
+└─────────────────────────────────────┘
+```
+
+## Authentication Methods
+
+The registry supports two authentication methods for MongoDB access, with the following priority:
+
+### 1. X.509 Certificate Authentication (Recommended) ⭐
+
+Use SSL/TLS certificates for authentication without passwords. Most secure option.
+
+```bash
+export MONGODB_X509_CERT_FILE=/path/to/certificate.pem
+```
+
+See [MONGODB_X509_AUTH.md](./MONGODB_X509_AUTH.md) for detailed setup instructions.
+
+### 2. Username/Password Authentication
+
+Traditional username/password authentication.
+
+```bash
+export MONGODB_USER=username
+export MONGODB_PASSWORD=password
+```
+
+You can also provide a full connection string:
+
+```bash
+export MONGODB_CONNECTION_STRING=mongodb+srv://user:pass@cluster.mongodb.net/...
+```
+
+## Quick Start
+
+### Using the High-Level API (No MongoDB Required)
+
+```python
+from traia_iatp.registry.iatp_search_api import find_utility_agent, list_mcp_servers
+
+# Find a specific utility agent
+agent = await find_utility_agent(name="trading-agent")
+
+# List available MCP servers
+servers = list_mcp_servers(limit=10)
+```
+
+### Direct MongoDB Access
+
+```python
+from traia_iatp.registry.mongodb_registry import UtilityAgentRegistry
+
+# Registry will automatically use configured authentication
+registry = UtilityAgentRegistry()
+
+# Query agents
+agents = await registry.query_agents(
+    query="trading",
+    tags=["finance"],
+    limit=10
+)
+```
+
+## Search Capabilities
+
+The registry supports multiple search methods:
+
+### 1. Text Search
+Basic MongoDB text search across indexed fields.
+
+```python
+agents = await registry.query_agents(query="trading bot")
+```
+
+### 2. Atlas Search
+Advanced full-text search using MongoDB Atlas Search.
+
+```python
+agents = await registry.atlas_search("AI trading assistant")
+```
+
+### 3. Vector Search
+Vector search uses OpenAI embeddings to find semantically similar agents:
+
+```python
+# By default, searches using the comprehensive search_text embedding (recommended)
+results = await registry.vector_search_text("trading bots", limit=5)
+
+# You can also search on specific embedding fields
+results = await registry.vector_search_text("defi", search_field="tags", limit=5)
+```
+
+The `search_text` field contains a concatenation of:
+- Agent name and description
+- All capabilities and tags
+- Agent card details (name, description)
+- All skill names, descriptions, examples, and tags
+
+This makes it ideal for comprehensive semantic search.
+
+## Environment Configuration
+
+### Required Settings
+
+- `ENV`: Environment name (`test`, `staging`, `prod`)
+- One of the authentication methods above
+
+### Optional Settings
+
+- `ENABLE_EMBEDDINGS`: Enable vector search (`true`/`false`, default: `true`)
+- `OPENAI_API_KEY`: Required if embeddings are enabled
+
+## Collections
+
+The registry uses environment-specific collections:
+
+- **Utility Agents**: `iatp-utility-agent-registry-{env}`
+- **MCP Servers**: `iatp-mcp-server-registry-{env}`
+
+## Indexes
+
+### Regular Indexes (Created Automatically)
+- `agent_id` (unique)
+- `name` (unique)
+- `base_url` (unique)
+- `is_active`
+- `tags`
+- `capabilities`
+- `registered_at`
+
+### Search Indexes (Create via Atlas UI)
+- Atlas Search indexes for full-text search
+- Vector Search indexes for semantic search
+
+See [atlas_search_indexes.json](./atlas_search_indexes.json) for index definitions.
+
+## Examples
+
+### Register a New Utility Agent
+
+```python
+from traia_iatp.core.models import UtilityAgent, AgentEndpoints
+
+agent = UtilityAgent(
+    name="My Trading Bot",
+    description="An AI agent for automated trading",
+    capabilities=["trade", "analyze", "report"],
+    endpoints=AgentEndpoints(
+        base_url="https://mybot.example.com"
+    )
+)
+
+registry = UtilityAgentRegistry()
+entry = await registry.add_utility_agent(agent)
+```
+
+### Search with Filters
+
+```python
+# Find agents with specific capabilities
+agents = await registry.query_agents(
+    capabilities=["trade", "analyze"],
+    tags=["crypto"],
+    active_only=True
+)
+```
+
+## Testing
+
+### Test Authentication
+
+```bash
+# Test X.509 certificate authentication
+uv run python tests/test_mongodb_registry/test_mongodb_x509_auth.py
+
+# Run general registry tests
+uv run python -m pytest tests/test_mongodb_registry/
+```
+
+### Example Scripts
+
+```bash
+# X.509 authentication example
+uv run python tests/test_mongodb_registry/example_x509_auth.py
+
+# IATP Registry API example
+uv run python tests/test_mongodb_registry/example_iatp_registry_api.py
+```
+
+## Security Best Practices
+
+1. **Use X.509 certificates** for production deployments
+2. **Rotate credentials** regularly
+3. **Use environment-specific** collections and credentials
+4. **Enable IP whitelisting** in MongoDB Atlas
+5. **Monitor access logs** for unauthorized attempts
+
+## Troubleshooting
+
+### Connection Issues
+
+1. Check authentication environment variables
+2. Verify MongoDB Atlas IP whitelist
+3. Test with `test_mongodb_x509_auth.py`
+
+### Search Not Working
+
+1. Ensure Atlas Search indexes are created
+2. Wait for index building to complete
+3. Check `ENABLE_EMBEDDINGS` setting
+
+### Certificate Authentication Failed
+
+1. Verify certificate file exists and is readable
+2. Check certificate user in `$external` database
+3. Ensure certificate hasn't expired
+
+## Related Documentation
+
+- [MONGODB_X509_AUTH.md](./MONGODB_X509_AUTH.md) - X.509 certificate setup
+- [ATLAS_SEARCH_SETUP.md](./ATLAS_SEARCH_SETUP.md) - Atlas Search configuration
+- [../api/README.md](../api/README.md) - REST API service