agentdom 3.6.0__py3-none-any.whl

agentdom/__init__.py

@@ -0,0 +1,45 @@
+"""
+AgentDOM Python SDK
+===================
+
+The universal runtime that makes every website, desktop app,
+and API accessible to AI agents — zero human in the loop.
+
+    pip install agentdom
+
+Usage (Flask):
+    from agentdom import AgentDOM
+
+    agent = AgentDOM(host="api.myapp.com")
+
+    @agent.capability("todos.create", description="Create a todo")
+    def create_todo(args):
+        return {"id": 1, "title": args["title"]}
+
+    agent.register(app)
+
+Usage (FastAPI):
+    from agentdom import AgentDOM
+
+    agent = AgentDOM(host="api.myapp.com")
+
+    @agent.capability("items.list", description="List items")
+    async def list_items(args):
+        return [{"id": 1, "name": "Widget"}]
+
+    agent.register(fastapi_app)
+
+Usage (standalone dispatch):
+    from agentdom import dispatch_intent
+
+    result = await dispatch_intent("issues.create", {
+        "title": "Bug report",
+        "body": "Reproducible on iOS 17"
+    }, host="github.com")
+"""
+
+from agentdom.core import AgentDOM, AgentCapability
+from agentdom.dispatch import dispatch_intent
+
+__version__ = "1.0.0"
+__all__ = ["AgentDOM", "AgentCapability", "dispatch_intent", "__version__"]

agentdom/core.py

@@ -0,0 +1,206 @@
+"""
+agentdom.core — AgentDOM class and capability registration.
+"""
+
+import datetime
+from typing import Callable, List, Optional
+
+
+class AgentCapability:
+    """A single declared capability (intent + handler)."""
+
+    def __init__(
+        self,
+        intent: str,
+        description: str,
+        handler: Callable,
+        args: dict = None,
+        side_effects: list = None,
+        method: str = "POST",
+    ):
+        self.intent = intent
+        self.description = description
+        self.handler = handler
+        self.args = args or {}
+        self.side_effects = side_effects or ["write_local"]
+        self.method = method
+
+
+class AgentDOM:
+    """
+    Embed AgentDOM into any Python web app.
+
+    Serves /.well-known/agentdom.json automatically and routes
+    incoming agent intents to your handler functions.
+
+    Args:
+        host:          Your public domain (e.g. "api.myapp.com")
+        name:          Human-readable name (defaults to host)
+        description:   Short description of your service
+        auth:          Auth config dict, e.g. {"method": "api_key", ...}
+        api_base_path: Route prefix for intent endpoints (default: /api/agentdom)
+    """
+
+    def __init__(
+        self,
+        host: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        auth: Optional[dict] = None,
+        api_base_path: str = "/api/agentdom",
+    ):
+        if not host:
+            raise ValueError("AgentDOM: host is required")
+        self.host = host
+        self.name = name or host
+        self.description = description or f"AgentDOM manifest for {host}"
+        self.auth = auth or {"method": "none"}
+        self.api_base_path = api_base_path
+        self._capabilities: List[AgentCapability] = []
+
+    def capability(
+        self,
+        intent: str,
+        description: str = "",
+        args: dict = None,
+        side_effects: list = None,
+        method: str = "POST",
+    ):
+        """
+        Decorator to register a capability handler.
+
+        Example:
+            @agent.capability("todos.create", description="Create a todo")
+            def create_todo(args):
+                return db.todos.insert(args["title"])
+        """
+        def decorator(fn: Callable):
+            cap = AgentCapability(
+                intent=intent,
+                description=description,
+                handler=fn,
+                args=args or {},
+                side_effects=side_effects or ["write_local"],
+                method=method,
+            )
+            self._capabilities.append(cap)
+            return fn
+        return decorator
+
+    def manifest(self) -> dict:
+        """
+        Build and return the agentdom.json manifest as a Python dict.
+        Serve this at GET /.well-known/agentdom.json.
+        """
+        return {
+            "version": "1.0",
+            "host": self.host,
+            "name": self.name,
+            "description": self.description,
+            "generated_at": datetime.datetime.utcnow().isoformat() + "Z",
+            "generated_by": "agentdom-python/1.0.0",
+            "auth": self.auth,
+            "capabilities": [
+                {
+                    "intent": cap.intent,
+                    "description": cap.description,
+                    "transport": "api",
+                    "method": cap.method,
+                    "endpoint": f"https://{self.host}{self.api_base_path}/{cap.intent}",
+                    "args": {
+                        k: {
+                            "type": v if isinstance(v, str) else v.get("type", "string"),
+                            "required": v.get("required", False) if isinstance(v, dict) else True,
+                            "description": v.get("description", "") if isinstance(v, dict) else "",
+                        }
+                        for k, v in cap.args.items()
+                    },
+                    "side_effects": cap.side_effects,
+                }
+                for cap in self._capabilities
+            ],
+        }
+
+    def register(self, app):
+        """
+        Auto-detect Flask or FastAPI and register all routes.
+
+        Registers:
+          GET  /.well-known/agentdom.json   → serves the manifest
+          POST /api/agentdom/<intent>        → dispatches to your handler
+        """
+        app_module = type(app).__module__
+
+        if "flask" in app_module:
+            self._register_flask(app)
+        elif "fastapi" in app_module:
+            self._register_fastapi(app)
+        else:
+            raise ValueError(
+                "AgentDOM.register() expects a Flask or FastAPI app instance. "
+                "For other frameworks, use .manifest() and route manually."
+            )
+
+    def _register_flask(self, app):
+        """Attach routes to a Flask app."""
+        from flask import request, jsonify
+
+        manifest = self.manifest()
+        cap_map = {cap.intent: cap for cap in self._capabilities}
+
+        @app.route("/.well-known/agentdom.json", methods=["GET"])
+        def agentdom_manifest():
+            return jsonify(manifest)
+
+        @app.route(f"{self.api_base_path}/<path:intent>", methods=["POST"])
+        def agentdom_intent(intent):
+            cap = cap_map.get(intent)
+            if not cap:
+                return jsonify({
+                    "error": f"Intent '{intent}' not found",
+                    "available": list(cap_map.keys()),
+                }), 404
+
+            try:
+                body = request.get_json(silent=True) or {}
+                result = cap.handler(body)
+                return jsonify({"success": True, "result": result})
+            except Exception as exc:
+                return jsonify({"success": False, "error": str(exc)}), 500
+
+    def _register_fastapi(self, app):
+        """Attach routes to a FastAPI app."""
+        from fastapi import Request
+        from fastapi.responses import JSONResponse
+
+        manifest = self.manifest()
+        cap_map = {cap.intent: cap for cap in self._capabilities}
+
+        @app.get("/.well-known/agentdom.json")
+        async def agentdom_manifest():
+            return JSONResponse(
+                manifest,
+                headers={"Cache-Control": "public, max-age=3600", "Access-Control-Allow-Origin": "*"},
+            )
+
+        @app.post(f"{self.api_base_path}/{{intent:path}}")
+        async def agentdom_intent(intent: str, request: Request):
+            import asyncio
+            cap = cap_map.get(intent)
+            if not cap:
+                return JSONResponse(
+                    {"error": f"Intent '{intent}' not found", "available": list(cap_map.keys())},
+                    status_code=404,
+                )
+            try:
+                body = await request.json()
+            except Exception:
+                body = {}
+            try:
+                if asyncio.iscoroutinefunction(cap.handler):
+                    result = await cap.handler(body)
+                else:
+                    result = cap.handler(body)
+                return JSONResponse({"success": True, "result": result})
+            except Exception as exc:
+                return JSONResponse({"success": False, "error": str(exc)}, status_code=500)

agentdom/dispatch.py

@@ -0,0 +1,103 @@
+"""
+agentdom.dispatch — dispatch_intent() for calling any AgentDOM-compatible service.
+
+This is the consumer-side function. It fetches the manifest from a host,
+finds the capability matching the intent, and executes it via the declared transport.
+"""
+
+import os
+import json
+from typing import Any, Optional
+
+
+async def dispatch_intent(
+    intent: str,
+    args: dict,
+    host: str,
+    token: Optional[str] = None,
+    agentdom_api: Optional[str] = None,
+) -> Any:
+    """
+    Dispatch an intent to an AgentDOM-compatible host.
+
+    This is the main consumer-side function. It:
+      1. Fetches the /.well-known/agentdom.json manifest from the host
+      2. Finds the capability matching `intent`
+      3. Executes the call via the declared transport (api, browser, desktop)
+
+    Args:
+        intent:       Intent name, e.g. "issues.create"
+        args:         Intent arguments dict
+        host:         Target host, e.g. "github.com"
+        token:        Auth token (overrides env var lookup)
+        agentdom_api: AgentDOM API server URL (default: https://api.getagentdom.com)
+
+    Returns:
+        The result from the remote capability.
+
+    Raises:
+        ValueError: If the intent is not found in the manifest.
+        httpx.HTTPStatusError: If the HTTP request fails.
+
+    Example:
+        from agentdom import dispatch_intent
+
+        result = await dispatch_intent(
+            "issues.create",
+            {"title": "Bug in login", "body": "Steps to reproduce..."},
+            host="github.com",
+        )
+        print(result)  # → {"id": 42, "url": "https://github.com/..."}
+    """
+    try:
+        import httpx
+    except ImportError:
+        raise ImportError(
+            "agentdom dispatch requires httpx: pip install agentdom[dispatch]"
+        )
+
+    api_base = agentdom_api or os.environ.get("AGENTDOM_API_URL", "https://api.getagentdom.com")
+
+    # Resolve auth token from env if not provided
+    if not token:
+        env_key = host.upper().replace(".", "_") + "_TOKEN"
+        token = os.environ.get(env_key) or os.environ.get("AGENTDOM_TOKEN")
+
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    payload = {"intent": intent, "host": host, "args": args}
+
+    async with httpx.AsyncClient(timeout=30) as client:
+        res = await client.post(
+            f"{api_base}/api/agentdom/dispatch",
+            headers=headers,
+            json=payload,
+        )
+        res.raise_for_status()
+        data = res.json()
+        return data.get("result", data)
+
+
+def dispatch_intent_sync(
+    intent: str,
+    args: dict,
+    host: str,
+    token: Optional[str] = None,
+    agentdom_api: Optional[str] = None,
+) -> Any:
+    """
+    Synchronous version of dispatch_intent for non-async code.
+
+    Example:
+        from agentdom import dispatch_intent_sync
+
+        result = dispatch_intent_sync(
+            "repos.list",
+            {"username": "octocat"},
+            host="github.com",
+        )
+    """
+    import asyncio
+    return asyncio.run(dispatch_intent(intent, args, host, token, agentdom_api))

agentdom-3.6.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: agentdom
+Version: 3.6.0
+Summary: The universal runtime that makes every website, desktop app, and API accessible to AI agents — zero human in the loop.
+Project-URL: Homepage, https://getagentdom.com
+Project-URL: Documentation, https://getagentdom.com/docs/python
+Project-URL: Repository, https://github.com/RagavRida/agentdom
+Project-URL: Changelog, https://github.com/RagavRida/agentdom/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/RagavRida/agentdom/issues
+Author-email: Ragavendhra Machikatla <hi@getagentdom.com>
+License: MIT
+Keywords: agentdom,agents,ai,automation,browser,dispatch,llm,mcp,protocol,rpa
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: flask>=2.0; extra == 'all'
+Requires-Dist: httpx>=0.25; extra == 'all'
+Requires-Dist: uvicorn>=0.20; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: flake8>=7; extra == 'dev'
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dispatch
+Requires-Dist: httpx>=0.25; extra == 'dispatch'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.20; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# agentdom
+
+**The universal runtime that makes every website, desktop app, and API accessible to AI agents — zero human in the loop.**
+
+[![PyPI version](https://img.shields.io/pypi/v/agentdom?color=f97316&style=flat-square)](https://pypi.org/project/agentdom/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentdom?style=flat-square)](https://pypi.org/project/agentdom/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/RagavRida/agentdom/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/agentdom?label=npm&color=f97316&style=flat-square)](https://www.npmjs.com/package/agentdom)
+
+[Website](https://getagentdom.com) · [Docs](https://getagentdom.com/docs/python) · [GitHub](https://github.com/RagavRida/agentdom) · [npm package](https://www.npmjs.com/package/agentdom)
+
+---
+
+## Install
+
+```bash
+pip install agentdom
+```
+
+With framework support:
+
+```bash
+pip install "agentdom[flask]"    # Flask integration
+pip install "agentdom[fastapi]"  # FastAPI integration
+pip install "agentdom[dispatch]" # dispatch_intent() support (requires httpx)
+pip install "agentdom[all]"      # everything
+```
+
+## Quick start — dispatch an intent
+
+```python
+import asyncio
+from agentdom import dispatch_intent
+
+async def main():
+    # Create a GitHub issue — routes via REST API, no browser needed
+    result = await dispatch_intent(
+        "issues.create",
+        {
+            "title": "Login crash on iOS 17",
+            "body":  "Reproducible on iPhone 15 Pro",
+            "labels": ["bug", "mobile"],
+        },
+        host="github.com",
+    )
+    print(result)  # → {"id": 42, "url": "https://github.com/..."}
+
+asyncio.run(main())
+```
+
+Or synchronously:
+
+```python
+from agentdom import dispatch_intent_sync
+
+result = dispatch_intent_sync("repos.list", {"username": "octocat"}, host="github.com")
+```
+
+## Embed AgentDOM in your app
+
+### Flask
+
+```python
+from flask import Flask
+from agentdom import AgentDOM
+
+app = Flask(__name__)
+agent = AgentDOM(
+    host="api.myapp.com",
+    auth={"method": "api_key", "key_header": "Authorization"},
+)
+
+@agent.capability("todos.create", description="Create a new todo item",
+                  args={"title": {"type": "string", "required": True}})
+def create_todo(args):
+    return {"id": 1, "title": args["title"]}
+
+@agent.capability("todos.list", description="List all todo items")
+def list_todos(args):
+    return [{"id": 1, "title": "Buy milk"}]
+
+agent.register(app)
+
+# Now your app automatically serves:
+#   GET  /.well-known/agentdom.json  → manifest
+#   POST /api/agentdom/todos.create  → your handler
+#   POST /api/agentdom/todos.list    → your handler
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from agentdom import AgentDOM
+
+app = FastAPI()
+agent = AgentDOM(host="api.myapp.com")
+
+@agent.capability("orders.ship", description="Ship a pending order",
+                  args={"order_id": {"type": "string", "required": True}})
+async def ship_order(args):
+    # async handlers are fully supported
+    return await shipping_service.ship(args["order_id"])
+
+agent.register(app)
+```
+
+### Standalone manifest
+
+```python
+from agentdom import AgentDOM
+
+agent = AgentDOM(host="api.myapp.com")
+
+@agent.capability("items.create", description="Create an item")
+def create_item(args):
+    return {"created": True}
+
+# Get the manifest dict to serve however you like
+manifest = agent.manifest()
+print(manifest)
+# → {"version": "1.0", "host": "api.myapp.com", "capabilities": [...], ...}
+```
+
+## Auth configuration
+
+```python
+# API key
+agent = AgentDOM(
+    host="api.myapp.com",
+    auth={
+        "method": "api_key",
+        "key_header": "Authorization",
+        "key_format": "Bearer {token}",
+    },
+)
+
+# OAuth 2.0
+agent = AgentDOM(
+    host="api.myapp.com",
+    auth={
+        "method": "oauth2",
+        "auth_url":  "https://api.myapp.com/oauth/authorize",
+        "token_url": "https://api.myapp.com/oauth/token",
+        "scopes":    ["read", "write"],
+    },
+)
+
+# No auth (public API)
+agent = AgentDOM(host="api.myapp.com", auth={"method": "none"})
+```
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `AGENTDOM_API_URL` | Override the AgentDOM API server URL |
+| `AGENTDOM_TOKEN` | Default auth token for dispatch_intent |
+| `<HOST>_TOKEN` | Per-host token (e.g. `GITHUB_COM_TOKEN`) |
+
+## Agent Token Protocol
+
+Publishers can declare an `agent_tokens` endpoint so agents provision their own scoped tokens automatically:
+
+```python
+agent = AgentDOM(
+    host="api.myapp.com",
+    auth={
+        "method": "api_key",
+        "agent_tokens": {
+            "issue":  "POST https://api.myapp.com/agent-tokens",
+            "revoke": "DELETE https://api.myapp.com/agent-tokens/{id}",
+            "scopes": ["read", "write"],
+            "max_ttl_seconds": 86400,
+        },
+    },
+)
+```
+
+## Supported providers
+
+| Provider | Auth | Capabilities |
+|---|---|---|
+| `github.com` | Device Flow | repos, issues, PRs, actions (811) |
+| `linear.app` | OAuth 2.0 | issues, teams, cycles (8) |
+| `slack.com` | OAuth 2.0 | messages, channels (6) |
+| `notion.so` | OAuth 2.0 | pages, databases (6) |
+| `stripe.com` | API Key | payments, customers (442) |
+| `resend.com` | API Key | emails, domains (5) |
+
+More providers at [getagentdom.com/providers](https://getagentdom.com/providers).
+
+## License
+
+MIT © [Ragavendhra Machikatla](https://github.com/RagavRida)

agentdom-3.6.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+agentdom/__init__.py,sha256=5C2ICG7LQxobd23_FUUPe8G52bpb5ra712RVym_ZA9w,1150
+agentdom/core.py,sha256=t5agQmECgzVFb0Pi4ttzabEowLM3EYu9LTx6_QTYavU,7169
+agentdom/dispatch.py,sha256=ioERHOrE6nDRoyrbRC1xnXx7gZ4tpK4nHpH2q-RjL3c,3108
+agentdom-3.6.0.dist-info/METADATA,sha256=259ATgq64pPo1DttzQqM9KSPyKw_T_SZtNPe26owIIs,7482
+agentdom-3.6.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentdom-3.6.0.dist-info/RECORD,,

agentdom-3.6.0.dist-info/WHEEL

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