fetch-hackkit 0.1.0__py3-none-any.whl

fetch_hackkit/doctor.py

@@ -0,0 +1,209 @@
+"""Pre-submission checks: ``hackkit doctor``.
+
+Each check maps to a hackathon requirement (registered, discoverable via
+ASI:One, chat protocol, README with badges + address) and says how to fix it.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+import httpx
+
+from .register import lookup_agent, profile_url, resolve
+
+CHAT_PROTOCOL_DIGEST = "30a801ed3a83f9a0ff0a9f1e6fe958cb91da1fc2218b153df7b6cbf87bd33d62"
+BADGES = (
+    "![tag:innovationlab](https://img.shields.io/badge/innovationlab-3D8BD3)",
+    "![tag:hackathon](https://img.shields.io/badge/hackathon-5F43F1)",
+)
+
+
+@dataclass
+class Check:
+    name: str
+    status: str  # "ok" | "warn" | "fail"
+    detail: str = ""
+    fix: str = ""
+
+    @property
+    def icon(self) -> str:
+        return {"ok": "✅", "warn": "⚠️ ", "fail": "❌"}[self.status]
+
+
+def identity_from_seed(seed: str) -> tuple[str, str]:
+    """``(agent address, FET wallet address)`` for a seed, exactly as uAgents derives them."""
+    from cosmpy.aerial.wallet import LocalWallet
+    from cosmpy.crypto.keypairs import PrivateKey
+    from uagents.config import LEDGER_PREFIX
+    from uagents_core.identity import Identity, derive_key_from_seed
+
+    address = Identity.from_seed(seed, 0).address
+    wallet = LocalWallet(
+        PrivateKey(derive_key_from_seed(seed, LEDGER_PREFIX, 0)), prefix=LEDGER_PREFIX
+    )
+    return address, str(wallet.address())
+
+
+def check_seed() -> tuple[Check, str | None]:
+    seed = os.getenv("AGENT_SEED_PHRASE", "")
+    if not seed:
+        return Check(
+            "Seed phrase",
+            "fail",
+            "AGENT_SEED_PHRASE is not set",
+            "Run `hackkit seed` and put the phrase in .env",
+        ), None
+    if len(seed) < 24:
+        return Check(
+            "Seed phrase",
+            "warn",
+            "seed is short; anyone who guesses it owns your agent",
+            "Use `hackkit seed` for a long random phrase",
+        ), identity_from_seed(seed)[0]
+    address, wallet = identity_from_seed(seed)
+    return Check("Seed phrase", "ok", f"address {address}\n      wallet  {wallet}"), address
+
+
+def check_asi1() -> Check:
+    key = os.getenv("ASI_ONE_API_KEY") or os.getenv("ASI1_API_KEY")
+    if not key:
+        return Check(
+            "ASI:One API key",
+            "warn",
+            "ASI_ONE_API_KEY is not set",
+            "Get one at https://asi1.ai/developer (only needed if you call the LLM)",
+        )
+    try:
+        resp = httpx.post(
+            "https://api.asi1.ai/v1/chat/completions",
+            headers={"Authorization": f"Bearer {key}"},
+            json={
+                "model": os.getenv("ASI_ONE_MODEL", "asi1"),
+                "max_tokens": 1,
+                "messages": [{"role": "user", "content": "ping"}],
+            },
+            timeout=30.0,
+        )
+    except httpx.HTTPError as exc:
+        return Check("ASI:One API key", "warn", f"could not reach ASI:One: {exc}")
+    if resp.status_code in (401, 403):
+        return Check(
+            "ASI:One API key",
+            "fail",
+            "key rejected",
+            "Create a new key at https://asi1.ai/developer",
+        )
+    if resp.status_code >= 400:
+        return Check("ASI:One API key", "warn", f"HTTP {resp.status_code}: {resp.text[:200]}")
+    return Check("ASI:One API key", "ok", "key works")
+
+
+def check_registration(address: str) -> Check:
+    if not os.getenv("AGENTVERSE_API_KEY"):
+        return Check(
+            "Agentverse account",
+            "warn",
+            "AGENTVERSE_API_KEY is not set (cannot check)",
+            "Create one at https://agentverse.ai/profile/api-keys",
+        )
+    try:
+        record = lookup_agent(address)
+    except RuntimeError as exc:
+        return Check("Agentverse account", "fail", str(exc))
+    if record is None:
+        return Check(
+            "Agentverse account",
+            "fail",
+            "agent is not on your Agentverse account",
+            "Run the agent with AGENTVERSE_API_KEY set (auto-connect), or open the "
+            "inspector link and click Connect -> Mailbox",
+        )
+    return Check("Agentverse account", "ok", profile_url(address))
+
+
+def check_almanac(address: str) -> Check:
+    try:
+        record = resolve(address)
+    except (RuntimeError, httpx.HTTPError) as exc:
+        return Check("Almanac / ASI:One discoverability", "warn", f"lookup failed: {exc}")
+    if record is None:
+        return Check(
+            "Almanac / ASI:One discoverability",
+            "fail",
+            "agent is not on the Almanac",
+            "Start the agent and connect it to Agentverse (mailbox)",
+        )
+    problems = []
+    if record.get("status") != "active":
+        problems.append(f"status is {record.get('status')!r} (start the agent)")
+    if CHAT_PROTOCOL_DIGEST not in (record.get("protocols") or []):
+        problems.append("chat protocol not published (include it with publish_manifest=True)")
+    expiry = record.get("expiry")
+    if expiry:
+        when = datetime.fromisoformat(str(expiry).replace("Z", "+00:00"))
+        if when < datetime.now(UTC):
+            problems.append("registration expired (restart the agent)")
+    if problems:
+        return Check("Almanac / ASI:One discoverability", "fail", "; ".join(problems))
+    return Check(
+        "Almanac / ASI:One discoverability",
+        "ok",
+        f"active, chat protocol published, type {record.get('type')}",
+    )
+
+
+def check_handle(handle: str, address: str) -> Check:
+    try:
+        record = resolve(handle)
+    except (RuntimeError, httpx.HTTPError) as exc:
+        return Check("@handle", "warn", f"lookup failed: {exc}")
+    if record is None:
+        return Check(
+            "@handle",
+            "fail",
+            f"@{handle} is not assigned yet",
+            "Pass handle=... to HackAgent and reconnect to Agentverse",
+        )
+    if record.get("address") != address:
+        return Check(
+            "@handle", "fail", f"@{handle} belongs to another agent", "Choose a different handle"
+        )
+    return Check("@handle", "ok", f"@{handle} -> this agent")
+
+
+def check_readme(path: Path, address: str | None) -> Check:
+    if not path.exists():
+        return Check("README", "fail", f"{path} not found", "Your repo needs a README")
+    text = path.read_text(encoding="utf-8")
+    missing = [b for b in BADGES if b not in text]
+    problems = []
+    if missing:
+        problems.append("missing badge(s): " + ", ".join(b.split("]")[0][2:] for b in missing))
+    if address and address not in text:
+        problems.append("agent address not listed")
+    if problems:
+        return Check(
+            "README",
+            "fail",
+            "; ".join(problems),
+            "Add the innovationlab + hackathon badges and your agent name + address",
+        )
+    return Check("README", "ok", "badges and address present")
+
+
+def run(*, readme: Path, handle: str | None) -> list[Check]:
+    checks: list[Check] = []
+    seed_check, address = check_seed()
+    checks.append(seed_check)
+    checks.append(check_asi1())
+    if address:
+        checks.append(check_registration(address))
+        checks.append(check_almanac(address))
+        if handle:
+            checks.append(check_handle(handle.removeprefix("@"), address))
+    checks.append(check_readme(readme, address))
+    return checks

fetch_hackkit/mcp.py

@@ -0,0 +1,93 @@
+"""Use any remote MCP server's tools from your agent (``pip install fetch-hackkit[mcp]``).
+
+    tools = await mcp_tools("https://mcp.deepwiki.com/mcp")
+    answer = await ASI1().run_tools("How do uAgents handle mailboxes?", tools=tools)
+
+Each tool call opens a short-lived connection, so there is nothing to keep
+alive or clean up. To go the other way (publish an MCP server *as* an agent
+on Agentverse), use ``uagents-adapter[mcp]``'s ``MCPServerAdapter``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .asi1 import Tool
+
+try:
+    import httpx2
+    from mcp import Client
+    from mcp.client.streamable_http import streamable_http_client
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("MCP support needs the extra: pip install 'fetch-hackkit[mcp]'") from exc
+
+# The MCP transport logs every HTTP request at INFO; keep agent logs readable.
+logging.getLogger("httpx2").setLevel(logging.WARNING)
+
+
+def _client(url: str, headers: dict[str, str] | None) -> Client:
+    if not headers:
+        return Client(url)
+    http = httpx2.AsyncClient(headers=headers, timeout=httpx2.Timeout(30.0, read=300.0))
+    return Client(streamable_http_client(url, http_client=http))
+
+
+def _result_text(result: Any) -> Any:
+    if getattr(result, "structured_content", None) is not None:
+        return result.structured_content
+    parts = [getattr(block, "text", None) or str(block) for block in result.content or []]
+    text = "\n".join(p for p in parts if p)
+    if getattr(result, "is_error", False):
+        return {"error": text or "tool failed"}
+    return text
+
+
+async def call_mcp_tool(
+    url: str,
+    name: str,
+    arguments: dict[str, Any] | None = None,
+    *,
+    headers: dict[str, str] | None = None,
+) -> Any:
+    """Call one tool on a remote MCP server and return its text/structured result."""
+    async with _client(url, headers) as client:
+        return _result_text(await client.call_tool(name, arguments or {}))
+
+
+async def mcp_tools(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    include: set[str] | None = None,
+    prefix: str = "",
+) -> list[Tool]:
+    """List a server's tools as :class:`~fetch_hackkit.asi1.Tool` objects for ``run_tools``.
+
+    Args:
+        url: Streamable-HTTP MCP endpoint, e.g. ``https://mcp.deepwiki.com/mcp``.
+        headers: Extra HTTP headers, e.g. ``{"Authorization": "Bearer ..."}``.
+        include: Only expose these tool names (keeps the model focused).
+        prefix: Prepended to tool names to avoid clashes between servers.
+    """
+    async with _client(url, headers) as client:
+        listed = await client.list_tools()
+
+    tools: list[Tool] = []
+    for spec in listed.tools:
+        if include and spec.name not in include:
+            continue
+
+        async def call(arguments: dict[str, Any], _name: str = spec.name) -> Any:
+            return await call_mcp_tool(url, _name, arguments, headers=headers)
+
+        schema = dict(spec.input_schema or {"type": "object", "properties": {}})
+        tools.append(
+            Tool(
+                name=f"{prefix}{spec.name}",
+                description=spec.description or spec.name,
+                parameters=schema,
+                call=call,
+            )
+        )
+    return tools

fetch_hackkit/payments.py

@@ -0,0 +1,264 @@
+"""Agent Payment Protocol (seller side) with on-chain FET verification.
+
+You normally use this through ``@agent.paid(...)``::
+
+    @agent.paid("brief", amount="0.1", description="AI project brief")
+    async def brief(ctx, msg, sel):
+        return "Here is your brief..."
+
+Flow (``uagents_core.contrib.protocols.payment``)::
+
+    you  -> user : RequestPayment(accepted_funds=[0.1 FET], recipient=<agent wallet>, reference)
+    user -> you  : CommitPayment(transaction_id, reference)      (or RejectPayment)
+    you          : verify the transfer on-chain (cosmpy)
+    you  -> user : CompletePayment(transaction_id) and the paid result
+                   (or CancelPayment(reason) if verification fails)
+
+Defaults to the Fetch.ai **stable testnet** (free test FET from the faucet).
+Set ``FET_NETWORK=mainnet`` for real money.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+from uagents import Context, Protocol
+from uagents_core.contrib.protocols.payment import (
+    CancelPayment,
+    CommitPayment,
+    CompletePayment,
+    Funds,
+    RejectPayment,
+    RequestPayment,
+    payment_protocol_spec,
+)
+
+if TYPE_CHECKING:
+    from .agent import ActionHandler, HackAgent, Inbound, Reply
+
+FET_DECIMALS = 18
+DEFAULT_DEADLINE_SECONDS = 600
+
+
+def fet_network() -> str:
+    """``stable-testnet`` (default) or ``mainnet``, from ``FET_NETWORK``."""
+    return "mainnet" if os.getenv("FET_NETWORK", "").lower() == "mainnet" else "stable-testnet"
+
+
+@dataclass
+class Product:
+    name: str
+    amount: str
+    currency: str
+    description: str
+    handler: ActionHandler
+
+
+def build_request(
+    *,
+    amount: str,
+    recipient_wallet: str,
+    description: str,
+    currency: str = "FET",
+    reference: str | None = None,
+    deadline_seconds: int = DEFAULT_DEADLINE_SECONDS,
+    network: str | None = None,
+) -> RequestPayment:
+    """A ``RequestPayment`` for a direct FET transfer to ``recipient_wallet``."""
+    network = network or fet_network()
+    return RequestPayment(
+        accepted_funds=[Funds(amount=amount, currency=currency, payment_method="fet_direct")],
+        recipient=recipient_wallet,
+        deadline_seconds=deadline_seconds,
+        reference=reference or str(uuid4()),
+        description=description,
+        metadata={"fet_network": network, "provider_agent_wallet": recipient_wallet},
+    )
+
+
+def _amount_ok(amount: str, expected_base_units: int, denom: str) -> bool:
+    if not amount.endswith(denom):
+        return False
+    try:
+        return int(amount[: -len(denom)]) >= expected_base_units
+    except ValueError:
+        return False
+
+
+def verify_fet_transfer(
+    *,
+    transaction_id: str,
+    amount: str,
+    recipient_wallet: str,
+    sender_wallet: str | None = None,
+    network: str | None = None,
+) -> tuple[bool, str]:
+    """Check on-chain that ``transaction_id`` sent at least ``amount`` FET to us.
+
+    Blocking (network I/O): call it via ``asyncio.to_thread``.
+    Returns ``(ok, reason)``.
+    """
+    from cosmpy.aerial.client import LedgerClient, NetworkConfig
+
+    mainnet = (network or fet_network()) == "mainnet"
+    denom = "afet" if mainnet else "atestfet"
+    expected = int(Decimal(amount) * (10**FET_DECIMALS))
+    config = NetworkConfig.fetchai_mainnet() if mainnet else NetworkConfig.fetchai_stable_testnet()
+    try:
+        tx = LedgerClient(config).query_tx(transaction_id)
+    except Exception as exc:
+        return False, f"transaction not found yet ({type(exc).__name__})"
+    if tx is None:
+        return False, "transaction not found"
+    if hasattr(tx, "is_successful") and not tx.is_successful():
+        return False, "transaction failed on-chain"
+    events = getattr(tx, "events", None)
+    if not isinstance(events, dict):
+        return False, "transaction has no events"
+
+    transfer = events.get("transfer") or {}
+    received = events.get("coin_received") or {}
+    spent = events.get("coin_spent") or {}
+    to_us = recipient_wallet in (transfer.get("recipient"), received.get("receiver"))
+    paid_enough = _amount_ok(str(transfer.get("amount", "")), expected, denom) or _amount_ok(
+        str(received.get("amount", "")), expected, denom
+    )
+    from_buyer = sender_wallet is None or sender_wallet in (
+        transfer.get("sender"),
+        spent.get("spender"),
+    )
+    if not to_us:
+        return False, "transfer was not to this agent's wallet"
+    if not paid_enough:
+        return False, f"amount is less than {amount} FET"
+    if not from_buyer:
+        return False, "transfer did not come from the buyer's wallet"
+    return True, "verified"
+
+
+class Paywall:
+    """Seller-side payment protocol attached to a :class:`HackAgent`."""
+
+    def __init__(self, agent: HackAgent) -> None:
+        self.agent = agent
+        self.products: dict[str, Product] = {}
+        self.protocol = Protocol(spec=payment_protocol_spec, role="seller")
+        self.protocol.on_message(CommitPayment)(self._on_commit)
+        self.protocol.on_message(RejectPayment)(self._on_reject)
+        agent.include(self.protocol, publish_manifest=True)
+
+    @property
+    def wallet(self) -> str:
+        return str(self.agent.wallet.address())
+
+    def add(self, product: Product) -> None:
+        self.products[product.name] = product
+
+    async def request(self, ctx: Context, msg: Inbound, name: str, sel: dict[str, Any]) -> Reply:
+        product = self.products[name]
+        reference = str(uuid4())
+        ctx.storage.set(
+            f"hackkit:pay:{reference}",
+            {
+                "product": name,
+                "sender": msg.sender,
+                "text": msg.text,
+                "session": msg.session,
+                "selection": sel,
+                "expires": time.time() + DEFAULT_DEADLINE_SECONDS,
+            },
+        )
+        await ctx.send(
+            msg.sender,
+            build_request(
+                amount=product.amount,
+                currency=product.currency,
+                recipient_wallet=self.wallet,
+                description=product.description,
+                reference=reference,
+            ),
+        )
+        net = "testnet " if fet_network() != "mainnet" else ""
+        return (
+            f"💳 **{product.description}** costs **{product.amount} {net}{product.currency}**. "
+            "Approve the payment request to continue."
+        )
+
+    async def _on_reject(self, ctx: Context, sender: str, msg: RejectPayment) -> None:
+        reason = f" ({msg.reason})" if msg.reason else ""
+        await self.agent.reply(ctx, sender, f"No problem, payment cancelled{reason}.")
+
+    async def _on_commit(self, ctx: Context, sender: str, msg: CommitPayment) -> None:
+        from .agent import Inbound, text_message
+
+        tx = msg.transaction_id
+        key = f"hackkit:pay:{msg.reference}"
+        pending = ctx.storage.get(key) if msg.reference else None
+        if ctx.storage.get(f"hackkit:paid-tx:{tx}"):
+            await ctx.send(sender, CompletePayment(transaction_id=tx))  # duplicate commit
+            return
+        if not isinstance(pending, dict) or pending.get("sender") != sender:
+            await ctx.send(
+                sender, CancelPayment(transaction_id=tx, reason="Unknown payment reference")
+            )
+            return
+        if time.time() > float(pending.get("expires", 0)):
+            ctx.storage.remove(key)
+            await ctx.send(
+                sender, CancelPayment(transaction_id=tx, reason="Payment request expired")
+            )
+            await self.agent.reply(ctx, sender, "That payment request expired. Please try again.")
+            return
+        product = self.products.get(str(pending["product"]))
+        if product is None:
+            await ctx.send(sender, CancelPayment(transaction_id=tx, reason="Unknown product"))
+            return
+
+        buyer = (msg.metadata or {}).get("buyer_fet_wallet") or (msg.metadata or {}).get(
+            "buyer_fet_address"
+        )
+        ok, reason = False, "not verified"
+        for attempt in range(3):  # the tx may take a few seconds to be indexed
+            ok, reason = await asyncio.to_thread(
+                verify_fet_transfer,
+                transaction_id=tx,
+                amount=product.amount,
+                recipient_wallet=self.wallet,
+                sender_wallet=buyer if isinstance(buyer, str) else None,
+            )
+            if ok or "not found" not in reason:
+                break
+            await asyncio.sleep(3 * (attempt + 1))
+        if not ok:
+            ctx.logger.warning(f"payment {tx} rejected: {reason}")
+            await ctx.send(sender, CancelPayment(transaction_id=tx, reason=reason))
+            await self.agent.reply(ctx, sender, f"I couldn't verify that payment: {reason}.")
+            return
+
+        ctx.storage.set(f"hackkit:paid-tx:{tx}", True)
+        ctx.storage.remove(key)
+        await ctx.send(sender, CompletePayment(transaction_id=tx))
+        ctx.logger.info(f"payment {tx} verified for {product.name}")
+
+        inbound = Inbound(
+            sender=sender,
+            text=str(pending.get("text", "")),
+            session=str(pending.get("session", "")),
+            raw=text_message(str(pending.get("text", ""))),
+            selection=dict(pending.get("selection") or {}),
+        )
+        try:
+            reply = await product.handler(ctx, inbound, inbound.selection)
+        except Exception:
+            ctx.logger.exception("paid handler failed")
+            reply = (
+                "Payment received, but something failed while preparing your result. "
+                f"Please contact the agent owner with transaction id {tx}."
+            )
+        await self.agent.reply(ctx, sender, reply)

fetch_hackkit/peers.py

@@ -0,0 +1,40 @@
+"""Talk to other agents over the chat protocol (multi-agent patterns).
+
+    answer = await ask_agent(ctx, "@weather-agent", "Forecast for Berkeley tomorrow?")
+
+Works with any chat-protocol agent on Agentverse, including ones you did not write.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+
+from uagents import Context
+from uagents_core.contrib.protocols.chat import ChatAcknowledgement, ChatMessage
+
+from .agent import text_message
+from .register import resolve_address
+
+
+class PeerError(RuntimeError):
+    pass
+
+
+async def ask_agent(ctx: Context, agent: str, text: str, *, timeout: int = 60) -> str:
+    """Send ``text`` to ``agent`` (address or ``@handle``) and wait for its text reply.
+
+    The peer's ``ChatAcknowledgement`` is skipped; its next ``ChatMessage`` in this
+    session is the answer. Raises :class:`PeerError` on delivery failure or timeout.
+    """
+    address = await asyncio.to_thread(resolve_address, agent)
+    reply, status = await ctx.send_and_receive(
+        address, text_message(text), response_type=ChatMessage, timeout=timeout
+    )
+    if not isinstance(reply, ChatMessage):
+        raise PeerError(f"{agent} did not answer: {getattr(status, 'detail', status)}")
+    await ctx.send(
+        address,
+        ChatAcknowledgement(timestamp=datetime.now(UTC), acknowledged_msg_id=reply.msg_id),
+    )
+    return reply.text()