🐝 airanks-acp-agent

AIR (Artificial Intelligence Ranking) by airanks — AI optimization made visible. Check any site's AI Rank free at airanks.net (toolbar: airanks.net/toolbar).

This repo turns AIR into a callable ACP (Agent Communication Protocol) agent named airank. Any ACP client, hub, or catalog — BeeAI included — can POST /runs and ask airank for a site's AI rank the same way it would call any other agent. 🤖↔️📊

🗺️ Contents

🧠 What it does

AIR measures AI optimization — how often, and how well, an AI assistant like ChatGPT cites a given domain when answering real questions. airank is the ACP door into that data:

• 🎯 Domain lookup — send a hostname (stripe.com), get its AIR score (0–10), percentile, tracked citation stats, and AI-file posture (llms.txt, ai.txt, robots.txt AI-agent rules).
• 🔍 Search — send a phrase (payment processing), get matching domains, brands, and phrases that airanks tracks.
• ⏳ Graceful hydration — a domain brand-new to AIR triggers server-side hydration. airank polls and streams a "gathering…" progress message instead of guessing or hanging silently.

🏗️ Architecture

Four small modules, one job each:

flowchart LR
    subgraph client["📥 Any ACP client"]
        C["BeeAI hub / catalog\ncurl / other agent"]
    end

    subgraph agent_pkg["🐝 airanks_acp_agent"]
        server["server.py\n@server.agent(name=\"airank\")"]
        agentpy["agent.py\nparse → poll → format"]
        api["api.py\nAirClient (httpx)"]
        auth["auth.py\nresolve_token()"]
    end

    AIR[("☁️ AIR API\nairanks.net/api/v1")]

    C -- "POST /runs" --> server
    server -- "answer(text)" --> agentpy
    agentpy -- "domain() / search()" --> api
    api -- "Bearer token?" --> auth
    api -- "GET /v1/domains/{host}\nGET /v1/search?q=" --> AIR
    AIR -. "JSON" .-> api
    agentpy -. "streamed reply chunks" .-> server
    server -. "RunYield" .-> C

• 🌐 api.py — the async httpx client (AirClient): GET /v1/domains/{host}, GET /v1/search, GET /user, plus normalize_hostname().
• 🔑 auth.py — shared token resolution, identical across every AIR client.
• 🧩 agent.py — parses the caller's text, polls while a domain is pending, formats the reply.
• 🚪 server.py — registers the airank ACP agent and runs the server.

🔁 A lookup, step by step

The one behavior worth diagramming: a never-before-seen domain. Rather than fake a score, airank streams a progress chunk and polls until AIR finishes hydrating it (or the ~180s budget runs out):

sequenceDiagram
    autonumber
    participant U as ACP caller
    participant A as agent.py
    participant API as api.py (AirClient)
    participant AIR as AIR API

    U->>A: "stripe.com"
    A->>API: normalize_hostname() → domain()
    API->>AIR: GET /v1/domains/stripe.com
    AIR-->>API: data.ai_files.status = "pending"
    API-->>A: pending payload
    A-->>U: ⏳ "gathering data now, polling…"
    loop every AIR_POLL_SECONDS (default 20s)
        A->>API: domain()
        API->>AIR: GET /v1/domains/stripe.com
        alt still pending
            AIR-->>API: status = "pending"
        else ready
            AIR-->>API: status = "ready" + score
            API-->>A: final payload
            A-->>U: "**stripe.com** — AIR score 8/10 …"
        else 429 rate limited
            AIR-->>API: 429 + Retry-After
            A->>A: sleep(Retry-After)
        end
    end

📦 Install

pip install -e .

Requires Python 3.10+. Two runtime dependencies: acp-sdk (the official BeeAI/Linux Foundation Agent Communication Protocol server SDK) and httpx (uvicorn<0.36 is pinned transitively — see the comment in pyproject.toml).

🚀 Quickstart

airank-acp
# or: python -m airanks_acp_agent.server

Starts an ACP server on http://127.0.0.1:8000 speaking the standard ACP REST contract: GET /agents, GET /agents/airank, POST /runs, GET /runs/{run_id}, GET /runs/{run_id}/events. Override the bind address with AIR_ACP_HOST / AIR_ACP_PORT.

Call it like any ACP agent:

curl -s http://127.0.0.1:8000/runs \
  -H 'content-type: application/json' \
  -d '{"agent_name": "airank", "input": [{"role": "user", "parts": [{"content": "stripe.com"}]}]}'

📋 Behavior reference

🐝 Registering with a BeeAI / ACP catalog

If a local BeeAI platform is running (PLATFORM_URL, default http://127.0.0.1:8333), airank-acp self-registers as a provider on startup — nothing further to do. To register with a different hub or catalog by hand, point it at this server's base URL and /agents/airank manifest, e.g.:

beeai agent add http://127.0.0.1:8000

or add a provider entry {"location": "http://<host>:<port>"} via that catalog's own API. Set PRODUCTION_MODE=true to disable auto-registration (e.g. behind a reverse proxy in prod).

🔐 Shared authentication

One login works across every AIR client — the air CLI, the browser toolbar, the airanks Python SDK, and this agent. Run air login anywhere and this agent picks it up automatically. Resolution order:

🗂️ Layout

🧪 Testing

pip install -e ".[dev]"
pytest

🌐 The airanks family

acp-agent is one door into AIR among many — same API, same shared login, different front door:

See ../API-CONTRACT.md for the full wire contract every client shares.

📄 License

MIT — see LICENSE.