@bluefly/openstandardagents 0.2.8 → 0.3.0

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

@@ -0,0 +1,240 @@
+"""
+OSSA Agent Operations
+
+Client methods for agent discovery, publishing, and lifecycle management.
+"""
+
+from typing import Any, Dict, List, Optional
+from .client import OSSAClient
+
+
+class AgentClient:
+    """
+    Agent operations client for OSSA registry.
+
+    Provides methods for searching, publishing, and managing agents.
+    """
+
+    def __init__(self, client: OSSAClient):
+        self._client = client
+
+    def search(
+        self,
+        q: Optional[str] = None,
+        tag: Optional[str] = None,
+        capability: Optional[str] = None,
+        domain: Optional[str] = None,
+        publisher: Optional[str] = None,
+        license: Optional[str] = None,
+        compliance: Optional[str] = None,
+        verified: Optional[bool] = None,
+        min_rating: Optional[float] = None,
+        sort: str = 'relevance',
+        limit: int = 20,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """
+        Search and list agents.
+
+        Args:
+            q: Full-text search query
+            tag: Filter by tag
+            capability: Filter by capability
+            domain: Filter by domain
+            publisher: Filter by publisher
+            license: Filter by license (SPDX identifier)
+            compliance: Filter by compliance profile
+            verified: Only verified publishers
+            min_rating: Minimum rating (1-5)
+            sort: Sort order (downloads, rating, updated, created, relevance)
+            limit: Results per page (max 100)
+            offset: Pagination offset
+
+        Returns:
+            Search results with agents list and metadata
+        """
+        return self._client.request(
+            'GET',
+            '/agents',
+            query={
+                'q': q,
+                'tag': tag,
+                'capability': capability,
+                'domain': domain,
+                'publisher': publisher,
+                'license': license,
+                'compliance': compliance,
+                'verified': verified,
+                'min_rating': min_rating,
+                'sort': sort,
+                'limit': limit,
+                'offset': offset,
+            },
+        )
+
+    def publish(
+        self,
+        manifest: Dict[str, Any],
+        package: Dict[str, Any],
+        license: str,
+        documentation: Optional[Dict[str, str]] = None,
+        keywords: Optional[List[str]] = None,
+        dependencies: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Publish a new agent or version.
+
+        Args:
+            manifest: OSSA agent manifest
+            package: Package information (tarball_url, shasum, size_bytes)
+            license: SPDX license identifier
+            documentation: Documentation URLs (readme, changelog, repository)
+            keywords: Agent keywords (max 20)
+            dependencies: Agent dependencies
+
+        Returns:
+            Publish response with status and verification info
+        """
+        return self._client.request(
+            'POST',
+            '/agents',
+            body={
+                'manifest': manifest,
+                'package': package,
+                'license': license,
+                'documentation': documentation,
+                'keywords': keywords,
+                'dependencies': dependencies,
+            },
+        )
+
+    def get(self, publisher: str, name: str) -> Dict[str, Any]:
+        """
+        Get agent details (latest version).
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+
+        Returns:
+            Agent details including metadata, stats, and versions
+        """
+        return self._client.request('GET', f'/agents/{publisher}/{name}')
+
+    def get_version(self, publisher: str, name: str, version: str) -> Dict[str, Any]:
+        """
+        Get specific agent version.
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+            version: Semantic version
+
+        Returns:
+            Agent version details
+        """
+        return self._client.request('GET', f'/agents/{publisher}/{name}/{version}')
+
+    def list_versions(self, publisher: str, name: str) -> Dict[str, Any]:
+        """
+        List all versions of an agent.
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+
+        Returns:
+            List of agent versions with metadata
+        """
+        return self._client.request('GET', f'/agents/{publisher}/{name}/versions')
+
+    def unpublish(
+        self,
+        publisher: str,
+        name: str,
+        version: str,
+        reason: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Unpublish a specific agent version.
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+            version: Semantic version
+            reason: Reason for unpublishing
+
+        Returns:
+            Unpublish confirmation
+        """
+        body = {'reason': reason} if reason else None
+        return self._client.request('DELETE', f'/agents/{publisher}/{name}/{version}', body=body)
+
+    def deprecate(
+        self,
+        publisher: str,
+        name: str,
+        version: str,
+        reason: str,
+        replacement_version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Deprecate a specific agent version.
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+            version: Semantic version to deprecate
+            reason: Reason for deprecation
+            replacement_version: Recommended replacement version
+
+        Returns:
+            Deprecation confirmation
+        """
+        return self._client.request(
+            'POST',
+            f'/agents/{publisher}/{name}/{version}/deprecate',
+            body={
+                'reason': reason,
+                'replacement_version': replacement_version,
+            },
+        )
+
+    def get_dependencies(
+        self,
+        publisher: str,
+        name: str,
+        version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get agent dependencies.
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+            version: Specific version (default: latest)
+
+        Returns:
+            Dependencies with version resolution and dependency tree
+        """
+        query = {'version': version} if version else None
+        return self._client.request('GET', f'/agents/{publisher}/{name}/dependencies', query=query)
+
+    def get_stats(
+        self,
+        publisher: str,
+        name: str,
+        period: str = 'all',
+    ) -> Dict[str, Any]:
+        """
+        Get agent download and usage statistics.
+
+        Args:
+            publisher: Publisher identifier
+            name: Agent name
+            period: Time period (day, week, month, year, all)
+
+        Returns:
+            Statistics including downloads and installs
+        """
+        return self._client.request('GET', f'/agents/{publisher}/{name}/stats', query={'period': period})

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

@@ -0,0 +1,164 @@
+"""
+OSSA API Client
+
+Main client for interacting with the OSSA registry and core API.
+Provides authentication, request handling, and error management.
+"""
+
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import urljoin, urlencode
+
+import requests
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
+
+
+class OSSAAPIError(Exception):
+    """Exception raised for OSSA API errors."""
+
+    def __init__(self, message: str, status_code: int, api_error: Dict[str, Any]):
+        super().__init__(message)
+        self.status_code = status_code
+        self.api_error = api_error
+
+
+class OSSAClient:
+    """
+    Low-level HTTP client for OSSA API.
+
+    Handles authentication, retries, rate limiting, and error handling.
+    """
+
+    def __init__(
+        self,
+        base_url: str = 'https://registry.openstandardagents.org/api/v1',
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        timeout: int = 30,
+        retries: int = 3,
+    ):
+        self.base_url = base_url.rstrip('/')
+        self.api_key = api_key
+        self.bearer_token = bearer_token
+        self.timeout = timeout
+        self.retries = retries
+
+        # Configure session with retry strategy
+        self.session = requests.Session()
+
+        retry_strategy = Retry(
+            total=retries,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=['GET', 'POST', 'PUT', 'DELETE'],
+        )
+
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount('http://', adapter)
+        self.session.mount('https://', adapter)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """
+        Make an authenticated API request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API endpoint path
+            body: Request body (will be JSON encoded)
+            query: Query parameters
+            headers: Additional headers
+
+        Returns:
+            Response data (parsed JSON or None for 204)
+
+        Raises:
+            OSSAAPIError: If the request fails
+        """
+        url = self._build_url(path, query)
+        request_headers = self._build_headers(headers)
+
+        for attempt in range(self.retries + 1):
+            try:
+                response = self.session.request(
+                    method=method,
+                    url=url,
+                    json=body,
+                    headers=request_headers,
+                    timeout=self.timeout,
+                )
+
+                # Handle rate limiting
+                if response.status_code == 429:
+                    retry_after = int(response.headers.get('Retry-After', 60))
+                    if attempt < self.retries:
+                        time.sleep(retry_after)
+                        continue
+
+                if not response.ok:
+                    error_data = response.json() if response.content else {}
+                    raise OSSAAPIError(
+                        error_data.get('message', f'HTTP {response.status_code}'),
+                        response.status_code,
+                        error_data,
+                    )
+
+                # Handle 204 No Content
+                if response.status_code == 204:
+                    return None
+
+                return response.json()
+
+            except requests.RequestException as e:
+                if attempt < self.retries:
+                    time.sleep(2**attempt)  # Exponential backoff
+                    continue
+                raise OSSAAPIError(str(e), 0, {'error': 'request_failed', 'message': str(e)})
+
+        raise OSSAAPIError('Request failed after retries', 0, {'error': 'max_retries_exceeded'})
+
+    def _build_url(self, path: str, query: Optional[Dict[str, Any]] = None) -> str:
+        """Build full URL with query parameters."""
+        url = urljoin(self.base_url, path.lstrip('/'))
+
+        if query:
+            # Filter out None values
+            filtered_query = {k: v for k, v in query.items() if v is not None}
+            if filtered_query:
+                url = f"{url}?{urlencode(filtered_query)}"
+
+        return url
+
+    def _build_headers(self, custom_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """Build request headers with authentication."""
+        headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'ossa-python-client/1.0.0',
+        }
+
+        if custom_headers:
+            headers.update(custom_headers)
+
+        if self.bearer_token:
+            headers['Authorization'] = f'Bearer {self.bearer_token}'
+        elif self.api_key:
+            headers['X-API-Key'] = self.api_key
+
+        return headers
+
+    def close(self):
+        """Close the session and cleanup resources."""
+        self.session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

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

@@ -0,0 +1,153 @@
+"""
+OSSA Discovery Operations
+
+Client methods for discovering agents by taxonomy, capabilities, and compliance.
+"""
+
+from typing import Any, Dict, List, Optional
+from .client import OSSAClient
+
+
+class DiscoveryClient:
+    """
+    Discovery operations client for finding agents by various criteria.
+    """
+
+    def __init__(self, client: OSSAClient):
+        self._client = client
+
+    def list_taxonomies(self) -> Dict[str, Any]:
+        """
+        List available agent taxonomies.
+
+        Returns:
+            Available taxonomies with domains, subdomains, and capabilities
+        """
+        return self._client.request('GET', '/specification/taxonomies')
+
+    def list_capabilities(self, domain: Optional[str] = None) -> Dict[str, Any]:
+        """
+        List available capabilities.
+
+        Args:
+            domain: Filter by domain
+
+        Returns:
+            Available capabilities with definitions and examples
+        """
+        query = {'domain': domain} if domain else None
+        return self._client.request('GET', '/specification/capabilities', query=query)
+
+    def get_capability(self, capability_name: str) -> Dict[str, Any]:
+        """
+        Get capability definition.
+
+        Args:
+            capability_name: Capability name
+
+        Returns:
+            Capability definition with schema and example agents
+        """
+        return self._client.request('GET', f'/specification/capabilities/{capability_name}')
+
+    def list_compliance_profiles(self) -> Dict[str, Any]:
+        """
+        List available compliance profiles.
+
+        Returns:
+            Available compliance profiles (FedRAMP, HIPAA, SOC2, etc.)
+        """
+        return self._client.request('GET', '/specification/compliance')
+
+    def get_compliance_profile(self, profile_id: str) -> Dict[str, Any]:
+        """
+        Get compliance profile details.
+
+        Args:
+            profile_id: Compliance profile ID
+
+        Returns:
+            Compliance profile requirements and agent count
+        """
+        return self._client.request('GET', f'/specification/compliance/{profile_id}')
+
+    def discover_by_taxonomy(
+        self,
+        domain: str,
+        subdomain: Optional[str] = None,
+        capability: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Discover agents by taxonomy.
+
+        Args:
+            domain: Taxonomy domain
+            subdomain: Taxonomy subdomain (optional)
+            capability: Specific capability (optional)
+
+        Returns:
+            Agents matching the taxonomy criteria
+        """
+        query = {'domain': domain}
+        if subdomain:
+            query['subdomain'] = subdomain
+        if capability:
+            query['capability'] = capability
+
+        return self._client.request('GET', '/agents/discover/taxonomy', query=query)
+
+    def discover_by_compliance(self, profiles: List[str]) -> Dict[str, Any]:
+        """
+        Discover agents by compliance requirements.
+
+        Args:
+            profiles: List of compliance profile IDs
+
+        Returns:
+            Agents matching the compliance requirements
+        """
+        return self._client.request(
+            'GET',
+            '/agents/discover/compliance',
+            query={'profiles': ','.join(profiles)},
+        )
+
+    def get_recommendations(
+        self,
+        use_case: str,
+        requirements: Optional[Dict[str, Any]] = None,
+        preferences: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get agent recommendations based on use case.
+
+        Args:
+            use_case: Description of the use case
+            requirements: Requirements (compliance, budget, performance, integration)
+            preferences: Preferences (verified_only, open_source_only, min_rating)
+
+        Returns:
+            Recommended agents with scores and reasoning
+        """
+        return self._client.request(
+            'POST',
+            '/agents/recommend',
+            body={
+                'use_case': use_case,
+                'requirements': requirements,
+                'preferences': preferences,
+            },
+        )
+
+    def discover(self, filters: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Advanced discovery with multiple filters.
+
+        Args:
+            filters: Discovery filters (domain, subdomain, capability, compliance,
+                    min_rating, verified_only, has_dependencies, license)
+
+        Returns:
+            Agents matching all filter criteria
+        """
+        return self._client.request('POST', '/agents/discover', body=filters)