fetch-hackkit 0.1.0__py3-none-any.whl

fetch_hackkit/register.py

@@ -0,0 +1,240 @@
+"""Agentverse registration: mailbox connect, endpoint registration, profile lookup.
+
+Where each profile field is set:
+
+==================  =====================================  =========================
+Field               Set in code (this module / HackAgent)  Agentverse MCP tool
+==================  =====================================  =========================
+name                ``HackAgent(name=...)``                ``update_user_agent``
+@handle             ``HackAgent(handle=...)``              *not available*
+short description   ``HackAgent(description=...)``         ``update_user_agent``
+README              ``HackAgent(readme_path=...)``         ``update_user_agent``
+avatar              ``HackAgent(avatar_url=...)``          ``update_user_agent``
+==================  =====================================  =========================
+
+The ``@handle`` is unique across Agentverse (max 40 chars). If it is taken,
+registration fails with HTTP 409.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from uagents import Agent
+
+HANDLE_MAX_LEN = 40
+_HANDLE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+AGENTVERSE_URL = "https://agentverse.ai"
+
+
+def validate_handle(handle: str) -> str:
+    """Check an Agentverse ``@handle`` locally and return it without a leading ``@``."""
+    value = handle.removeprefix("@")
+    if not value or len(value) > HANDLE_MAX_LEN:
+        raise ValueError(f"handle must be 1-{HANDLE_MAX_LEN} characters, got {len(value)}")
+    if not _HANDLE_RE.match(value):
+        raise ValueError(
+            f"handle {handle!r} may only contain letters, digits, '-', '_' and '.' (no spaces)"
+        )
+    return value
+
+
+def profile_url(address: str) -> str:
+    return f"{AGENTVERSE_URL}/agents/details/{address}/profile"
+
+
+def _api_key(api_key: str | None) -> str:
+    key = api_key or os.getenv("AGENTVERSE_API_KEY")
+    if not key:
+        raise ValueError(
+            "AGENTVERSE_API_KEY is not set. Create one at https://agentverse.ai/profile/api-keys"
+        )
+    return key
+
+
+def _detail(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+        detail = body.get("detail", body) if isinstance(body, dict) else body
+    except ValueError:
+        detail = resp.text
+    hint = ""
+    if resp.status_code == 401:
+        hint = " (invalid or expired AGENTVERSE_API_KEY)"
+    elif resp.status_code == 409:
+        hint = " (address or @handle already registered by another account; pick another handle)"
+    return f"HTTP {resp.status_code}{hint}: {detail}"
+
+
+@dataclass
+class ConnectResult:
+    ok: bool
+    detail: str = ""
+    address: str = ""
+
+    @property
+    def profile_url(self) -> str:
+        return profile_url(self.address)
+
+
+def _registration_body(agent: Agent, endpoint: str | None) -> str:
+    """The same ``RegistrationRequest`` the inspector's Connect button sends."""
+    from uagents_core.registration import RegistrationRequest
+
+    request = RegistrationRequest(
+        address=agent.address,
+        name=agent.name,
+        handle=agent._handle,
+        url=endpoint,
+        profile=agent._build_registration_profile(),
+        endpoints=agent._endpoints,
+        protocols=list(agent.protocols.keys()),
+        metadata=agent.metadata,
+    )
+    return request.model_dump_json()
+
+
+async def connect_mailbox(
+    agent: Agent,
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    timeout: float = 15.0,
+) -> ConnectResult:
+    """Do what the inspector's *Connect* button does, using ``AGENTVERSE_API_KEY``.
+
+    Proves the agent owns its address (signed challenge), then publishes its
+    profile (name, @handle, description, README, protocols) to Agentverse.
+    For an agent with its own public URL, use :func:`register_endpoint_agent`.
+    """
+    key = _api_key(api_key)
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    av = agent._agentverse
+    identity = agent._identity
+    async with httpx.AsyncClient(timeout=timeout, headers=headers) as client:
+        try:
+            resp = await client.get(f"{av.identity_api}/{identity.address}/challenge")
+            if resp.status_code != 200:
+                return ConnectResult(False, "challenge: " + _detail(resp), agent.address)
+            challenge = resp.json()["challenge"]
+            proof = {
+                "address": identity.address,
+                "challenge": challenge,
+                "challenge_response": identity.sign(challenge.encode()),
+            }
+            resp = await client.post(av.identity_api, json=proof)
+            if resp.status_code != 200:
+                return ConnectResult(False, "identity proof: " + _detail(resp), agent.address)
+            body = _registration_body(agent, endpoint)
+            resp = await client.post(av.agents_api, content=body)
+            if resp.status_code not in (200, 201):
+                return ConnectResult(False, "register: " + _detail(resp), agent.address)
+            handle = agent._handle
+            if handle:
+                # Agentverse ignores `handle` when it first creates an agent and only
+                # applies it on an update, so read it back and send the update if needed.
+                record = await client.get(f"{av.agents_api}/{agent.address}")
+                if record.status_code == 200 and record.json().get("handle") != handle:
+                    resp = await client.post(av.agents_api, content=body)
+                    if resp.status_code not in (200, 201):
+                        return ConnectResult(False, "set handle: " + _detail(resp), agent.address)
+                    record = await client.get(f"{av.agents_api}/{agent.address}")
+                    if record.status_code == 200 and record.json().get("handle") != handle:
+                        return ConnectResult(
+                            True,
+                            f"connected, but Agentverse did not apply @{handle}",
+                            agent.address,
+                        )
+        except httpx.HTTPError as exc:
+            return ConnectResult(False, f"network error: {exc}", agent.address)
+    return ConnectResult(True, "", agent.address)
+
+
+def register_endpoint_agent(agent: Agent, endpoint: str, *, api_key: str | None = None) -> bool:
+    """Register an agent that runs at a public URL (Render, Fly, a VM, ...).
+
+    Uses ``uagents_core``'s ``register_agent`` (which, unlike ``register_chat_agent``,
+    accepts a ``handle``). Raises ``AgentverseRequestError`` on failure.
+    """
+    from uagents_core.config import AgentverseConfig
+    from uagents_core.utils.registration import (
+        AgentverseRegistrationRequest,
+        RegistrationRequestCredentials,
+        register_agent,
+    )
+
+    profile = agent._build_registration_profile()
+    request = AgentverseRegistrationRequest(
+        name=agent.name,
+        endpoint=endpoint,
+        protocols=list(agent.protocols.keys()),
+        description=profile.description or None,
+        readme=profile.readme or None,
+        avatar_url=profile.avatar_url or None,
+        handle=agent._handle,
+        active=True,
+    )
+    seed = os.getenv("AGENT_SEED_PHRASE")
+    if not seed:
+        raise ValueError("AGENT_SEED_PHRASE is not set")
+    credentials = RegistrationRequestCredentials(
+        agentverse_api_key=_api_key(api_key), agent_seed_phrase=seed
+    )
+    ok = register_agent(request, AgentverseConfig(), credentials)
+    record = lookup_agent(agent.address, api_key=api_key) if agent._handle else None
+    if record is not None and record.get("handle") != agent._handle:
+        # The handle only applies on update (see connect_mailbox).
+        ok = register_agent(request, AgentverseConfig(), credentials)
+    return ok
+
+
+def lookup_agent(address: str, *, api_key: str | None = None) -> dict[str, Any] | None:
+    """Your Agentverse record for ``address`` (``None`` if it is not on your account)."""
+    resp = httpx.get(
+        f"{AGENTVERSE_URL}/v2/agents/{address}",
+        headers={"Authorization": f"Bearer {_api_key(api_key)}"},
+        timeout=15.0,
+    )
+    if resp.status_code == 404:
+        return None
+    if resp.status_code != 200:
+        raise RuntimeError(_detail(resp))
+    data = resp.json()
+    return data if isinstance(data, dict) else None
+
+
+def resolve(identifier: str) -> dict[str, Any] | None:
+    """Public Almanac lookup by address, ``@handle`` or domain; ``None`` if unassigned.
+
+    Returns ``{"address", "status", "type", "protocols", "endpoints", "expiry", ...}``.
+    """
+    ident = identifier.removeprefix("@")
+    resp = httpx.get(f"{AGENTVERSE_URL}/v2/almanac/resolve/{ident}", timeout=15.0)
+    if resp.status_code == 404:
+        return None
+    if resp.status_code != 200:
+        raise RuntimeError(_detail(resp))
+    data = resp.json()
+    return data if isinstance(data, dict) else None
+
+
+def handle_available(handle: str, *, mine: str | None = None) -> bool:
+    """True if nobody (other than address ``mine``) has taken ``handle``."""
+    record = resolve(validate_handle(handle))
+    return record is None or (mine is not None and record.get("address") == mine)
+
+
+def resolve_address(identifier: str) -> str:
+    """``agent1...`` passes through; ``@handle``/domain is looked up on the Almanac."""
+    if identifier.startswith(("agent1", "test-agent1")):
+        return identifier
+    record = resolve(identifier)
+    if not record or not record.get("address"):
+        raise ValueError(f"no agent found for {identifier!r}")
+    return str(record["address"])

fetch_hackkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: fetch-hackkit
+Version: 0.1.0
+Summary: Batteries for Fetch.ai hackathon agents: chat protocol, ASI:One interactive cards, ASI:One LLM + tools, payments, MCP, and Agentverse registration.
+Project-URL: Homepage, https://github.com/adylagad/fetch-hackathon-starter
+Project-URL: Documentation, https://github.com/adylagad/fetch-hackathon-starter/blob/main/AGENTS.md
+Project-URL: Issues, https://github.com/adylagad/fetch-hackathon-starter/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,agentverse,asi1,fetch.ai,hackathon,uagents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.50
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uagents-core>=0.4.12
+Requires-Dist: uagents<0.28,>=0.26.1
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# fetch-hackkit
+
+Batteries for [Fetch.ai](https://fetch.ai) hackathon agents. Build a uAgent that works inside ASI:One in a few lines:
+
+- **Chat protocol** done for you: acknowledgements, sessions, `@mention` stripping, friendly error replies.
+- **ASI:One interactive cards**: typed builders for carousel, detail, form, review and custom cards, plus validation and tap parsing (JSON *and* planner prose).
+- **ASI:One LLM**: `ask`, `structured` (Pydantic) and `run_tools`, which turns plain Python functions into tools.
+- **Payments**: `@agent.paid(...)` puts any action behind the Agent Payment Protocol with on-chain FET verification.
+- **MCP**: use any remote MCP server's tools from your agent.
+- **Multi-agent**: `ask_agent(ctx, "@handle", "question")`.
+- **Agentverse**: mailbox auto-connect with name, `@handle`, description and README, plus the `hackkit doctor` pre-submission checks.
+
+```bash
+pip install fetch-hackkit          # or: pip install "fetch-hackkit[mcp]"
+```
+
+```python
+from fetch_hackkit import HackAgent, cards
+
+agent = HackAgent(name="Trip Planner", handle="trip-planner", readme_path="README.md")
+
+@agent.on_text
+async def on_text(ctx, msg):
+    return cards.carousel("Pick a city", [cards.item("sf", "San Francisco", action="plan")])
+
+@agent.on_action("plan")
+async def plan(ctx, msg, sel):
+    return f"Planning {sel['id']}..."
+
+agent.run()
+```
+
+Environment (`.env` is loaded automatically):
+- `AGENT_SEED_PHRASE` (required; generate with `hackkit seed`)
+- `ASI_ONE_API_KEY`
+- `AGENTVERSE_API_KEY`
+- `AGENT_HANDLE`
+
+## CLI
+
+```
+hackkit seed            generate a secure seed phrase (+ its address and wallet)
+hackkit whoami          address, wallet and Agentverse profile URL for your seed
+hackkit handle NAME     is @NAME free on Agentverse?
+hackkit doctor          check the agent against hackathon submission requirements
+```
+
+The starter repo, full docs and showcase agent are at https://github.com/adylagad/fetch-hackathon-starter. Requires Python 3.11+, `uagents` 0.26+ and `uagents-core` 0.4.12+. MIT licensed.

fetch_hackkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+fetch_hackkit/__init__.py,sha256=10LI3Rm0c-VmnMeweOoq37-_euhtjIRZaxhb6t-7-w4,729
+fetch_hackkit/agent.py,sha256=06tUKS_tURCJelGw4JV57MaYR5rGdWSi_AALBGFahtg,12865
+fetch_hackkit/asi1.py,sha256=CUH6GG7DqEQF3bC4srZ3Wlr6GGeKxi1J7Pkwxomf1N8,11321
+fetch_hackkit/cards.py,sha256=nPYfLFFMkHz5HPmCt3CuhackYO0E49uUl7gLhFT2sCI,18618
+fetch_hackkit/cli.py,sha256=9sbIxNTmT_Zr-5TaDMXdScDPfTYHS83lSZTee7tEEhY,3047
+fetch_hackkit/doctor.py,sha256=HbyNLhM_VDTTmS3NhbNWCZzE0PSgNVORrgCkUYs3ZpY,7374
+fetch_hackkit/mcp.py,sha256=ZdU_xTShDS50WTkvncARGxUXB0IgLxhfvxhI6m3l8ec,3273
+fetch_hackkit/payments.py,sha256=k0M-n8Yh5HHKarVR1XpxHXIgWKHt5ZR5l5hef8wzJ3c,9780
+fetch_hackkit/peers.py,sha256=pnfdw86KjAXtcJmKOtgsG0xQSmW22PAywH2967JaDf8,1399
+fetch_hackkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fetch_hackkit/register.py,sha256=ZTRsM-zfAvXg_7VtuE76TEXLLU2dk9fB_OCU5kjHj6k,9610
+fetch_hackkit-0.1.0.dist-info/METADATA,sha256=fBofvP5BVsDD0dRWzLHxPsLE61bEvHrAffCEkfo0NxY,3100
+fetch_hackkit-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fetch_hackkit-0.1.0.dist-info/entry_points.txt,sha256=q4jE2XuDrXcHO9S2PB2j-G4w1zaXu2I7KnZNnzGx-NY,51
+fetch_hackkit-0.1.0.dist-info/licenses/LICENSE,sha256=5gBVHjA8rbq1fHVmCGulYLk0PujDeuPnj-TS9HnhhTc,1065
+fetch_hackkit-0.1.0.dist-info/RECORD,,

fetch_hackkit-0.1.0.dist-info/WHEEL

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

fetch_hackkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hackkit = fetch_hackkit.cli:main

fetch_hackkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adylagad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.