apia 0.1.0__py3-none-any.whl

apia/__init__.py

@@ -0,0 +1,27 @@
+"""
+APIA Python SDK
+~~~~~~~~~~~~~~~
+Python client for the APIA standard — AI-native API manifest discovery.
+
+    >>> from apia import Registry
+    >>> registry = Registry()
+    >>> apis = registry.find("send telegram message")
+    >>> print(apis[0].name)
+    'Telegram Bot'
+"""
+
+from .registry import Registry
+from .manifest import Manifest, Capability, Service, Auth
+from .exceptions import ApiaError, ManifestNotFoundError, RegistryError
+
+__version__ = "0.1.0"
+__all__ = [
+    "Registry",
+    "Manifest",
+    "Capability",
+    "Service",
+    "Auth",
+    "ApiaError",
+    "ManifestNotFoundError",
+    "RegistryError",
+]

apia/exceptions.py

@@ -0,0 +1,13 @@
+"""APIA exceptions."""
+
+
+class ApiaError(Exception):
+    """Base exception for all APIA errors."""
+
+
+class RegistryError(ApiaError):
+    """Raised when the registry cannot be loaded or is invalid."""
+
+
+class ManifestNotFoundError(ApiaError):
+    """Raised when a manifest cannot be found by the given id or criteria."""

apia/manifest.py

@@ -0,0 +1,196 @@
+"""Data models for APIA manifests."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Auth:
+    type: str
+    anonymous_access: bool
+    how_to_get: str = ""
+    cost: str = ""
+    header: str = ""
+    param_name: str = ""
+    param_location: str = ""
+    token_url: str = ""
+    note: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Auth":
+        return cls(
+            type=data.get("type", ""),
+            anonymous_access=data.get("anonymous_access", False),
+            how_to_get=data.get("how_to_get", ""),
+            cost=data.get("cost", ""),
+            header=data.get("header", ""),
+            param_name=data.get("param_name", ""),
+            param_location=data.get("param_location", ""),
+            token_url=data.get("token_url", ""),
+            note=data.get("note", ""),
+        )
+
+
+@dataclass
+class Service:
+    id: str
+    name: str
+    description_for_ai: str
+    category: str
+    geo: list[str]
+    language: str = "en"
+    url: str = ""
+    api_base: str = ""
+    docs: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Service":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description_for_ai=data.get("description_for_ai", ""),
+            category=data.get("category", ""),
+            geo=data.get("geo", []),
+            language=data.get("language", "en"),
+            url=data.get("url", ""),
+            api_base=data.get("api_base", ""),
+            docs=data.get("docs", ""),
+        )
+
+
+@dataclass
+class Capability:
+    id: str
+    description_for_ai: str
+    intent: list[str]
+    endpoint: str
+    input: dict[str, Any] = field(default_factory=dict)
+    output: dict[str, Any] = field(default_factory=dict)
+    realtime: bool = False
+    requires_auth: bool = True
+    rate_limit: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Capability":
+        return cls(
+            id=data.get("id", ""),
+            description_for_ai=data.get("description_for_ai", ""),
+            intent=data.get("intent", []),
+            endpoint=data.get("endpoint", ""),
+            input=data.get("input", {}),
+            output=data.get("output", {}),
+            realtime=data.get("realtime", False),
+            requires_auth=data.get("requires_auth", True),
+            rate_limit=data.get("rate_limit", ""),
+        )
+
+    def matches_intent(self, task: str) -> bool:
+        """Return True if any intent phrase matches the task string."""
+        task_lower = task.lower()
+        return any(
+            task_lower in phrase.lower() or phrase.lower() in task_lower
+            for phrase in self.intent
+        )
+
+    def to_openai_tool(self) -> dict[str, Any]:
+        """Convert this capability to an OpenAI function/tool definition."""
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        for name, spec in self.input.items():
+            if not isinstance(spec, dict):
+                continue
+            properties[name] = {
+                "type": spec.get("type", "string"),
+                "description": spec.get("description", ""),
+            }
+            if spec.get("enum"):
+                properties[name]["enum"] = spec["enum"]
+            if spec.get("required"):
+                required.append(name)
+        return {
+            "type": "function",
+            "function": {
+                "name": self.id,
+                "description": self.description_for_ai,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                },
+            },
+        }
+
+
+@dataclass
+class Manifest:
+    service: Service
+    auth: Auth
+    capabilities: list[Capability]
+    agent_hints: dict[str, str] = field(default_factory=dict)
+    apia_version: str = "1.0"
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    # Convenience aliases
+    @property
+    def id(self) -> str:
+        return self.service.id
+
+    @property
+    def name(self) -> str:
+        return self.service.name
+
+    @property
+    def category(self) -> str:
+        return self.service.category
+
+    @property
+    def geo(self) -> list[str]:
+        return self.service.geo
+
+    @property
+    def is_free(self) -> bool:
+        return self.auth.anonymous_access
+
+    def find_capability(self, task: str) -> Capability | None:
+        """Return the first capability whose intent matches the task."""
+        for cap in self.capabilities:
+            if cap.matches_intent(task):
+                return cap
+        return None
+
+    def to_system_prompt(self) -> str:
+        """Format this manifest as a system prompt section for an LLM."""
+        lines = [
+            f"## {self.service.name}",
+            f"{self.service.description_for_ai}",
+            f"Auth: {self.auth.type} | Cost: {self.auth.cost}",
+            f"Docs: {self.service.docs}",
+            "",
+            "### Capabilities",
+        ]
+        for cap in self.capabilities:
+            lines.append(f"**[{cap.id}]** `{cap.endpoint}`")
+            lines.append(f"When: {cap.description_for_ai}")
+            lines.append(f"Intent: {', '.join(cap.intent[:5])}")
+            lines.append("")
+        if self.agent_hints:
+            lines.append("### Hints")
+            for k, v in self.agent_hints.items():
+                lines.append(f"- **{k}**: {v}")
+        return "\n".join(lines)
+
+    def to_openai_tools(self) -> list[dict[str, Any]]:
+        """Convert all capabilities to OpenAI tool definitions."""
+        return [cap.to_openai_tool() for cap in self.capabilities]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Manifest":
+        return cls(
+            service=Service.from_dict(data.get("service", {})),
+            auth=Auth.from_dict(data.get("auth", {})),
+            capabilities=[Capability.from_dict(c) for c in data.get("capabilities", [])],
+            agent_hints=data.get("agent_hints", {}),
+            apia_version=data.get("apia", "1.0"),
+            raw=data,
+        )

apia/registry.py

@@ -0,0 +1,176 @@
+"""
+APIA Registry — loads and searches the manifest index.
+"""
+
+from __future__ import annotations
+import json
+from typing import Any
+import httpx
+
+from .manifest import Manifest
+from .exceptions import RegistryError, ManifestNotFoundError
+
+REGISTRY_URL = (
+    "https://raw.githubusercontent.com/Komsomol39/apia-standard/main/registry.json"
+)
+MANIFEST_BASE_URL = (
+    "https://raw.githubusercontent.com/Komsomol39/apia-standard/main/manifests"
+)
+
+
+class Registry:
+    """
+    APIA manifest registry.
+
+    Usage::
+
+        registry = Registry()
+        apis = registry.find("send telegram message")
+        manifest = registry.get("telegram-bot")
+        tools = manifest.to_openai_tools()
+        prompt = manifest.to_system_prompt()
+    """
+
+    def __init__(self, registry_url: str = REGISTRY_URL) -> None:
+        self._url = registry_url
+        self._index: list[dict[str, Any]] = []
+        self._cache: dict[str, Manifest] = {}
+
+    def _ensure_loaded(self) -> None:
+        if self._index:
+            return
+        try:
+            response = httpx.get(self._url, timeout=15.0)
+            response.raise_for_status()
+            data = response.json()
+            self._index = data.get("manifests", [])
+        except Exception as exc:
+            raise RegistryError(f"Failed to load APIA registry: {exc}") from exc
+
+    def list(
+        self,
+        category: str | None = None,
+        geo: str | None = None,
+        free_only: bool = False,
+        language: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        List registry entries with optional filters.
+
+        :param category: One of the 26 APIA categories e.g. "ai", "finance", "maps".
+        :param geo: ISO country code or "GLOBAL" e.g. "RU", "US", "GLOBAL".
+        :param free_only: Only return APIs with anonymous_access=True.
+        :param language: Primary language e.g. "ru", "en".
+        :returns: List of lightweight registry entries (not full manifests).
+        """
+        self._ensure_loaded()
+        results = self._index
+        if category:
+            results = [m for m in results if m.get("category") == category]
+        if geo:
+            results = [m for m in results if geo in m.get("geo", []) or "GLOBAL" in m.get("geo", [])]
+        if free_only:
+            results = [m for m in results if m.get("anonymous_access")]
+        if language:
+            results = [m for m in results if m.get("language") == language]
+        return results
+
+    def categories(self) -> dict[str, int]:
+        """Return a dict of {category: count} for all manifests."""
+        self._ensure_loaded()
+        from collections import Counter
+        return dict(Counter(m.get("category", "") for m in self._index))
+
+    def find(
+        self,
+        task: str,
+        category: str | None = None,
+        geo: str | None = None,
+        top_k: int = 3,
+    ) -> list[Manifest]:
+        """
+        Find the most relevant APIs for a natural language task.
+
+        Searches intent phrases in capabilities. Returns full Manifest objects.
+
+        :param task: Natural language description e.g. "send a telegram message".
+        :param category: Narrow to a specific category.
+        :param geo: Narrow to a specific geography.
+        :param top_k: Maximum number of results.
+        :returns: List of Manifest objects sorted by relevance.
+        """
+        self._ensure_loaded()
+        task_lower = task.lower()
+        scored: list[tuple[int, dict[str, Any]]] = []
+
+        candidates = self._index
+        if category:
+            candidates = [m for m in candidates if m.get("category") == category]
+        if geo:
+            candidates = [m for m in candidates if geo in m.get("geo", []) or "GLOBAL" in m.get("geo", [])]
+
+        for entry in candidates:
+            score = 0
+            # Match description
+            if any(w in entry.get("description_for_ai", "").lower() for w in task_lower.split()):
+                score += 1
+            # Match capability intents (stronger signal)
+            for cap in entry.get("capabilities", []):
+                for intent in cap.get("intent", []):
+                    if task_lower in intent.lower() or intent.lower() in task_lower:
+                        score += 3
+                        break
+            if score > 0:
+                scored.append((score, entry))
+
+        scored.sort(key=lambda x: -x[0])
+        top_entries = [e for _, e in scored[:top_k]]
+
+        # Load full manifests for top results
+        return [self.get(e["id"]) for e in top_entries]
+
+    def get(self, api_id: str) -> Manifest:
+        """
+        Load a full manifest by API id.
+
+        :param api_id: The manifest id e.g. "openai", "telegram-bot", "stripe".
+        :raises ManifestNotFoundError: If the manifest cannot be found.
+        :returns: Full Manifest object.
+        """
+        if api_id in self._cache:
+            return self._cache[api_id]
+        url = f"{MANIFEST_BASE_URL}/{api_id}/apia.json"
+        try:
+            response = httpx.get(url, timeout=10.0)
+            if response.status_code == 404:
+                raise ManifestNotFoundError(f"Manifest not found: {api_id!r}")
+            response.raise_for_status()
+            manifest = Manifest.from_dict(response.json())
+            self._cache[api_id] = manifest
+            return manifest
+        except ManifestNotFoundError:
+            raise
+        except Exception as exc:
+            raise RegistryError(f"Failed to load manifest {api_id!r}: {exc}") from exc
+
+    def build_system_prompt(
+        self,
+        apis: list[Manifest],
+        header: str = "You are an AI agent with access to the following APIs:",
+    ) -> str:
+        """
+        Build a system prompt containing multiple API manifests.
+
+        :param apis: List of Manifest objects to include.
+        :param header: Opening sentence for the system prompt.
+        :returns: Complete system prompt string ready to pass to an LLM.
+        """
+        parts = [header, ""]
+        for manifest in apis:
+            parts.append(manifest.to_system_prompt())
+            parts.append("---")
+        parts.append(
+            "\nWhen the user asks something, identify which API and capability to use, "
+            "explain your reasoning, and provide the exact API call."
+        )
+        return "\n".join(parts)

apia-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: apia
+Version: 0.1.0
+Summary: Python SDK for APIA — AI-native API manifests standard
+Project-URL: Homepage, https://github.com/Komsomol39/apia-standard
+Project-URL: Repository, https://github.com/Komsomol39/apia-py
+Project-URL: Issues, https://github.com/Komsomol39/apia-py/issues
+Author: APIA Community
+License: MIT
+Keywords: agents,ai,api,apia,llm,manifests
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# apia-py
+
+Python SDK for [APIA](https://github.com/Komsomol39/apia-standard) — the open standard for AI-native API manifests.
+
+```bash
+pip install apia
+```
+
+## Quickstart
+
+```python
+from apia import Registry
+
+registry = Registry()
+
+# Find APIs for a task
+apis = registry.find("send a telegram message")
+print(apis[0].name)        # → Telegram Bot API
+print(apis[0].category)    # → social
+
+# Get a specific manifest
+manifest = registry.get("stripe")
+print(manifest.service.description_for_ai)
+
+# Convert to OpenAI tools
+tools = manifest.to_openai_tools()
+
+# Build a system prompt for an LLM
+prompt = registry.build_system_prompt(apis)
+```
+
+## Core API
+
+### `Registry`
+
+```python
+from apia import Registry
+
+r = Registry()
+
+# Search by intent (natural language)
+r.find("track DHL package")              # → [Manifest, ...]
+r.find("crypto price", category="finance") # → filtered
+
+# Load a specific manifest
+r.get("openai")                          # → Manifest
+
+# List with filters
+r.list(category="ai")                    # all AI APIs
+r.list(geo="RU", free_only=True)        # free Russian APIs
+r.list(language="ru")                    # Russian-language APIs
+
+# Categories overview
+r.categories()                           # → {"ai": 25, "finance": 17, ...}
+
+# Build LLM system prompt from multiple manifests
+prompt = r.build_system_prompt(apis)
+```
+
+### `Manifest`
+
+```python
+m = r.get("stripe")
+
+m.id                     # "stripe"
+m.name                   # "Stripe"
+m.category               # "finance"
+m.geo                    # ["GLOBAL"]
+m.is_free                # False
+
+# Find capability by task
+cap = m.find_capability("charge a customer")
+cap.id                   # "create_payment_intent"
+cap.endpoint             # "POST https://api.stripe.com/v1/payment_intents"
+
+# Export
+m.to_openai_tools()      # list of OpenAI function definitions
+m.to_system_prompt()     # formatted string for LLM system prompt
+```
+
+## Use with LLMs
+
+### Anthropic Claude
+
+```python
+from apia import Registry
+import anthropic
+
+r = Registry()
+apis = r.find("send telegram message")
+system = r.build_system_prompt(apis)
+
+client = anthropic.Anthropic()
+response = client.messages.create(
+    model="claude-haiku-4-5",
+    max_tokens=1024,
+    system=system,
+    messages=[{"role": "user", "content": "Send 'Hello!' to chat 123456"}]
+)
+print(response.content[0].text)
+```
+
+### OpenAI function calling
+
+```python
+from apia import Registry
+import openai
+
+r = Registry()
+manifest = r.get("openweathermap")
+tools = manifest.to_openai_tools()
+
+client = openai.OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+    tools=tools,
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/Komsomol39/apia-py
+cd apia-py
+pip install -e ".[dev]"
+pytest
+```
+
+## Related
+
+- [apia-standard](https://github.com/Komsomol39/apia-standard) — manifest registry (257 APIs)
+- [apia-js](https://github.com/Komsomol39/apia-js) — JavaScript/TypeScript SDK
+
+## License
+
+MIT

apia-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+apia/__init__.py,sha256=-aC12FBNJ8tjje_W6hobrHfVsgIgIfDZCnUQxcX3BFM,623
+apia/exceptions.py,sha256=Xp2pnG93NtagVViz0lDLQZcTjBjvVG0g7TjYPxc3BIw,320
+apia/manifest.py,sha256=HUqoTR_kPXddA3BnpbumBL6bGC4-brgWhM9Zm7mIydU,6176
+apia/registry.py,sha256=6ZCJlZrjZIW9XLdi2wAkAxPn3d6KhFa-xI8iL9qzRgc,6324
+apia-0.1.0.dist-info/METADATA,sha256=1votxv_t7bbArMALlTfkpPXKAz-DlpUbEsi8Y22z_GQ,4231
+apia-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+apia-0.1.0.dist-info/RECORD,,

apia-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any