aid-discovery 1.0.0__tar.gz

aid_discovery-1.0.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: aid-discovery
+Version: 1.0.0
+Summary: Python library for Agent Interface Discovery (AID) - v1.0.0 release
+Author-email: Agent Community <maintainers@agentcommunity.org>
+License: MIT
+Project-URL: Homepage, https://github.com/agent-community/agent-interface-discovery
+Project-URL: Repository, https://github.com/agent-community/agent-interface-discovery
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: dnspython>=2.6.0
+Requires-Dist: idna>=3.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# aid-discovery (Python)
+
+> Official Python implementation of the [Agent Interface Discovery (AID)](https://github.com/agentcommunity/agent-interface-discovery) specification.
+
+[![PyPI version](https://img.shields.io/pypi/v/aid-discovery.svg?color=blue)](https://pypi.org/project/aid-discovery/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+AID enables you to discover AI agents by domain name using DNS TXT records. Type a domain, get the agent's endpoint and protocol - that's it.
+
+## Installation
+
+```bash
+pip install aid-discovery
+```
+
+## Quick Start
+
+```python
+from aid_py import discover, AidError
+
+try:
+    # Discover an agent by domain
+    result = discover("supabase.agentcommunity.org")
+
+    print(f"Protocol: {result.record.proto}")  # "mcp"
+    print(f"URI: {result.record.uri}")         # "https://api.supabase.com/mcp"
+    print(f"Description: {result.record.desc}") # "Supabase MCP"
+    print(f"TTL: {result.ttl} seconds")
+
+except AidError as e:
+    print(f"Discovery failed: {e}")
+```
+
+## API Reference
+
+### `discover(domain: str) -> DiscoveryResult`
+
+Discovers an agent by looking up the `_agent` TXT record for the given domain.
+
+**Parameters:**
+
+- `domain` (str): The domain name to discover
+
+**Returns:**
+
+- `DiscoveryResult`: Object containing the parsed record and TTL
+
+**Raises:**
+
+- `AidError`: If discovery fails for any reason
+
+### `parse(txt: str) -> AidRecord`
+
+Parses and validates a raw TXT record string.
+
+**Parameters:**
+
+- `txt` (str): Raw TXT record content (e.g., "v=aid1;uri=https://...")
+
+**Returns:**
+
+- `AidRecord`: Parsed and validated record
+
+**Raises:**
+
+- `AidError`: If parsing or validation fails
+
+## Data Types
+
+### `AidRecord`
+
+Represents a parsed AID record with the following attributes:
+
+- `v` (str): Protocol version (always "aid1")
+- `uri` (str): Agent endpoint URI
+- `proto` (str): Protocol identifier (e.g., "mcp", "openapi")
+- `auth` (str, optional): Authentication method
+- `desc` (str, optional): Human-readable description
+
+### `DiscoveryResult`
+
+Contains discovery results:
+
+- `record` (AidRecord): The parsed AID record
+- `ttl` (int): DNS TTL in seconds
+
+### `AidError`
+
+Exception raised when discovery or parsing fails:
+
+- `code` (int): Numeric error code
+- `message` (str): Human-readable error message
+
+## Error Codes
+
+| Code | Symbol                  | Description                  |
+| ---- | ----------------------- | ---------------------------- |
+| 1000 | `ERR_NO_RECORD`         | No `_agent` TXT record found |
+| 1001 | `ERR_INVALID_TXT`       | Record found but malformed   |
+| 1002 | `ERR_UNSUPPORTED_PROTO` | Protocol not supported       |
+| 1003 | `ERR_SECURITY`          | Security policy violation    |
+| 1004 | `ERR_DNS_LOOKUP_FAILED` | DNS query failed             |
+
+## Advanced Usage
+
+### Custom Error Handling
+
+```python
+from aid_py import discover, AidError
+
+try:
+    result = discover("example.com")
+    # Use result.record...
+except AidError as e:
+    if e.code == 1000:  # ERR_NO_RECORD
+        print("No agent found for this domain")
+    elif e.code == 1001:  # ERR_INVALID_TXT
+        print("Found a record but it's malformed")
+    else:
+        print(f"Other error: {e}")
+```
+
+### Parsing Raw Records
+
+```python
+from aid_py import parse, AidError
+
+txt_record = "v=aid1;uri=https://api.example.com/agent;proto=mcp;desc=Example Agent"
+
+try:
+    record = parse(txt_record)
+    print(f"Parsed: {record.proto} agent at {record.uri}")
+except AidError as e:
+    print(f"Invalid record: {e}")
+```
+
+## Development
+
+This package is part of the [AID monorepo](https://github.com/agentcommunity/agent-interface-discovery). To run tests:
+
+```bash
+# From the monorepo root
+pnpm test
+
+# Or run Python tests directly
+cd packages/aid-py
+python -m pytest tests/
+```
+
+## License
+
+MIT - see [LICENSE](https://github.com/agentcommunity/agent-interface-discovery/blob/main/LICENSE) for details.

aid_discovery-1.0.0/README.md

@@ -0,0 +1,152 @@
+# aid-discovery (Python)
+
+> Official Python implementation of the [Agent Interface Discovery (AID)](https://github.com/agentcommunity/agent-interface-discovery) specification.
+
+[![PyPI version](https://img.shields.io/pypi/v/aid-discovery.svg?color=blue)](https://pypi.org/project/aid-discovery/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+AID enables you to discover AI agents by domain name using DNS TXT records. Type a domain, get the agent's endpoint and protocol - that's it.
+
+## Installation
+
+```bash
+pip install aid-discovery
+```
+
+## Quick Start
+
+```python
+from aid_py import discover, AidError
+
+try:
+    # Discover an agent by domain
+    result = discover("supabase.agentcommunity.org")
+
+    print(f"Protocol: {result.record.proto}")  # "mcp"
+    print(f"URI: {result.record.uri}")         # "https://api.supabase.com/mcp"
+    print(f"Description: {result.record.desc}") # "Supabase MCP"
+    print(f"TTL: {result.ttl} seconds")
+
+except AidError as e:
+    print(f"Discovery failed: {e}")
+```
+
+## API Reference
+
+### `discover(domain: str) -> DiscoveryResult`
+
+Discovers an agent by looking up the `_agent` TXT record for the given domain.
+
+**Parameters:**
+
+- `domain` (str): The domain name to discover
+
+**Returns:**
+
+- `DiscoveryResult`: Object containing the parsed record and TTL
+
+**Raises:**
+
+- `AidError`: If discovery fails for any reason
+
+### `parse(txt: str) -> AidRecord`
+
+Parses and validates a raw TXT record string.
+
+**Parameters:**
+
+- `txt` (str): Raw TXT record content (e.g., "v=aid1;uri=https://...")
+
+**Returns:**
+
+- `AidRecord`: Parsed and validated record
+
+**Raises:**
+
+- `AidError`: If parsing or validation fails
+
+## Data Types
+
+### `AidRecord`
+
+Represents a parsed AID record with the following attributes:
+
+- `v` (str): Protocol version (always "aid1")
+- `uri` (str): Agent endpoint URI
+- `proto` (str): Protocol identifier (e.g., "mcp", "openapi")
+- `auth` (str, optional): Authentication method
+- `desc` (str, optional): Human-readable description
+
+### `DiscoveryResult`
+
+Contains discovery results:
+
+- `record` (AidRecord): The parsed AID record
+- `ttl` (int): DNS TTL in seconds
+
+### `AidError`
+
+Exception raised when discovery or parsing fails:
+
+- `code` (int): Numeric error code
+- `message` (str): Human-readable error message
+
+## Error Codes
+
+| Code | Symbol                  | Description                  |
+| ---- | ----------------------- | ---------------------------- |
+| 1000 | `ERR_NO_RECORD`         | No `_agent` TXT record found |
+| 1001 | `ERR_INVALID_TXT`       | Record found but malformed   |
+| 1002 | `ERR_UNSUPPORTED_PROTO` | Protocol not supported       |
+| 1003 | `ERR_SECURITY`          | Security policy violation    |
+| 1004 | `ERR_DNS_LOOKUP_FAILED` | DNS query failed             |
+
+## Advanced Usage
+
+### Custom Error Handling
+
+```python
+from aid_py import discover, AidError
+
+try:
+    result = discover("example.com")
+    # Use result.record...
+except AidError as e:
+    if e.code == 1000:  # ERR_NO_RECORD
+        print("No agent found for this domain")
+    elif e.code == 1001:  # ERR_INVALID_TXT
+        print("Found a record but it's malformed")
+    else:
+        print(f"Other error: {e}")
+```
+
+### Parsing Raw Records
+
+```python
+from aid_py import parse, AidError
+
+txt_record = "v=aid1;uri=https://api.example.com/agent;proto=mcp;desc=Example Agent"
+
+try:
+    record = parse(txt_record)
+    print(f"Parsed: {record.proto} agent at {record.uri}")
+except AidError as e:
+    print(f"Invalid record: {e}")
+```
+
+## Development
+
+This package is part of the [AID monorepo](https://github.com/agentcommunity/agent-interface-discovery). To run tests:
+
+```bash
+# From the monorepo root
+pnpm test
+
+# Or run Python tests directly
+cd packages/aid-py
+python -m pytest tests/
+```
+
+## License
+
+MIT - see [LICENSE](https://github.com/agentcommunity/agent-interface-discovery/blob/main/LICENSE) for details.

aid_discovery-1.0.0/aid_discovery.egg-info/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: aid-discovery
+Version: 1.0.0
+Summary: Python library for Agent Interface Discovery (AID) - v1.0.0 release
+Author-email: Agent Community <maintainers@agentcommunity.org>
+License: MIT
+Project-URL: Homepage, https://github.com/agent-community/agent-interface-discovery
+Project-URL: Repository, https://github.com/agent-community/agent-interface-discovery
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: dnspython>=2.6.0
+Requires-Dist: idna>=3.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# aid-discovery (Python)
+
+> Official Python implementation of the [Agent Interface Discovery (AID)](https://github.com/agentcommunity/agent-interface-discovery) specification.
+
+[![PyPI version](https://img.shields.io/pypi/v/aid-discovery.svg?color=blue)](https://pypi.org/project/aid-discovery/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+AID enables you to discover AI agents by domain name using DNS TXT records. Type a domain, get the agent's endpoint and protocol - that's it.
+
+## Installation
+
+```bash
+pip install aid-discovery
+```
+
+## Quick Start
+
+```python
+from aid_py import discover, AidError
+
+try:
+    # Discover an agent by domain
+    result = discover("supabase.agentcommunity.org")
+
+    print(f"Protocol: {result.record.proto}")  # "mcp"
+    print(f"URI: {result.record.uri}")         # "https://api.supabase.com/mcp"
+    print(f"Description: {result.record.desc}") # "Supabase MCP"
+    print(f"TTL: {result.ttl} seconds")
+
+except AidError as e:
+    print(f"Discovery failed: {e}")
+```
+
+## API Reference
+
+### `discover(domain: str) -> DiscoveryResult`
+
+Discovers an agent by looking up the `_agent` TXT record for the given domain.
+
+**Parameters:**
+
+- `domain` (str): The domain name to discover
+
+**Returns:**
+
+- `DiscoveryResult`: Object containing the parsed record and TTL
+
+**Raises:**
+
+- `AidError`: If discovery fails for any reason
+
+### `parse(txt: str) -> AidRecord`
+
+Parses and validates a raw TXT record string.
+
+**Parameters:**
+
+- `txt` (str): Raw TXT record content (e.g., "v=aid1;uri=https://...")
+
+**Returns:**
+
+- `AidRecord`: Parsed and validated record
+
+**Raises:**
+
+- `AidError`: If parsing or validation fails
+
+## Data Types
+
+### `AidRecord`
+
+Represents a parsed AID record with the following attributes:
+
+- `v` (str): Protocol version (always "aid1")
+- `uri` (str): Agent endpoint URI
+- `proto` (str): Protocol identifier (e.g., "mcp", "openapi")
+- `auth` (str, optional): Authentication method
+- `desc` (str, optional): Human-readable description
+
+### `DiscoveryResult`
+
+Contains discovery results:
+
+- `record` (AidRecord): The parsed AID record
+- `ttl` (int): DNS TTL in seconds
+
+### `AidError`
+
+Exception raised when discovery or parsing fails:
+
+- `code` (int): Numeric error code
+- `message` (str): Human-readable error message
+
+## Error Codes
+
+| Code | Symbol                  | Description                  |
+| ---- | ----------------------- | ---------------------------- |
+| 1000 | `ERR_NO_RECORD`         | No `_agent` TXT record found |
+| 1001 | `ERR_INVALID_TXT`       | Record found but malformed   |
+| 1002 | `ERR_UNSUPPORTED_PROTO` | Protocol not supported       |
+| 1003 | `ERR_SECURITY`          | Security policy violation    |
+| 1004 | `ERR_DNS_LOOKUP_FAILED` | DNS query failed             |
+
+## Advanced Usage
+
+### Custom Error Handling
+
+```python
+from aid_py import discover, AidError
+
+try:
+    result = discover("example.com")
+    # Use result.record...
+except AidError as e:
+    if e.code == 1000:  # ERR_NO_RECORD
+        print("No agent found for this domain")
+    elif e.code == 1001:  # ERR_INVALID_TXT
+        print("Found a record but it's malformed")
+    else:
+        print(f"Other error: {e}")
+```
+
+### Parsing Raw Records
+
+```python
+from aid_py import parse, AidError
+
+txt_record = "v=aid1;uri=https://api.example.com/agent;proto=mcp;desc=Example Agent"
+
+try:
+    record = parse(txt_record)
+    print(f"Parsed: {record.proto} agent at {record.uri}")
+except AidError as e:
+    print(f"Invalid record: {e}")
+```
+
+## Development
+
+This package is part of the [AID monorepo](https://github.com/agentcommunity/agent-interface-discovery). To run tests:
+
+```bash
+# From the monorepo root
+pnpm test
+
+# Or run Python tests directly
+cd packages/aid-py
+python -m pytest tests/
+```
+
+## License
+
+MIT - see [LICENSE](https://github.com/agentcommunity/agent-interface-discovery/blob/main/LICENSE) for details.

aid_discovery-1.0.0/aid_discovery.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+aid_discovery.egg-info/PKG-INFO
+aid_discovery.egg-info/SOURCES.txt
+aid_discovery.egg-info/dependency_links.txt
+aid_discovery.egg-info/requires.txt
+aid_discovery.egg-info/top_level.txt
+aid_py/__init__.py
+aid_py/constants.py
+aid_py/discover.py
+aid_py/parser.py
+tests/test_discover.py
+tests/test_parity.py
+tests/test_parser.py

aid_discovery-1.0.0/aid_discovery.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aid_discovery-1.0.0/aid_discovery.egg-info/requires.txt

@@ -0,0 +1,5 @@
+dnspython>=2.6.0
+idna>=3.6
+
+[dev]
+pytest>=8

aid_discovery-1.0.0/aid_discovery.egg-info/top_level.txt

@@ -0,0 +1 @@
+aid_py

aid_discovery-1.0.0/aid_py/__init__.py

@@ -0,0 +1,29 @@
+# MIT License
+# Copyright (c) 2025 Agent Community
+# Author: Agent Community
+# Repository: https://github.com/agentcommunity/agent-interface-discovery
+"""Agent Interface Discovery (AID) – Python library.
+
+This is a **work-in-progress** implementation providing the same high-level API as the
+TypeScript reference:
+
+    from aid_py import discover, parse, AidError
+
+    record = discover("example.com")
+    # ...
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+# Re-export key API pieces from submodules
+from .parser import AidError, parse, is_valid_proto  # noqa: E402
+from .discover import discover  # noqa: E402
+
+__all__ = [
+    "discover",
+    "parse",
+    "is_valid_proto",
+    "AidError",
+] 

aid_discovery-1.0.0/aid_py/constants.py

@@ -0,0 +1,93 @@
+"""
+GENERATED FILE - DO NOT EDIT
+
+This file is auto-generated from protocol/constants.yml by scripts/generate-constants.ts
+To make changes, edit the YAML file and run: pnpm gen
+"""
+from __future__ import annotations
+
+from typing import Final, Dict, List
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+
+SPEC_VERSION: Final[str] = "aid1"
+
+# ---------------------------------------------------------------------------
+# Protocol tokens
+# ---------------------------------------------------------------------------
+PROTO_A2A: Final[str] = "a2a"
+PROTO_LOCAL: Final[str] = "local"
+PROTO_MCP: Final[str] = "mcp"
+PROTO_OPENAPI: Final[str] = "openapi"
+
+PROTOCOL_TOKENS: Final[Dict[str, str]] = {
+    "a2a": "a2a",
+    "local": "local",
+    "mcp": "mcp",
+    "openapi": "openapi",
+}
+
+# ---------------------------------------------------------------------------
+# Auth tokens
+# ---------------------------------------------------------------------------
+AUTH_APIKEY: Final[str] = "apikey"
+AUTH_BASIC: Final[str] = "basic"
+AUTH_CUSTOM: Final[str] = "custom"
+AUTH_MTLS: Final[str] = "mtls"
+AUTH_NONE: Final[str] = "none"
+AUTH_OAUTH2_CODE: Final[str] = "oauth2_code"
+AUTH_OAUTH2_DEVICE: Final[str] = "oauth2_device"
+AUTH_PAT: Final[str] = "pat"
+
+AUTH_TOKENS: Final[Dict[str, str]] = {
+    "apikey": "apikey",
+    "basic": "basic",
+    "custom": "custom",
+    "mtls": "mtls",
+    "none": "none",
+    "oauth2_code": "oauth2_code",
+    "oauth2_device": "oauth2_device",
+    "pat": "pat",
+}
+
+# ---------------------------------------------------------------------------
+# Error codes & messages
+# ---------------------------------------------------------------------------
+
+ERR_DNS_LOOKUP_FAILED: Final[int] = 1004
+ERR_INVALID_TXT: Final[int] = 1001
+ERR_NO_RECORD: Final[int] = 1000
+ERR_SECURITY: Final[int] = 1003
+ERR_UNSUPPORTED_PROTO: Final[int] = 1002
+
+ERROR_CODES: Final[Dict[str, int]] = {
+    "ERR_DNS_LOOKUP_FAILED": ERR_DNS_LOOKUP_FAILED,
+    "ERR_INVALID_TXT": ERR_INVALID_TXT,
+    "ERR_NO_RECORD": ERR_NO_RECORD,
+    "ERR_SECURITY": ERR_SECURITY,
+    "ERR_UNSUPPORTED_PROTO": ERR_UNSUPPORTED_PROTO,
+}
+
+ERROR_MESSAGES: Final[Dict[str, str]] = {
+    "ERR_DNS_LOOKUP_FAILED": "The DNS query failed for a network-related reason",
+    "ERR_INVALID_TXT": "A record was found but is malformed or missing required keys",
+    "ERR_NO_RECORD": "No _agent TXT record was found for the domain",
+    "ERR_SECURITY": "Discovery failed due to a security policy (e.g., DNSSEC failure, local execution denied)",
+    "ERR_UNSUPPORTED_PROTO": "The record is valid, but the client does not support the specified protocol",
+}
+
+# ---------------------------------------------------------------------------
+# Other spec constants
+# ---------------------------------------------------------------------------
+
+DNS_SUBDOMAIN: Final[str] = "_agent"
+DNS_TTL_MIN: Final[int] = 300
+DNS_TTL_MAX: Final[int] = 900
+
+LOCAL_URI_SCHEMES: Final[List[str]] = [
+    "docker",
+    "npx",
+    "pip",
+]

aid_discovery-1.0.0/aid_py/discover.py

@@ -0,0 +1,93 @@
+# MIT License
+# Copyright (c) 2025 Agent Community
+# Author: Agent Community
+# Repository: https://github.com/agentcommunity/agent-interface-discovery
+"""DNS discovery client for Agent Interface Discovery (AID).
+
+Uses `dnspython` to query the `_agent.<domain>` TXT record, validates it
+with `aid_py.parse`, and returns the parsed record together with the DNS TTL.
+"""
+from __future__ import annotations
+
+from typing import Tuple
+
+import dns.exception
+import dns.resolver
+
+from .constants import DNS_SUBDOMAIN
+from .parser import AidError, parse
+
+__all__ = ["discover"]
+
+
+def _query_txt_record(fqdn: str, timeout: float) -> Tuple[list[str], int]:
+    """Return list of TXT strings and TTL or raise AidError on DNS failure."""
+
+    try:
+        answers = dns.resolver.resolve(fqdn, "TXT", lifetime=timeout)
+    except dns.resolver.NXDOMAIN as exc:
+        raise AidError("ERR_NO_RECORD", str(exc)) from None
+    except (dns.resolver.Timeout, dns.exception.DNSException) as exc:
+        raise AidError("ERR_DNS_LOOKUP_FAILED", str(exc)) from None
+
+    # dnspython joins multi-string automatically? Actually each answer.rdata.strings
+    ttl = answers.rrset.ttl if answers.rrset else DNS_TTL_DEFAULT
+    txt_strings: list[str] = []
+    for rdata in answers:
+        # each rdata.strings is a tuple of bytes segments
+        txt_strings.append("".join(seg.decode() for seg in rdata.strings))
+    return txt_strings, ttl
+
+
+DNS_TTL_DEFAULT = 300  # fallback
+
+
+def discover(domain: str, *, protocol: str | None = None, timeout: float = 5.0) -> Tuple[dict, int]:
+    """Discover and validate the AID record for *domain*.
+
+    Can optionally try a protocol-specific subdomain first.
+
+    Returns a tuple `(record_dict, ttl_seconds)`.
+    Raises `AidError` on any failure as per the specification.
+    """
+
+    # IDN → A-label conversion per RFC5890
+    try:
+        import idna
+
+        domain_alabel = idna.encode(domain).decode()
+    except Exception:
+        domain_alabel = domain  # Fallback – let DNS resolver handle errors
+
+    def _query_and_parse(query_name: str) -> Tuple[dict, int]:
+        """Query a specific FQDN and parse the result."""
+        txt_records, ttl = _query_txt_record(query_name, timeout)
+
+        last_error: AidError | None = None
+        for txt in txt_records:
+            try:
+                record = parse(txt)
+                return record, ttl
+            except AidError as exc:
+                # Save and try the next TXT string (if multiple records exist)
+                last_error = exc
+                continue
+
+        # If we got here, either no records or all invalid
+        if last_error is not None:
+            raise last_error
+        raise AidError("ERR_NO_RECORD", f"No valid _agent TXT record found for {query_name}")
+
+    # Try protocol-specific subdomain first if specified
+    if protocol:
+        protocol_fqdn = f"{DNS_SUBDOMAIN}.{protocol}.{domain_alabel}".rstrip(".")
+        try:
+            return _query_and_parse(protocol_fqdn)
+        except AidError as exc:
+            if exc.error_code != "ERR_NO_RECORD":
+                raise exc
+            # else: fall through to base domain query
+
+    # Fallback or default: query the base _agent subdomain
+    base_fqdn = f"{DNS_SUBDOMAIN}.{domain_alabel}".rstrip(".")
+    return _query_and_parse(base_fqdn) 

aid_discovery-1.0.0/aid_py/parser.py

@@ -0,0 +1,187 @@
+# MIT License
+# Copyright (c) 2025 Agent Community
+# Author: Agent Community
+# Repository: https://github.com/agentcommunity/agent-interface-discovery
+"""AID record parser and validator (Python).
+
+Mirrors the TypeScript reference implementation in `packages/aid/src/parser.ts`.
+"""
+from __future__ import annotations
+
+import re
+from typing import Dict, Tuple, TypedDict
+
+from .constants import (
+    SPEC_VERSION,
+    PROTOCOL_TOKENS,
+    AUTH_TOKENS,
+    ERROR_MESSAGES,
+    ERROR_CODES,
+    LOCAL_URI_SCHEMES,
+)
+
+# ---------------------------------------------------------------------------
+# Error class
+# ---------------------------------------------------------------------------
+
+
+class AidError(ValueError):
+    """Raised when parsing/validation fails with spec-specific error codes."""
+
+    def __init__(self, error_code: str, message: str | None = None):
+        if error_code not in ERROR_CODES:
+            raise ValueError(f"Unknown error code: {error_code}")
+        super().__init__(message or ERROR_MESSAGES[error_code])
+        self.name = "AidError"
+        self.error_code: str = error_code  # symbolic (e.g. "ERR_INVALID_TXT")
+        self.code: int = ERROR_CODES[error_code]  # numeric (e.g. 1001)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"AidError(error_code={self.error_code}, message={self.args[0]!r})"
+
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+
+class AidRecord(TypedDict, total=False):
+    v: str
+    uri: str
+    proto: str
+    auth: str
+    desc: str
+
+
+RawAidRecord = Dict[str, str]
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_raw_record(txt: str) -> RawAidRecord:
+    """Split semicolon-delimited key=value pairs into a dict."""
+
+    record: RawAidRecord = {}
+
+    # Drop surrounding whitespace and split by semicolon
+    for pair in [p.strip() for p in txt.split(";") if p.strip()]:
+        if "=" not in pair:
+            raise AidError("ERR_INVALID_TXT", f"Invalid key-value pair: {pair}")
+        key, value = pair.split("=", 1)
+        key = key.strip().lower()
+        value = value.strip()
+        if not key or not value:
+            raise AidError("ERR_INVALID_TXT", f"Empty key or value in pair: {pair}")
+        if key in record:
+            raise AidError("ERR_INVALID_TXT", f"Duplicate key: {key}")
+        record[key] = value
+    return record
+
+
+def _is_valid_local_uri(uri: str) -> bool:
+    match = re.match(r"^(?P<scheme>[a-zA-Z][a-zA-Z0-9+.-]*):", uri)
+    if not match:
+        return False
+    scheme = match.group("scheme")
+    return scheme in LOCAL_URI_SCHEMES
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def validate_record(raw: RawAidRecord) -> AidRecord:
+    """Validate a raw record dict and return a typed record."""
+
+    # Required fields
+    if "v" not in raw:
+        raise AidError("ERR_INVALID_TXT", "Missing required field: v")
+    if "uri" not in raw:
+        raise AidError("ERR_INVALID_TXT", "Missing required field: uri")
+
+    # proto or p but not both
+    has_proto = "proto" in raw
+    has_p = "p" in raw
+    if has_proto and has_p:
+        raise AidError("ERR_INVALID_TXT", 'Cannot specify both "proto" and "p" fields')
+    if not has_proto and not has_p:
+        raise AidError("ERR_INVALID_TXT", "Missing required field: proto (or p)")
+
+    # Version check
+    if raw["v"] != SPEC_VERSION:
+        raise AidError(
+            "ERR_INVALID_TXT",
+            f"Unsupported version: {raw['v']}. Expected: {SPEC_VERSION}",
+        )
+
+    proto_value = raw.get("proto") or raw.get("p")  # already ensured exists
+    if proto_value not in PROTOCOL_TOKENS:
+        raise AidError("ERR_UNSUPPORTED_PROTO", f"Unsupported protocol: {proto_value}")
+
+    # Auth token validation
+    if "auth" in raw and raw["auth"] not in AUTH_TOKENS:
+        raise AidError("ERR_INVALID_TXT", f"Invalid auth token: {raw['auth']}")
+
+    # Description length ≤ 60 UTF-8 bytes
+    if "desc" in raw and len(raw["desc"].encode("utf-8")) > 60:
+        raise AidError("ERR_INVALID_TXT", "Description field must be ≤ 60 UTF-8 bytes")
+
+    # URI validation
+    uri = raw["uri"]
+    if proto_value == "local":
+        # Must use approved local scheme
+        if not _is_valid_local_uri(uri):
+            raise AidError(
+                "ERR_INVALID_TXT",
+                f"Invalid URI scheme for local protocol. Must be one of: {', '.join(LOCAL_URI_SCHEMES)}",
+            )
+    else:
+        if not uri.startswith("https://"):
+            raise AidError(
+                "ERR_INVALID_TXT",
+                f"Invalid URI scheme for remote protocol '{proto_value}'. MUST be 'https:'",
+            )
+        # Basic URL validation
+        try:
+            from urllib.parse import urlparse
+
+            parsed = urlparse(uri)
+            if not parsed.scheme or not parsed.netloc:
+                raise ValueError
+        except Exception:
+            raise AidError("ERR_INVALID_TXT", f"Invalid URI format: {uri}") from None
+
+    # Build typed record
+    record: AidRecord = {
+        "v": "aid1",
+        "uri": uri,
+        "proto": proto_value,  # type: ignore[assignment]
+    }
+    if "auth" in raw:
+        record["auth"] = raw["auth"]
+    if "desc" in raw:
+        record["desc"] = raw["desc"]
+    return record
+
+
+def parse(txt_record: str) -> AidRecord:
+    """Parse and validate a TXT record string."""
+
+    raw = _parse_raw_record(txt_record)
+    return validate_record(raw)
+
+
+def is_valid_proto(token: str) -> bool:
+    return token in PROTOCOL_TOKENS
+
+
+# Expose main helpers for import convenience
+__all__ = [
+    "AidError",
+    "parse",
+    "validate_record",
+    "is_valid_proto",
+] 

aid_discovery-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aid-discovery"
+version = "1.0.0"
+description = "Python library for Agent Interface Discovery (AID) - v1.0.0 release"
+authors = [{ name = "Agent Community", email = "maintainers@agentcommunity.org" }]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = ["dnspython>=2.6.0", "idna>=3.6"]
+
+[project.urls]
+Homepage = "https://github.com/agent-community/agent-interface-discovery"
+Repository = "https://github.com/agent-community/agent-interface-discovery"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"] 

aid_discovery-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aid_discovery-1.0.0/tests/test_discover.py

@@ -0,0 +1,87 @@
+# MIT License
+# Copyright (c) 2025 Agent Community
+# Author: Agent Community
+# Repository: https://github.com/agentcommunity/agent-interface-discovery
+import types, sys, pathlib
+import pytest
+
+sys.path.append(str(pathlib.Path(__file__).resolve().parents[1]))
+
+from aid_py import discover, AidError  # noqa: E402
+
+
+class _FakeRdata:  # minimal stub
+    def __init__(self, strings):
+        self.strings = tuple(s.encode() for s in strings)
+
+
+class _FakeAnswer(list):
+    def __init__(self, strings_list, ttl):
+        super().__init__(_FakeRdata([s]) for s in strings_list)
+        rrset = types.SimpleNamespace()
+        rrset.ttl = ttl
+        self.rrset = rrset
+
+
+@pytest.fixture()
+def monkey_resolver(monkeypatch):
+    import dns.resolver
+
+    def _fake_resolve(name, rdtype, lifetime=5.0):
+        assert rdtype == "TXT"
+        if name == "_agent.example.com":
+            return _FakeAnswer(["v=aid1;uri=https://api.example.com/mcp;proto=mcp"], 300)
+        raise dns.resolver.NXDOMAIN()
+
+    monkeypatch.setattr(dns.resolver, "resolve", _fake_resolve)
+
+
+def test_discover_success(monkey_resolver):  # pylint: disable=unused-argument
+    record, ttl = discover("example.com")
+    assert record["proto"] == "mcp"
+    assert ttl == 300
+
+
+def test_discover_protocol_specific_success(monkeypatch):
+    import dns.resolver
+
+    def _fake_resolve(name, rdtype, lifetime=5.0):
+        if name == "_agent.mcp.example.com":
+            return _FakeAnswer(["v=aid1;uri=https://api.example.com/mcp;proto=mcp"], 333)
+        if name == "_agent.example.com":
+            return _FakeAnswer(["v=aid1;uri=https://api.example.com/fallback;p=a2a"], 444)
+        raise dns.resolver.NXDOMAIN()
+
+    monkeypatch.setattr(dns.resolver, "resolve", _fake_resolve)
+    record, ttl = discover("example.com", protocol="mcp")
+    assert record["proto"] == "mcp"
+    assert record["uri"] == "https://api.example.com/mcp"
+    assert ttl == 333
+
+
+def test_discover_fallback_to_base(monkeypatch):
+    import dns.resolver
+
+    def _fake_resolve(name, rdtype, lifetime=5.0):
+        if name == "_agent.mcp.example.com":
+            raise dns.resolver.NXDOMAIN()
+        if name == "_agent.example.com":
+            return _FakeAnswer(["v=aid1;uri=https://fallback.com;p=a2a"], 555)
+        raise dns.resolver.NXDOMAIN()
+
+    monkeypatch.setattr(dns.resolver, "resolve", _fake_resolve)
+    record, ttl = discover("example.com", protocol="mcp")
+    assert record["proto"] == "a2a"
+    assert record["uri"] == "https://fallback.com"
+    assert ttl == 555
+
+
+def test_discover_no_record(monkeypatch):
+    import dns.resolver
+
+    def _no_record(name, rdtype, lifetime=5.0):
+        raise dns.resolver.NXDOMAIN()
+
+    monkeypatch.setattr(dns.resolver, "resolve", _no_record)
+    with pytest.raises(AidError):
+        discover("missing.com") 

aid_discovery-1.0.0/tests/test_parity.py

@@ -0,0 +1,23 @@
+# MIT License
+# Copyright (c) 2025 Agent Community
+# Author: Agent Community
+# Repository: https://github.com/agentcommunity/agent-interface-discovery
+"""Cross-language parity test (Python).
+Parses the shared golden fixtures and ensures output matches expected.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from aid_py.parser import parse
+
+FIXTURE_PATH = Path(__file__).parents[3] / "test-fixtures" / "golden.json"
+_fixture = json.loads(FIXTURE_PATH.read_text())
+
+
+def test_parity():
+    for rec in _fixture["records"]:
+        parsed = parse(rec["raw"])
+        # Convert TypedDict to plain dict for comparison
+        assert dict(parsed) == rec["expected"] 

aid_discovery-1.0.0/tests/test_parser.py

@@ -0,0 +1,63 @@
+# MIT License
+# Copyright (c) 2025 Agent Community
+# Author: Agent Community
+# Repository: https://github.com/agentcommunity/agent-interface-discovery
+
+import sys, pathlib
+sys.path.append(str(pathlib.Path(__file__).resolve().parents[1]))
+
+import pytest
+
+from aid_py import parse, AidError, is_valid_proto
+
+
+def test_parse_valid_record():
+    txt = "v=aid1;uri=https://api.example.com/mcp;proto=mcp;auth=pat;desc=Test Agent"
+    record = parse(txt)
+    assert record == {
+        "v": "aid1",
+        "uri": "https://api.example.com/mcp",
+        "proto": "mcp",
+        "auth": "pat",
+        "desc": "Test Agent",
+    }
+
+
+def test_parse_alias_p():
+    txt = "v=aid1;uri=https://api.example.com/mcp;p=mcp"
+    record = parse(txt)
+    assert record == {
+        "v": "aid1",
+        "uri": "https://api.example.com/mcp",
+        "proto": "mcp",
+    }
+
+
+def test_missing_version():
+    txt = "uri=https://api.example.com/mcp;proto=mcp"
+    with pytest.raises(AidError):
+        parse(txt)
+
+
+def test_invalid_proto():
+    txt = "v=aid1;uri=https://api.example.com/mcp;proto=unknown"
+    with pytest.raises(AidError):
+        parse(txt)
+
+
+def test_description_length():
+    long_desc = "This is a very long description that exceeds the 60 UTF-8 byte limit for AID records"
+    txt = f"v=aid1;uri=https://api.example.com/mcp;proto=mcp;desc={long_desc}"
+    with pytest.raises(AidError):
+        parse(txt)
+
+
+def test_is_valid_proto():
+    assert is_valid_proto("mcp") is True
+    assert is_valid_proto("unknown") is False
+
+
+def test_duplicate_keys():
+    txt = "v=aid1;v=aid1;uri=https://api.example.com/mcp;proto=mcp"
+    with pytest.raises(AidError, match="Duplicate key: v"):
+        parse(txt)