apia 0.1.0__tar.gz

apia-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest --tb=short -q

apia-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write   # нужен для trusted publishing (без API токена)
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload dist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/apia/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Trusted Publishing — не нужен API токен
+        # Настроить в PyPI: pypi.org → Account → Publishing
+        # Publisher: GitHub Actions, repo: Komsomol39/apia-py, workflow: publish.yml

apia-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg
+MANIFEST

apia-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,137 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apia"
+version = "0.1.0"
+description = "Python SDK for APIA — AI-native API manifests standard"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "APIA Community" }]
+keywords = ["apia", "api", "ai", "agents", "llm", "manifests"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "ruff", "mypy"]
+
+[project.urls]
+Homepage = "https://github.com/Komsomol39/apia-standard"
+Repository = "https://github.com/Komsomol39/apia-py"
+Issues = "https://github.com/Komsomol39/apia-py/issues"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+strict = true

apia-0.1.0/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths = tests
+asyncio_mode = auto

apia-0.1.0/tests/test_apia.py

@@ -0,0 +1,198 @@
+"""Tests for apia Python SDK."""
+import pytest
+from unittest.mock import patch, MagicMock
+from apia import Registry, Manifest, Capability, Service, Auth
+from apia.exceptions import ManifestNotFoundError, RegistryError
+
+# ── Fixtures ────────────────────────────────────────────────────────────────
+
+SAMPLE_MANIFEST = {
+    "apia": "1.0",
+    "service": {
+        "id": "telegram-bot",
+        "name": "Telegram Bot API",
+        "description_for_ai": "Send messages via Telegram. 950M users.",
+        "category": "social",
+        "geo": ["GLOBAL"],
+        "language": "en",
+        "url": "https://telegram.org",
+        "api_base": "https://api.telegram.org/bot{token}",
+        "docs": "https://core.telegram.org/bots/api",
+    },
+    "auth": {"type": "apikey", "anonymous_access": False, "cost": "Free"},
+    "capabilities": [
+        {
+            "id": "send_message",
+            "description_for_ai": "Send a text message to a user or group.",
+            "intent": ["send telegram message", "telegram notify", "telegram bot send"],
+            "endpoint": "POST https://api.telegram.org/bot{token}/sendMessage",
+            "input": {
+                "chat_id": {"type": "string", "required": True, "description": "Telegram chat ID"},
+                "text": {"type": "string", "required": True, "description": "Message text"},
+                "parse_mode": {"type": "string", "required": False, "description": "HTML or Markdown"},
+            },
+            "output": {"type": "message", "fields": ["message_id", "chat.id", "text"]},
+            "realtime": True,
+            "requires_auth": True,
+        }
+    ],
+    "agent_hints": {"bot_father": "Get token from @BotFather on Telegram"},
+    "meta": {"apia_version": "1.0", "last_verified": "2026-06-14"},
+}
+
+SAMPLE_REGISTRY = {
+    "_meta": {"total": 1, "generated": "2026-06-14"},
+    "manifests": [
+        {
+            "id": "telegram-bot",
+            "name": "Telegram Bot API",
+            "description_for_ai": "Send messages via Telegram. 950M users.",
+            "category": "social",
+            "geo": ["GLOBAL"],
+            "language": "en",
+            "auth_type": "apikey",
+            "anonymous_access": False,
+            "cost": "Free",
+            "capabilities": [
+                {
+                    "id": "send_message",
+                    "description_for_ai": "Send a text message.",
+                    "intent": ["send telegram message", "telegram notify"],
+                    "endpoint": "POST https://api.telegram.org/bot{token}/sendMessage",
+                    "realtime": True,
+                    "requires_auth": True,
+                }
+            ],
+            "manifest_url": "https://raw.githubusercontent.com/Komsomol39/apia-standard/main/manifests/telegram-bot/apia.json",
+        }
+    ],
+}
+
+
+# ── Manifest tests ───────────────────────────────────────────────────────────
+
+class TestManifest:
+    def test_from_dict(self):
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        assert m.id == "telegram-bot"
+        assert m.name == "Telegram Bot API"
+        assert m.category == "social"
+        assert m.is_free is False
+        assert len(m.capabilities) == 1
+
+    def test_find_capability_match(self):
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        cap = m.find_capability("send telegram message")
+        assert cap is not None
+        assert cap.id == "send_message"
+
+    def test_find_capability_no_match(self):
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        cap = m.find_capability("book a hotel room")
+        assert cap is None
+
+    def test_to_openai_tools(self):
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        tools = m.to_openai_tools()
+        assert len(tools) == 1
+        tool = tools[0]
+        assert tool["type"] == "function"
+        assert tool["function"]["name"] == "send_message"
+        assert "chat_id" in tool["function"]["parameters"]["properties"]
+        assert "chat_id" in tool["function"]["parameters"]["required"]
+        assert "parse_mode" not in tool["function"]["parameters"]["required"]
+
+    def test_to_system_prompt(self):
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        prompt = m.to_system_prompt()
+        assert "Telegram Bot API" in prompt
+        assert "send_message" in prompt
+        assert "POST" in prompt
+
+
+# ── Capability tests ─────────────────────────────────────────────────────────
+
+class TestCapability:
+    def test_matches_intent(self):
+        cap = Capability.from_dict(SAMPLE_MANIFEST["capabilities"][0])
+        assert cap.matches_intent("send telegram message") is True
+        assert cap.matches_intent("telegram notify") is True
+        assert cap.matches_intent("book flight") is False
+
+
+# ── Registry tests ───────────────────────────────────────────────────────────
+
+class TestRegistry:
+    def _registry_with_mock_index(self):
+        registry = Registry()
+        registry._index = SAMPLE_REGISTRY["manifests"]
+        return registry
+
+    def test_list_all(self):
+        r = self._registry_with_mock_index()
+        entries = r.list()
+        assert len(entries) == 1
+
+    def test_list_by_category(self):
+        r = self._registry_with_mock_index()
+        assert len(r.list(category="social")) == 1
+        assert len(r.list(category="finance")) == 0
+
+    def test_list_by_geo(self):
+        r = self._registry_with_mock_index()
+        assert len(r.list(geo="RU")) == 1   # GLOBAL includes RU
+        assert len(r.list(geo="US")) == 1
+
+    def test_list_free_only(self):
+        r = self._registry_with_mock_index()
+        assert len(r.list(free_only=True)) == 0  # telegram-bot is not anonymous
+
+    def test_categories(self):
+        r = self._registry_with_mock_index()
+        cats = r.categories()
+        assert cats == {"social": 1}
+
+    def test_find_by_intent(self):
+        r = self._registry_with_mock_index()
+        with patch.object(r, "get", return_value=Manifest.from_dict(SAMPLE_MANIFEST)):
+            results = r.find("send telegram message")
+            assert len(results) == 1
+            assert results[0].id == "telegram-bot"
+
+    def test_find_no_results(self):
+        r = self._registry_with_mock_index()
+        results = r.find("xyzzy-nonexistent-quantum-blockchain")
+        assert results == []
+
+    def test_get_manifest(self):
+        r = self._registry_with_mock_index()
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = SAMPLE_MANIFEST
+        with patch("httpx.get", return_value=mock_response):
+            m = r.get("telegram-bot")
+            assert m.id == "telegram-bot"
+
+    def test_get_not_found(self):
+        r = self._registry_with_mock_index()
+        mock_response = MagicMock()
+        mock_response.status_code = 404
+        with patch("httpx.get", return_value=mock_response):
+            with pytest.raises(ManifestNotFoundError):
+                r.get("nonexistent-api")
+
+    def test_get_cached(self):
+        r = self._registry_with_mock_index()
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        r._cache["telegram-bot"] = m
+        with patch("httpx.get") as mock_get:
+            result = r.get("telegram-bot")
+            mock_get.assert_not_called()
+        assert result is m
+
+    def test_build_system_prompt(self):
+        r = self._registry_with_mock_index()
+        m = Manifest.from_dict(SAMPLE_MANIFEST)
+        prompt = r.build_system_prompt([m])
+        assert "You are an AI agent" in prompt
+        assert "Telegram Bot API" in prompt