@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/reference-implementations/README.md

@@ -0,0 +1,321 @@
+# OSSA API Reference Implementations
+
+Complete reference implementations demonstrating OSSA API usage in TypeScript, Python, and shell scripts.
+
+## Overview
+
+This directory contains production-ready reference implementations for the OSSA (Open Standards for Scalable Agents) API. Each implementation provides:
+
+- Complete API coverage (agents, discovery, messaging)
+- Working examples with real-world use cases
+- Error handling and retry logic
+- Authentication and rate limiting support
+- Comprehensive documentation
+
+## Implementations
+
+### [TypeScript Client](./typescript-client/)
+
+Modern TypeScript SDK with full type safety and ES modules.
+
+**Features:**
+- Complete TypeScript definitions
+- ES2022 modules
+- Fetch-based HTTP client
+- Event streaming with async iterators
+- Automatic retries and rate limiting
+
+**Quick Start:**
+```bash
+cd typescript-client
+npm install
+npm run build
+npm run example
+```
+
+**Use Case:** Production applications, web services, browser-based tools
+
+### [Python Client](./python-client/)
+
+Pythonic SDK with requests-based HTTP client.
+
+**Features:**
+- Clean, idiomatic Python API
+- Session management with connection pooling
+- Context manager support
+- Generator-based event streaming
+- Type hints for modern Python
+
+**Quick Start:**
+```bash
+cd python-client
+pip install -r requirements.txt
+python examples/basic_usage.py
+```
+
+**Use Case:** Data science, automation scripts, backend services
+
+### [cURL Scripts](./curl-scripts/)
+
+Standalone shell scripts for command-line usage and CI/CD pipelines.
+
+**Features:**
+- No dependencies except curl and jq
+- Easy to integrate in CI/CD
+- Standalone executable scripts
+- Error handling and validation
+- Environment variable configuration
+
+**Quick Start:**
+```bash
+cd curl-scripts
+./01-search-agents.sh
+```
+
+**Use Case:** CI/CD pipelines, debugging, quick testing
+
+## Common Functionality
+
+All implementations support:
+
+### Agent Operations
+
+- **Search & Discovery**: Find agents by domain, capability, compliance
+- **Agent Details**: Retrieve metadata, versions, dependencies
+- **Publishing**: Deploy new agents to the registry
+- **Lifecycle Management**: Deprecate, unpublish, version management
+- **Statistics**: Download counts, ratings, usage metrics
+
+### Discovery
+
+- **Taxonomies**: Browse domain/subdomain/capability hierarchy
+- **Capabilities**: Explore agent capabilities and schemas
+- **Compliance**: Find agents by compliance profiles (FedRAMP, HIPAA, SOC2)
+- **Recommendations**: AI-powered agent suggestions for use cases
+
+### Agent-to-Agent Messaging
+
+- **Direct Messaging**: Send messages between agents
+- **Synchronous Requests**: Request-response pattern with timeout
+- **Broadcasting**: Broadcast to multiple agents by filters
+- **Webhooks**: Register HTTP callbacks for events
+- **Event Streaming**: Real-time event streams (SSE)
+- **Subscriptions**: Subscribe to agent events
+
+## Authentication
+
+All implementations support authentication via Bearer token:
+
+```bash
+export OSSA_TOKEN=ossa_tok_xxx
+```
+
+Get a token:
+1. Visit https://registry.openstandardagents.org
+2. Sign in or create an account
+3. Navigate to Settings > API Tokens
+4. Generate a new token
+
+## API Endpoints
+
+**Base URL:** `https://registry.openstandardagents.org/api/v1`
+
+**Public Endpoints (No Auth):**
+- `GET /agents` - Search agents
+- `GET /agents/{publisher}/{name}` - Get agent
+- `GET /specification/taxonomies` - List taxonomies
+- `GET /specification/capabilities` - List capabilities
+
+**Authenticated Endpoints:**
+- `POST /agents` - Publish agent
+- `POST /messaging/send` - Send A2A message
+- `POST /messaging/webhooks` - Register webhook
+
+See individual implementation READMEs for complete endpoint lists.
+
+## Examples
+
+Each implementation includes working examples:
+
+### Basic Usage
+- Search for agents
+- Get agent details
+- List versions
+- View dependencies
+
+### Publishing
+- Create agent manifest
+- Package and publish
+- Handle verification
+
+### Messaging
+- Send A2A messages
+- Register webhooks
+- Subscribe to events
+- Stream events in real-time
+
+### Discovery
+- Browse taxonomies
+- Find by capabilities
+- Filter by compliance
+- Get AI recommendations
+
+## Rate Limits
+
+- **Authenticated**: 1000 requests/hour
+- **Unauthenticated**: 100 requests/hour
+
+Rate limit headers:
+- `X-RateLimit-Limit`: Total requests allowed
+- `X-RateLimit-Remaining`: Remaining requests
+- `X-RateLimit-Reset`: Unix timestamp when limit resets
+
+## Error Handling
+
+All implementations include robust error handling:
+
+**HTTP Status Codes:**
+- `200` - Success
+- `201` - Created
+- `204` - No Content
+- `400` - Bad Request
+- `401` - Unauthorized
+- `403` - Forbidden
+- `404` - Not Found
+- `409` - Conflict
+- `422` - Unprocessable Entity
+- `429` - Rate Limited
+- `500` - Internal Server Error
+
+**Error Response Format:**
+```json
+{
+  "error": "error_code",
+  "message": "Human-readable message",
+  "details": {},
+  "retry_after": 3600
+}
+```
+
+## Best Practices
+
+### 1. Always Use Authentication
+
+For production use, always authenticate with a Bearer token:
+```bash
+export OSSA_TOKEN=ossa_tok_xxx
+```
+
+### 2. Handle Rate Limiting
+
+Respect rate limits and implement exponential backoff:
+- Check `X-RateLimit-Remaining` header
+- Sleep based on `Retry-After` header on 429
+- Implement exponential backoff for retries
+
+### 3. Validate Manifests
+
+Before publishing, validate your agent manifest:
+```bash
+curl -X POST "${BASE_URL}/specification/validate" \
+  -H "Content-Type: application/json" \
+  -d @manifest.json
+```
+
+### 4. Monitor Message Status
+
+When sending A2A messages, poll for status:
+```bash
+MESSAGE_ID=$(curl ... | jq -r '.message_id')
+curl "${BASE_URL}/messaging/messages/${MESSAGE_ID}"
+```
+
+### 5. Use Webhooks for Events
+
+For production, use webhooks instead of polling:
+```bash
+curl -X POST "${BASE_URL}/messaging/webhooks" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -d '{"url": "https://your-app.com/webhook", "events": [...]}'
+```
+
+## Environment Variables
+
+Common environment variables:
+
+- `OSSA_TOKEN` - Bearer token for authentication
+- `OSSA_BASE_URL` - Override base API URL (default: production)
+- `OSSA_TIMEOUT` - Request timeout in seconds
+- `OSSA_RETRIES` - Number of retry attempts
+
+## Choosing an Implementation
+
+**Use TypeScript if:**
+- Building web applications or services
+- Need full type safety
+- Want modern async/await patterns
+- Deploying to Node.js or browsers
+
+**Use Python if:**
+- Writing automation scripts
+- Building data pipelines
+- Need integration with ML/AI tools
+- Prefer Pythonic APIs
+
+**Use cURL scripts if:**
+- Working in CI/CD pipelines
+- Need quick debugging
+- Want zero dependencies
+- Prefer shell scripting
+
+## Testing
+
+All implementations can be tested against:
+
+**Production Registry:**
+```bash
+export OSSA_BASE_URL=https://registry.openstandardagents.org/api/v1
+```
+
+**Staging Registry:**
+```bash
+export OSSA_BASE_URL=https://staging-registry.openstandardagents.org/api/v1
+```
+
+**Local Development:**
+```bash
+export OSSA_BASE_URL=http://localhost:3000
+```
+
+## Contributing
+
+To add a new reference implementation:
+
+1. Create a new directory (e.g., `go-client/`, `rust-client/`)
+2. Include:
+   - Client library source code
+   - Working examples
+   - README.md with usage instructions
+   - Package/dependency configuration
+3. Follow OSSA API spec v0.3.0
+4. Include error handling and retries
+5. Add authentication support
+
+## Resources
+
+- [OSSA Specification](https://openstandardagents.org/spec)
+- [API Documentation](https://docs.openstandardagents.org)
+- [Registry Web UI](https://registry.openstandardagents.org)
+- [GitHub Repository](https://github.com/openstandardagents/ossa)
+- [Community Discord](https://discord.gg/ossa)
+
+## License
+
+All reference implementations are licensed under Apache-2.0.
+
+## Support
+
+- **Documentation**: https://docs.openstandardagents.org
+- **Issues**: https://github.com/openstandardagents/ossa/issues
+- **Email**: registry@openstandardagents.org
+- **Discord**: https://discord.gg/ossa

package/examples/reference-implementations/curl-scripts/01-search-agents.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+#
+# OSSA API - Search Agents Example
+#
+# Demonstrates searching for agents using various filters.
+#
+
+set -e
+
+# Configuration
+BASE_URL="${OSSA_BASE_URL:-https://registry.openstandardagents.org/api/v1}"
+TOKEN="${OSSA_TOKEN:-}"
+
+echo "🔍 OSSA API - Search Agents Example"
+echo ""
+
+# 1. Search for security agents
+echo "1️⃣  Search for security agents..."
+curl -s "${BASE_URL}/agents?domain=security&limit=5&sort=downloads" \
+  -H "Accept: application/json" \
+  | jq '.agents[] | {name: .name, publisher: .publisher, version: .version, rating: .rating, downloads: .downloads}'
+
+echo ""
+
+# 2. Search with full-text query
+echo "2️⃣  Full-text search for 'vulnerability scanner'..."
+curl -s "${BASE_URL}/agents?q=vulnerability+scanner&limit=3" \
+  -H "Accept: application/json" \
+  | jq '.agents[] | {name: .name, description: .description}'
+
+echo ""
+
+# 3. Filter by capability
+echo "3️⃣  Filter by capability: vulnerability-detection..."
+curl -s "${BASE_URL}/agents?capability=vulnerability-detection&limit=3" \
+  -H "Accept: application/json" \
+  | jq '.agents[] | {name: .name, capabilities: .capabilities}'
+
+echo ""
+
+# 4. Filter by verified publishers only
+echo "4️⃣  Verified publishers only with minimum rating 4.0..."
+curl -s "${BASE_URL}/agents?verified=true&min_rating=4.0&limit=5" \
+  -H "Accept: application/json" \
+  | jq '.agents[] | {name: .name, publisher: .publisher, verified: .verified, rating: .rating}'
+
+echo ""
+
+# 5. Filter by compliance profile
+echo "5️⃣  Agents with FedRAMP moderate compliance..."
+curl -s "${BASE_URL}/agents?compliance=fedramp-moderate&limit=3" \
+  -H "Accept: application/json" \
+  | jq '.agents[] | {name: .name, compliance_profiles: .compliance_profiles}'
+
+echo ""
+
+# 6. Pagination example
+echo "6️⃣  Pagination - First page (10 results)..."
+curl -s "${BASE_URL}/agents?limit=10&offset=0" \
+  -H "Accept: application/json" \
+  | jq '{total: .total, limit: .limit, offset: .offset, count: (.agents | length)}'
+
+echo ""
+
+# 7. Combined filters
+echo "7️⃣  Combined filters: domain=security, license=Apache-2.0, min_rating=3.5..."
+curl -s "${BASE_URL}/agents?domain=security&license=Apache-2.0&min_rating=3.5" \
+  -H "Accept: application/json" \
+  | jq '.agents[] | {name: .name, license: .license, rating: .rating}'
+
+echo ""
+echo "✅ Search examples completed!"

package/examples/reference-implementations/curl-scripts/02-get-agent-details.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+#
+# OSSA API - Get Agent Details Example
+#
+# Demonstrates retrieving detailed information about agents.
+#
+
+set -e
+
+# Configuration
+BASE_URL="${OSSA_BASE_URL:-https://registry.openstandardagents.org/api/v1}"
+PUBLISHER="${1:-blueflyio}"
+AGENT_NAME="${2:-security-scanner}"
+
+echo "📋 OSSA API - Get Agent Details Example"
+echo ""
+
+# 1. Get latest version of agent
+echo "1️⃣  Get agent details: ${PUBLISHER}/${AGENT_NAME}..."
+curl -s "${BASE_URL}/agents/${PUBLISHER}/${AGENT_NAME}" \
+  -H "Accept: application/json" \
+  | jq '{
+      name: .name,
+      version: .version,
+      publisher: .publisher.name,
+      verified: .publisher.verified,
+      description: .description,
+      license: .license,
+      taxonomy: .taxonomy,
+      capabilities: .capabilities,
+      downloads: .download_stats,
+      rating: .rating_info
+    }'
+
+echo ""
+
+# 2. List all versions
+echo "2️⃣  List all versions of ${PUBLISHER}/${AGENT_NAME}..."
+curl -s "${BASE_URL}/agents/${PUBLISHER}/${AGENT_NAME}/versions" \
+  -H "Accept: application/json" \
+  | jq '.versions[] | {version: .version, published_at: .published_at, downloads: .downloads, deprecated: .deprecated}'
+
+echo ""
+
+# 3. Get specific version
+echo "3️⃣  Get specific version details..."
+VERSION=$(curl -s "${BASE_URL}/agents/${PUBLISHER}/${AGENT_NAME}/versions" \
+  -H "Accept: application/json" \
+  | jq -r '.versions[0].version')
+
+if [ -n "$VERSION" ]; then
+  curl -s "${BASE_URL}/agents/${PUBLISHER}/${AGENT_NAME}/${VERSION}" \
+    -H "Accept: application/json" \
+    | jq '{name: .name, version: .version, created_at: .created_at, manifest_url: .manifest_url}'
+fi
+
+echo ""
+
+# 4. Get agent dependencies
+echo "4️⃣  Get agent dependencies..."
+curl -s "${BASE_URL}/agents/${PUBLISHER}/${AGENT_NAME}/dependencies" \
+  -H "Accept: application/json" \
+  | jq '{agent: .agent, version: .version, dependencies: .dependencies}'
+
+echo ""
+
+# 5. Get download statistics
+echo "5️⃣  Get download statistics (last month)..."
+curl -s "${BASE_URL}/agents/${PUBLISHER}/${AGENT_NAME}/stats?period=month" \
+  -H "Accept: application/json" \
+  | jq '{agent: .agent, period: .period, downloads: .downloads.total}'
+
+echo ""
+echo "✅ Agent details examples completed!"

package/examples/reference-implementations/curl-scripts/03-publish-agent.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+#
+# OSSA API - Publish Agent Example
+#
+# Demonstrates publishing an agent to the registry.
+# Requires OSSA_TOKEN environment variable.
+#
+
+set -e
+
+# Configuration
+BASE_URL="${OSSA_BASE_URL:-https://registry.openstandardagents.org/api/v1}"
+TOKEN="${OSSA_TOKEN:-}"
+
+if [ -z "$TOKEN" ]; then
+  echo "❌ Error: OSSA_TOKEN environment variable is required"
+  echo "   Run: export OSSA_TOKEN=ossa_tok_xxx"
+  exit 1
+fi
+
+echo "📦 OSSA API - Publish Agent Example"
+echo ""
+
+# Prepare the publish request
+PUBLISH_REQUEST=$(cat <<'EOF'
+{
+  "manifest": {
+    "apiVersion": "ossa/v0.3.0",
+    "kind": "Agent",
+    "metadata": {
+      "name": "example-curl-agent",
+      "version": "1.0.0",
+      "description": "Example agent published via curl",
+      "labels": {
+        "environment": "production",
+        "team": "devops"
+      }
+    },
+    "spec": {
+      "taxonomy": {
+        "domain": "infrastructure",
+        "subdomain": "monitoring",
+        "capability": "health-check"
+      },
+      "role": "Infrastructure health monitoring agent",
+      "llm": {
+        "provider": "anthropic",
+        "model": "claude-sonnet-4",
+        "temperature": 0.3,
+        "maxTokens": 4000
+      },
+      "capabilities": [
+        {
+          "name": "check_health",
+          "description": "Perform health check on infrastructure",
+          "input_schema": {
+            "type": "object",
+            "required": ["target"],
+            "properties": {
+              "target": {
+                "type": "string",
+                "description": "Target URL or hostname"
+              }
+            }
+          },
+          "output_schema": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": ["healthy", "degraded", "unhealthy"]
+              },
+              "checks": {
+                "type": "array"
+              }
+            }
+          }
+        }
+      ],
+      "runtime": {
+        "type": "serverless",
+        "config": {
+          "timeout": 60,
+          "memory": "256Mi"
+        }
+      }
+    }
+  },
+  "package": {
+    "tarball_url": "https://example.com/agents/example-curl-agent-1.0.0.tgz",
+    "shasum": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "size_bytes": 102400
+  },
+  "documentation": {
+    "readme": "https://github.com/example/example-curl-agent#readme",
+    "repository": "https://github.com/example/example-curl-agent"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["monitoring", "health-check", "infrastructure"]
+}
+EOF
+)
+
+# Publish the agent
+echo "1️⃣  Publishing agent..."
+RESPONSE=$(curl -s -w "\n%{http_code}" "${BASE_URL}/agents" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "${PUBLISH_REQUEST}")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | head -n-1)
+
+if [ "$HTTP_CODE" -eq 201 ]; then
+  echo "✅ Agent published successfully!"
+  echo ""
+  echo "$BODY" | jq '{
+    status: .status,
+    agent: {
+      name: .agent.name,
+      version: .agent.version,
+      publisher: .agent.publisher,
+      published_at: .agent.published_at,
+      registry_url: .agent.registry_url
+    },
+    verification: .verification
+  }'
+else
+  echo "❌ Publishing failed with HTTP $HTTP_CODE"
+  echo "$BODY" | jq '.'
+  exit 1
+fi
+
+echo ""
+echo "✅ Publish example completed!"