@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/reference-implementations/python-client/ossa_client/messaging.py

@@ -0,0 +1,227 @@
+"""
+OSSA Agent-to-Agent Messaging
+
+Client methods for A2A messaging, webhooks, and event streaming.
+"""
+
+from typing import Any, Dict, Iterator, List, Optional
+from .client import OSSAClient
+
+
+class MessagingClient:
+    """
+    Messaging operations client for A2A communication.
+    """
+
+    def __init__(self, client: OSSAClient):
+        self._client = client
+
+    def send_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Send an A2A message.
+
+        Args:
+            message: Message with from, to, type, capability, payload, and metadata
+
+        Returns:
+            Message ID and delivery status
+        """
+        return self._client.request('POST', '/messaging/send', body=message)
+
+    def send_request(self, message: Dict[str, Any], timeout: int = 30000) -> Dict[str, Any]:
+        """
+        Send a request and wait for response (synchronous-style).
+
+        Args:
+            message: Message (without 'type' field)
+            timeout: Timeout in milliseconds
+
+        Returns:
+            Request ID, response, and status
+        """
+        return self._client.request(
+            'POST',
+            '/messaging/request',
+            body={**message, 'timeout': timeout},
+        )
+
+    def get_message_status(self, message_id: str) -> Dict[str, Any]:
+        """
+        Get message status.
+
+        Args:
+            message_id: Message ID
+
+        Returns:
+            Message status and delivery information
+        """
+        return self._client.request('GET', f'/messaging/messages/{message_id}')
+
+    def broadcast(self, message: Dict[str, Any], filters: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Broadcast message to multiple agents.
+
+        Args:
+            message: Message to broadcast (without 'to' and 'type' fields)
+            filters: Recipient filters (domain, capability, tags)
+
+        Returns:
+            Broadcast ID and recipient count
+        """
+        return self._client.request(
+            'POST',
+            '/messaging/broadcast',
+            body={'message': message, 'filters': filters},
+        )
+
+    def register_webhook(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Register a webhook.
+
+        Args:
+            config: Webhook configuration (url, events, filters, headers, retry_config)
+
+        Returns:
+            Webhook ID and configuration
+        """
+        return self._client.request('POST', '/messaging/webhooks', body=config)
+
+    def list_webhooks(self) -> Dict[str, Any]:
+        """
+        List registered webhooks.
+
+        Returns:
+            List of webhooks with their configurations
+        """
+        return self._client.request('GET', '/messaging/webhooks')
+
+    def get_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        """
+        Get webhook details.
+
+        Args:
+            webhook_id: Webhook ID
+
+        Returns:
+            Webhook configuration and stats
+        """
+        return self._client.request('GET', f'/messaging/webhooks/{webhook_id}')
+
+    def update_webhook(self, webhook_id: str, config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update webhook configuration.
+
+        Args:
+            webhook_id: Webhook ID
+            config: Updated configuration
+
+        Returns:
+            Updated webhook configuration
+        """
+        return self._client.request('PUT', f'/messaging/webhooks/{webhook_id}', body=config)
+
+    def delete_webhook(self, webhook_id: str) -> None:
+        """
+        Delete webhook.
+
+        Args:
+            webhook_id: Webhook ID
+        """
+        self._client.request('DELETE', f'/messaging/webhooks/{webhook_id}')
+
+    def subscribe(self, subscription: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Subscribe to agent events.
+
+        Args:
+            subscription: Subscription config (agent, events, filters, delivery_mode, config)
+
+        Returns:
+            Subscription ID and status
+        """
+        return self._client.request('POST', '/messaging/subscriptions', body=subscription)
+
+    def list_subscriptions(self) -> Dict[str, Any]:
+        """
+        List event subscriptions.
+
+        Returns:
+            List of active subscriptions
+        """
+        return self._client.request('GET', '/messaging/subscriptions')
+
+    def poll_events(
+        self,
+        subscription_id: str,
+        limit: Optional[int] = None,
+        since: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Poll for events (for polling-mode subscriptions).
+
+        Args:
+            subscription_id: Subscription ID
+            limit: Maximum events to return
+            since: Return events since this cursor
+
+        Returns:
+            Events list and pagination info
+        """
+        query = {}
+        if limit:
+            query['limit'] = limit
+        if since:
+            query['since'] = since
+
+        return self._client.request('GET', f'/messaging/subscriptions/{subscription_id}/poll', query=query)
+
+    def stream_events(self, options: Optional[Dict[str, Any]] = None) -> Iterator[Dict[str, Any]]:
+        """
+        Stream events using Server-Sent Events (SSE).
+
+        Args:
+            options: Stream options (agent, event_types, from_timestamp, batch_size)
+
+        Yields:
+            Agent events as they arrive
+
+        Note:
+            This is a basic implementation. For production use, consider using
+            a dedicated SSE library like `sseclient-py`.
+        """
+        import json
+
+        params = {}
+        if options:
+            if 'agent' in options:
+                params['publisher'] = options['agent']['publisher']
+                params['name'] = options['agent']['name']
+            if 'event_types' in options:
+                params['events'] = ','.join(options['event_types'])
+            if 'from_timestamp' in options:
+                params['from'] = options['from_timestamp']
+            if 'batch_size' in options:
+                params['batch_size'] = options['batch_size']
+
+        url = self._client._build_url('/messaging/stream', params)
+        headers = self._client._build_headers()
+
+        import requests
+
+        response = requests.get(url, headers=headers, stream=True, timeout=None)
+        response.raise_for_status()
+
+        buffer = ''
+        for line in response.iter_lines(decode_unicode=True):
+            if line:
+                buffer += line + '\n'
+                if line.startswith('data: '):
+                    data = line[6:]
+                    if data == '[DONE]':
+                        return
+
+                    try:
+                        event = json.loads(data)
+                        yield event
+                    except json.JSONDecodeError:
+                        continue

package/examples/reference-implementations/python-client/requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+urllib3>=2.0.0

package/examples/reference-implementations/python-client/setup.py

@@ -0,0 +1,40 @@
+"""Setup configuration for OSSA Python client."""
+
+from setuptools import setup, find_packages
+
+with open('README.md', 'r', encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='ossa-client',
+    version='1.0.0',
+    description='Python reference implementation for OSSA API',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    author='OSSA Community',
+    author_email='registry@openstandardagents.org',
+    url='https://github.com/openstandardagents/ossa',
+    packages=find_packages(),
+    install_requires=[
+        'requests>=2.31.0',
+        'urllib3>=2.0.0',
+    ],
+    python_requires='>=3.8',
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: Apache Software License',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+    ],
+    keywords='ossa agents ai sdk',
+    project_urls={
+        'Documentation': 'https://docs.openstandardagents.org',
+        'Source': 'https://github.com/openstandardagents/ossa',
+        'Bug Reports': 'https://github.com/openstandardagents/ossa/issues',
+    },
+)

package/examples/reference-implementations/typescript-client/README.md

@@ -0,0 +1,227 @@
+# OSSA TypeScript Client
+
+TypeScript reference implementation for the OSSA (Open Standards for Scalable Agents) API.
+
+## Features
+
+- **Full Type Safety**: Complete TypeScript definitions for all API operations
+- **Agent Operations**: Search, publish, and manage agents
+- **Discovery**: Find agents by taxonomy, capabilities, and compliance
+- **A2A Messaging**: Agent-to-agent communication with webhooks and event streaming
+- **Error Handling**: Comprehensive error handling with retries and rate limiting
+- **Modern ES Modules**: Built with ES2022 modules
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Quick Start
+
+```typescript
+import { OSSA } from './src/index.js';
+
+// Initialize the client
+const client = new OSSA({
+  bearerToken: process.env.OSSA_TOKEN,
+});
+
+// Search for agents
+const results = await client.agents.search({
+  domain: 'security',
+  limit: 10,
+});
+
+// Get agent details
+const agent = await client.agents.get('blueflyio', 'security-scanner');
+
+// Send A2A message
+await client.messaging.sendMessage({
+  from: { publisher: 'myorg', name: 'my-agent' },
+  to: { publisher: 'blueflyio', name: 'security-scanner' },
+  type: 'request',
+  capability: 'vulnerability-scan',
+  payload: { target: 'https://example.com' },
+});
+```
+
+## Examples
+
+Run the included examples:
+
+```bash
+# Basic usage - search and get agent details
+npm run example
+
+# Search with various filters
+npm run example:search
+
+# Publish an agent (requires OSSA_TOKEN)
+export OSSA_TOKEN=ossa_tok_xxx
+npm run example:publish
+
+# A2A messaging and webhooks
+npm run example:messaging
+```
+
+## API Reference
+
+### Client Initialization
+
+```typescript
+const client = new OSSA({
+  baseUrl?: string;           // Default: https://registry.openstandardagents.org/api/v1
+  bearerToken?: string;       // Bearer token for authentication
+  apiKey?: string;            // Alternative: API key authentication
+  timeout?: number;           // Request timeout in ms (default: 30000)
+  retries?: number;           // Number of retries (default: 3)
+});
+```
+
+### Agent Operations
+
+```typescript
+// Search agents
+const results = await client.agents.search({
+  q?: string;                 // Full-text search
+  domain?: string;            // Filter by domain
+  capability?: string;        // Filter by capability
+  publisher?: string;         // Filter by publisher
+  verified?: boolean;         // Only verified publishers
+  min_rating?: number;        // Minimum rating (1-5)
+  sort?: 'downloads' | 'rating' | 'updated' | 'created';
+  limit?: number;             // Results per page (max 100)
+  offset?: number;            // Pagination offset
+});
+
+// Get agent details
+const agent = await client.agents.get(publisher, name);
+
+// Get specific version
+const version = await client.agents.getVersion(publisher, name, version);
+
+// List versions
+const versions = await client.agents.listVersions(publisher, name);
+
+// Publish agent
+const result = await client.agents.publish({
+  manifest: {...},
+  package: {
+    tarball_url: string,
+    shasum: string,
+    size_bytes: number,
+  },
+  license: string,
+  keywords?: string[],
+});
+
+// Get dependencies
+const deps = await client.agents.getDependencies(publisher, name, version);
+```
+
+### Discovery Operations
+
+```typescript
+// List taxonomies
+const taxonomies = await client.discovery.listTaxonomies();
+
+// List capabilities
+const capabilities = await client.discovery.listCapabilities(domain);
+
+// Discover by taxonomy
+const agents = await client.discovery.discoverByTaxonomy(
+  'security',
+  'vulnerability',
+  'vulnerability-detection'
+);
+
+// Get recommendations
+const recommendations = await client.discovery.getRecommendations({
+  use_case: 'Scan web apps for vulnerabilities',
+  requirements: {
+    compliance: ['fedramp-moderate'],
+    budget: '$100/month',
+  },
+  preferences: {
+    verified_only: true,
+    min_rating: 4.0,
+  },
+});
+```
+
+### Messaging Operations
+
+```typescript
+// Send A2A message
+const result = await client.messaging.sendMessage({
+  from: { publisher: string, name: string },
+  to: { publisher: string, name: string },
+  type: 'request' | 'response' | 'event' | 'broadcast',
+  capability: string,
+  payload: object,
+  metadata?: {
+    correlation_id?: string,
+    priority?: 'low' | 'normal' | 'high' | 'critical',
+    ttl?: number,
+  },
+});
+
+// Send synchronous request
+const response = await client.messaging.sendRequest(message, timeout);
+
+// Register webhook
+const webhook = await client.messaging.registerWebhook({
+  url: string,
+  events: string[],
+  filters?: object,
+  headers?: object,
+});
+
+// Stream events
+for await (const event of client.messaging.streamEvents({
+  agent: { publisher: 'blueflyio', name: 'security-scanner' },
+  event_types: ['scan.completed'],
+})) {
+  console.log('Event:', event);
+}
+```
+
+## Error Handling
+
+```typescript
+import { OSSAAPIError } from './src/index.js';
+
+try {
+  const agent = await client.agents.get('publisher', 'agent');
+} catch (error) {
+  if (error instanceof OSSAAPIError) {
+    console.error('API Error:', error.message);
+    console.error('Status:', error.statusCode);
+    console.error('Details:', error.apiError);
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+
+- `OSSA_TOKEN`: Bearer token for authentication
+- `OSSA_BASE_URL`: Override base API URL
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.3.0
+
+## License
+
+Apache-2.0
+
+## Resources
+
+- [OSSA Documentation](https://docs.openstandardagents.org)
+- [API Reference](https://registry.openstandardagents.org/docs)
+- [GitHub Repository](https://github.com/openstandardagents/ossa)

package/examples/reference-implementations/typescript-client/examples/basic-usage.ts

@@ -0,0 +1,86 @@
+/**
+ * Basic Usage Example
+ *
+ * Demonstrates basic OSSA SDK usage including:
+ * - Initializing the client
+ * - Searching for agents
+ * - Getting agent details
+ * - Listing agent versions
+ */
+
+import { OSSA } from '../src/index.js';
+
+async function main() {
+  // Initialize the OSSA client
+  const client = new OSSA({
+    // bearerToken: process.env.OSSA_TOKEN, // Uncomment for authenticated requests
+  });
+
+  console.log('🚀 OSSA TypeScript Client - Basic Usage Example\n');
+
+  try {
+    // 1. Search for security agents
+    console.log('1️⃣  Searching for security agents...');
+    const searchResults = await client.agents.search({
+      domain: 'security',
+      limit: 5,
+      sort: 'downloads',
+    });
+
+    console.log(`   Found ${searchResults.total} security agents\n`);
+    searchResults.agents.forEach((agent, i) => {
+      console.log(`   ${i + 1}. ${agent.publisher}/${agent.name} v${agent.version}`);
+      console.log(`      ${agent.description}`);
+      console.log(`      ⭐ ${agent.rating}/5 | 📥 ${agent.downloads} downloads\n`);
+    });
+
+    if (searchResults.agents.length === 0) {
+      console.log('   No agents found. Try different search criteria.\n');
+      return;
+    }
+
+    // 2. Get details for the first agent
+    const firstAgent = searchResults.agents[0];
+    console.log(`2️⃣  Getting details for ${firstAgent.publisher}/${firstAgent.name}...`);
+
+    const agentDetails = await client.agents.get(
+      firstAgent.publisher,
+      firstAgent.name
+    );
+
+    console.log(`   Agent: ${agentDetails.name}`);
+    console.log(`   Version: ${agentDetails.version}`);
+    console.log(`   Publisher: ${agentDetails.publisher} ${agentDetails.verified ? '✓' : ''}`);
+    console.log(`   License: ${agentDetails.license}`);
+    console.log(`   Taxonomy: ${agentDetails.taxonomy.domain} > ${agentDetails.taxonomy.subdomain || 'N/A'}`);
+    console.log(`   Capabilities: ${agentDetails.capabilities.join(', ')}`);
+    console.log(`   Downloads: ${agentDetails.download_stats.total} total, ${agentDetails.download_stats.last_month} this month`);
+    console.log(`   Rating: ${agentDetails.rating_info.average}/5 (${agentDetails.rating_info.count} reviews)\n`);
+
+    // 3. List available versions
+    console.log(`3️⃣  Listing versions for ${firstAgent.publisher}/${firstAgent.name}...`);
+    const versions = await client.agents.listVersions(
+      firstAgent.publisher,
+      firstAgent.name
+    );
+
+    console.log(`   Available versions (${versions.versions.length}):\n`);
+    versions.versions.slice(0, 5).forEach((version) => {
+      console.log(`   - v${version.version} (${new Date(version.published_at).toLocaleDateString()})`);
+      console.log(`     📥 ${version.downloads} downloads`);
+      if (version.deprecated) {
+        console.log(`     ⚠️  DEPRECATED: ${version.deprecation_reason}`);
+      }
+    });
+
+    console.log('\n✅ Basic usage example completed successfully!');
+  } catch (error) {
+    console.error('❌ Error:', error);
+    if (error instanceof Error) {
+      console.error('   Message:', error.message);
+    }
+    process.exit(1);
+  }
+}
+
+main();