Skip to content

Discovery Service

The Discovery Service is a centralized implementation of the Unified Intent Mediator (UIM) Protocol's discovery mechanism. It allows AI agents to discover web services and their intents through a centralized registry.

Overview

While the UIM Protocol supports decentralized discovery through DNS TXT records and agents.json files, a centralized discovery service can provide additional benefits such as search capabilities, curation, and analytics. The Discovery Service prototype demonstrates how such a centralized service can be implemented.

Features

  • Service Registration: Allows web services to register their intents and policies.
  • Intent Discovery: Provides a search API for AI agents to discover intents.
  • Service Verification: Verifies the authenticity of registered services.
  • Analytics: Tracks usage patterns and provides insights.
  • Curation: Curates high-quality services and intents.
  • Web Interface: Provides a web interface for browsing and managing services and intents.
  • API: Offers a comprehensive API for programmatic access.

Architecture

The Discovery Service is built with a modular architecture that separates concerns and promotes maintainability:

+------------------+
|   Web Interface  |
+------------------+
         |
+------------------+
|    API Layer     |
+------------------+
         |
+------------------+     +------------------+     +------------------+
| Registry Module  |     | Search Module    |     | Analytics Module |
+------------------+     +------------------+     +------------------+
         |                       |                        |
+------------------+     +------------------+     +------------------+
| Verification     |     | Curation         |     | Notification     |
| Module           |     | Module           |     | Module           |
+------------------+     +------------------+     +------------------+
         |                       |                        |
+------------------+
|  Data Storage    |
+------------------+

Components

  1. Web Interface: Provides a user interface for browsing and managing services and intents.
  2. API Layer: Handles HTTP requests and responses.
  3. Registry Module: Manages service and intent registration.
  4. Search Module: Provides search capabilities for discovering services and intents.
  5. Analytics Module: Tracks usage patterns and provides insights.
  6. Verification Module: Verifies the authenticity of registered services.
  7. Curation Module: Curates high-quality services and intents.
  8. Notification Module: Sends notifications about new services and intents.
  9. Data Storage: Manages persistent storage of services, intents, and other data.

Installation

Prerequisites

  • Python 3.8 or higher
  • pip (Python package manager)
  • MongoDB (for production deployments)

Steps

  1. Clone the repository: 

    git clone https://github.com/synaptiai/uim-protocol.git
cd uim-protocol/implementations/centralized-discovery-service

  2. Create a virtual environment: 

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies: 

    pip install -r requirements.txt

  4. Configure the service (see Configuration section).

  5. Initialize the database: 

    python manage.py init-db

  6. Start the service: 

    python manage.py runserver

Configuration

The Discovery Service can be configured using a configuration file or environment variables.

Configuration File

Create a file named .env in the service's directory:

# Server Configuration
HOST=localhost
PORT=5000
DEBUG=True

# Database Configuration
DB_TYPE=mongodb
DB_HOST=localhost
DB_PORT=27017
DB_NAME=uim_discovery
DB_USER=
DB_PASSWORD=

# Security Configuration
SECRET_KEY=your-secret-key
JWT_SECRET=your-jwt-secret
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin
ADMIN_EMAIL=admin@example.com

# Verification Configuration
VERIFY_SERVICES=True
VERIFICATION_TIMEOUT=30

# Curation Configuration
ENABLE_CURATION=True
AUTO_APPROVE_SERVICES=False

# Analytics Configuration
ENABLE_ANALYTICS=True
ANALYTICS_RETENTION_DAYS=90

# Notification Configuration
ENABLE_NOTIFICATIONS=True
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user@example.com
SMTP_PASSWORD=your-smtp-password
NOTIFICATION_FROM=noreply@example.com

Environment Variables

You can also use environment variables to configure the service. The environment variables have the same names as the keys in the .env file.

Usage

Accessing the Web Interface

Once the service is running, you can access the web interface at http://localhost:5000 (or the URL you configured).

The web interface provides:

  • A dashboard with service statistics
  • A list of registered services and intents
  • Search functionality
  • Service and intent details
  • Administration tools

API Endpoints

The Discovery Service provides the following API endpoints:

Service Endpoints

  • GET /api/services: Lists all registered services
  • GET /api/services/{service_id}: Returns details for a specific service
  • POST /api/services: Registers a new service
  • PUT /api/services/{service_id}: Updates a service
  • DELETE /api/services/{service_id}: Deletes a service

Intent Endpoints

  • GET /api/intents: Lists all registered intents
  • GET /api/intents/{intent_id}: Returns details for a specific intent
  • GET /api/intents/search: Searches for intents based on query parameters
  • POST /api/intents: Registers a new intent
  • PUT /api/intents/{intent_id}: Updates an intent
  • DELETE /api/intents/{intent_id}: Deletes an intent

Authentication Endpoints

  • POST /api/auth/login: Authenticates a user and returns a JWT
  • POST /api/auth/register: Registers a new user
  • POST /api/auth/refresh: Refreshes a JWT
  • POST /api/auth/logout: Logs out a user

Admin Endpoints

  • GET /api/admin/users: Lists all users
  • GET /api/admin/analytics: Returns analytics data
  • POST /api/admin/verify-service/{service_id}: Verifies a service
  • POST /api/admin/curate-intent/{intent_id}: Curates an intent

Service Registration

Web services can register with the Discovery Service using the API or the web interface.

API Registration

curl -X POST http://localhost:5000/api/services \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{
    "name": "E-commerce Service",
    "description": "A service for e-commerce operations",
    "url": "https://api.example.com",
    "logo_url": "https://example.com/logo.png",
    "terms_url": "https://example.com/terms",
    "privacy_url": "https://example.com/privacy",
    "policy_url": "https://example.com/uim-policy.json",
    "discovery_url": "https://api.example.com/uim/intents/search",
    "intents": [
      {
        "intent_uid": "example.com:searchProducts:v1",
        "intent_name": "SearchProducts",
        "description": "Search for products based on criteria",
        "input_parameters": [
          {"name": "query", "type": "string", "required": true},
          {"name": "category", "type": "string", "required": false},
          {"name": "price_range", "type": "string", "required": false},
          {"name": "sort_by", "type": "string", "required": false}
        ],
        "output_parameters": [
          {"name": "products", "type": "array"},
          {"name": "total_results", "type": "integer"}
        ],
        "endpoint": "https://api.example.com/products/search",
        "tags": ["e-commerce", "search", "products"]
      }
    ]
  }'

Web Interface Registration

  1. Log in to the web interface
  2. Navigate to the "Services" section
  3. Click "Register New Service"
  4. Fill out the service details
  5. Add intents
  6. Submit the registration

Intent Discovery

AI agents can discover intents using the API or the web interface.

API Discovery

curl -X GET "http://localhost:5000/api/intents/search?query=product&tags=e-commerce,search"

This will return a list of intents that match the query and tags.

Web Interface Discovery

  1. Navigate to the "Intents" section
  2. Use the search bar to search for intents
  3. Filter by tags, service, or other criteria
  4. View intent details

Deployment

The Discovery Service can be deployed in various environments:

Docker

A Dockerfile is provided for containerized deployment:

docker build -t uim-discovery-service .
docker run -p 5000:5000 uim-discovery-service

Docker Compose

A docker-compose.yml file is provided for multi-container deployment:

docker-compose up

Cloud Deployment

Instructions for deploying to various cloud platforms are available in the deployment directory.

Integration with UIM Protocol

The Discovery Service integrates with the UIM Protocol in the following ways:

For Web Services

Web services can register their intents and policies with the Discovery Service, making them discoverable by AI agents.

For AI Agents

AI agents can use the Discovery Service to find web services and intents that match their requirements.

Complementary to Decentralized Discovery

The Discovery Service complements the decentralized discovery mechanism of the UIM Protocol. AI agents can use both methods to discover services and intents.

Extending the Discovery Service

The Discovery Service is designed to be extensible. Here are some ways you can extend it:

Adding New Features

To add a new feature:

  1. Create a new module in the appropriate directory
  2. Implement the feature
  3. Register the module in the application

Adding Storage Backends

The Discovery Service supports different storage backends. To add a new one:

  1. Create a new file in the storage directory
  2. Implement the storage interface
  3. Register the storage backend in storage/__init__.py

Adding Authentication Methods

To add a new authentication method:

  1. Create a new file in the auth directory
  2. Implement the authentication interface
  3. Register the authentication method in auth/__init__.py

Testing

The Discovery Service includes a comprehensive test suite to ensure its functionality:

pytest

For more detailed test output:

pytest -v

To run specific tests:

pytest tests/test_registry.py

Troubleshooting

Common Issues

Server Won't Start

If the server won't start:

  1. Check that the port is not already in use
  2. Verify that the configuration file is valid
  3. Ensure that the database is running and accessible
  4. Check the logs for error messages

Registration Errors

If service registration is failing:

  1. Check that the service details are valid
  2. Verify that the service URL is accessible
  3. Ensure that the intents are properly formatted
  4. Check the logs for error messages

Search Errors

If intent search is failing:

  1. Check that the search parameters are valid
  2. Verify that the database is running and accessible
  3. Ensure that there are intents in the database
  4. Check the logs for error messages

Logging

The Discovery Service logs information to the console and to a log file. To change the log level:

export DEBUG=True
python manage.py runserver

Log files are stored in the logs directory.

Contributing

We welcome contributions to the Discovery Service! Please see the Contributing Guide for more information.

License

The Discovery Service is licensed under the Apache License 2.0. See the LICENSE file for details.