fetch-hackkit 0.1.0__py3-none-any.whl

fetch_hackkit/__init__.py

@@ -0,0 +1,33 @@
+"""fetch-hackkit: batteries for Fetch.ai hackathon agents.
+
+from fetch_hackkit import HackAgent, cards, ASI1
+"""
+
+from . import cards
+from .agent import HackAgent, Inbound, Reply, text_message
+from .asi1 import ASI1, ASI1Error, Tool, history, remember, tool
+from .cards import Card, CardError, parse_selection
+from .register import connect_mailbox, handle_available, resolve, validate_handle
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ASI1",
+    "ASI1Error",
+    "Card",
+    "CardError",
+    "HackAgent",
+    "Inbound",
+    "Reply",
+    "Tool",
+    "cards",
+    "connect_mailbox",
+    "handle_available",
+    "history",
+    "parse_selection",
+    "remember",
+    "resolve",
+    "text_message",
+    "tool",
+    "validate_handle",
+]

fetch_hackkit/agent.py

@@ -0,0 +1,340 @@
+"""``HackAgent``: a uAgent that already speaks the Agent Chat Protocol.
+
+What you get over a plain ``uagents.Agent``:
+
+* the chat protocol is included and its manifest published (ASI:One needs this);
+* every message is acknowledged, session start/end content is handled;
+* ``@agent.on_text`` receives clean text (leading ``@handle`` mentions removed);
+* ``@agent.on_action("name")`` receives interactive-card taps, already parsed;
+* handlers just *return* a reply: ``str``, :class:`~fetch_hackkit.cards.Card`,
+  ``ChatMessage``, or a list of those;
+* if a handler raises, the user gets a friendly message instead of silence;
+* ``@agent.paid(...)`` puts any action behind the Payment Protocol;
+* with ``AGENTVERSE_API_KEY`` set, a mailbox agent connects itself to
+  Agentverse on startup (no inspector click), with name, ``@handle``,
+  description and README.
+
+It *is* a ``uagents.Agent``, so ``on_interval``, ``storage``, ``include`` and
+everything else still work.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import os
+import warnings
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, TypeAlias
+from uuid import uuid4
+
+from dotenv import find_dotenv, load_dotenv
+from uagents import Agent, Context, Protocol
+from uagents_core.contrib.protocols.chat import (
+    ChatAcknowledgement,
+    ChatMessage,
+    EndSessionContent,
+    MetadataContent,
+    StartSessionContent,
+    TextContent,
+    chat_protocol_spec,
+)
+
+from .cards import Card, collect_actions, parse_selection, strip_mention
+from .register import validate_handle
+
+if TYPE_CHECKING:
+    from .payments import Paywall
+
+DEFAULT_ERROR_MESSAGE = (
+    "Sorry, something went wrong on my side while handling that. Please try again in a moment."
+)
+
+ReplyPart: TypeAlias = str | Card | ChatMessage
+Reply: TypeAlias = ReplyPart | Sequence[ReplyPart] | None
+TextHandler: TypeAlias = Callable[[Context, "Inbound"], Awaitable[Reply]]
+ActionHandler: TypeAlias = Callable[[Context, "Inbound", dict[str, Any]], Awaitable[Reply]]
+
+
+@dataclass
+class Inbound:
+    """One user message, already unpacked."""
+
+    sender: str
+    text: str
+    """Text with leading ``@handle`` mentions stripped."""
+    session: str
+    """Conversation id; use it to key per-conversation state in ``ctx.storage``."""
+    raw: ChatMessage
+    metadata: dict[str, str] = field(default_factory=dict)
+    selection: dict[str, Any] = field(default_factory=dict)
+    """Parsed card tap (``{}`` for ordinary text)."""
+
+    @property
+    def action(self) -> str | None:
+        value = self.selection.get("action")
+        return str(value) if value else None
+
+
+def text_message(text: str, *, end_session: bool = False) -> ChatMessage:
+    """A plain chat-protocol text message."""
+    content: list[Any] = [TextContent(type="text", text=text)]
+    if end_session:
+        content.append(EndSessionContent(type="end-session"))
+    return ChatMessage(timestamp=datetime.now(UTC), msg_id=uuid4(), content=content)
+
+
+def to_messages(reply: Reply) -> list[ChatMessage]:
+    """Normalise anything a handler may return into chat messages."""
+    if reply is None:
+        return []
+    parts: Sequence[ReplyPart] = (
+        [reply] if isinstance(reply, str | Card | ChatMessage) else reply  # type: ignore[list-item]
+    )
+    out: list[ChatMessage] = []
+    for part in parts:
+        if isinstance(part, ChatMessage):
+            out.append(part)
+        elif isinstance(part, Card):
+            out.append(part.to_message())
+        elif isinstance(part, str):
+            if part.strip():
+                out.append(text_message(part))
+        else:
+            raise TypeError(f"handlers must return str, Card or ChatMessage, got {type(part)!r}")
+    return out
+
+
+def _event_loop() -> asyncio.AbstractEventLoop:
+    """The loop uAgents should use. On Python 3.14+ there is no implicit main-thread
+    loop, and ``uagents.Agent()`` at module level crashes without this."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            return asyncio.get_event_loop_policy().get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        return loop
+
+
+async def _maybe_await(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+class HackAgent(Agent):
+    """A chat-protocol-ready ``uagents.Agent``. See the module docstring."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        seed: str | None = None,
+        port: int | None = None,
+        mailbox: bool = True,
+        handle: str | None = None,
+        description: str | None = None,
+        readme_path: str | None = None,
+        avatar_url: str | None = None,
+        error_message: str = DEFAULT_ERROR_MESSAGE,
+        auto_connect: bool = True,
+        **agent_kwargs: Any,
+    ) -> None:
+        load_dotenv(find_dotenv(usecwd=True))
+        seed = seed or os.getenv("AGENT_SEED_PHRASE")
+        if not seed:
+            raise ValueError(
+                "No seed phrase. Set AGENT_SEED_PHRASE in .env to any long random phrase and keep "
+                "it secret: the seed *is* your agent's identity (address + wallet). "
+                "Run `hackkit seed` to generate one."
+            )
+        if handle:
+            validate_handle(handle)
+        agent_kwargs.setdefault("loop", _event_loop())
+        super().__init__(
+            name=name,
+            seed=seed,
+            port=port or int(os.getenv("AGENT_PORT", "8000")),
+            mailbox=mailbox,
+            handle=handle,
+            description=description,
+            readme_path=readme_path,
+            avatar_url=avatar_url,
+            publish_agent_details=True,
+            **agent_kwargs,
+        )
+        self.error_message = error_message
+        self._text_handler: TextHandler | None = None
+        self._action_handlers: dict[str, ActionHandler] = {}
+        self._known_actions: set[str] = set()
+        self._paywall: Paywall | None = None
+
+        self.chat_protocol = Protocol(spec=chat_protocol_spec)
+        self.chat_protocol.on_message(ChatMessage)(self._on_chat_message)
+        self.chat_protocol.on_message(ChatAcknowledgement)(self._on_chat_ack)
+        self.include(self.chat_protocol, publish_manifest=True)
+
+        if mailbox and auto_connect:
+            self.on_event("startup")(self._auto_connect)
+
+    # ------------------------------------------------------------------ #
+    # Decorators
+    # ------------------------------------------------------------------ #
+
+    def on_text(self, func: TextHandler) -> TextHandler:
+        """Handle ordinary text (and card taps with no matching ``on_action``)."""
+        self._text_handler = func
+        return func
+
+    def on_action(self, name: str) -> Callable[[ActionHandler], ActionHandler]:
+        """Handle card taps whose selection has ``{"action": name}``."""
+
+        def decorator(func: ActionHandler) -> ActionHandler:
+            self._action_handlers[name] = func
+            self._known_actions.add(name)
+            return func
+
+        return decorator
+
+    def paid(
+        self,
+        name: str,
+        *,
+        amount: str,
+        currency: str = "FET",
+        description: str | None = None,
+    ) -> Callable[[ActionHandler], ActionHandler]:
+        """Put action ``name`` behind a payment. The handler runs only after payment.
+
+        Tapping a button with ``action=name`` (or calling :meth:`charge`) sends the
+        user a ``RequestPayment``; when the user's ``CommitPayment`` verifies
+        on-chain, the handler runs with the original message and selection.
+        """
+        from .payments import Paywall, Product
+
+        if self._paywall is None:
+            self._paywall = Paywall(self)
+        paywall = self._paywall
+
+        def decorator(func: ActionHandler) -> ActionHandler:
+            paywall.add(
+                Product(
+                    name=name,
+                    amount=amount,
+                    currency=currency,
+                    description=description or name,
+                    handler=func,
+                )
+            )
+
+            async def request(ctx: Context, msg: Inbound, sel: dict[str, Any]) -> Reply:
+                return await paywall.request(ctx, msg, name, sel)
+
+            self._action_handlers[name] = request
+            self._known_actions.add(name)
+            return func
+
+        return decorator
+
+    async def charge(
+        self, ctx: Context, msg: Inbound, product: str, sel: dict[str, Any] | None = None
+    ) -> Reply:
+        """Start the payment flow for a ``@paid`` product from your own code."""
+        if self._paywall is None:
+            raise ValueError(f"no @agent.paid product named {product!r}")
+        return await self._paywall.request(ctx, msg, product, sel or {})
+
+    # ------------------------------------------------------------------ #
+    # Sending
+    # ------------------------------------------------------------------ #
+
+    async def reply(self, ctx: Context, to: str, reply: Reply) -> None:
+        """Send a reply (any handler return value) to ``to``."""
+        for message in to_messages(reply):
+            for content in message.content:
+                if isinstance(content, MetadataContent) and "card_payload" in content.metadata:
+                    self._known_actions |= collect_actions(
+                        json.loads(content.metadata["card_payload"])
+                    )
+            await ctx.send(to, message)
+
+    # ------------------------------------------------------------------ #
+    # Protocol plumbing
+    # ------------------------------------------------------------------ #
+
+    async def _on_chat_ack(self, ctx: Context, sender: str, msg: ChatAcknowledgement) -> None:
+        ctx.logger.debug(f"ack from {sender} for {msg.acknowledged_msg_id}")
+
+    async def _on_chat_message(self, ctx: Context, sender: str, msg: ChatMessage) -> None:
+        await ctx.send(
+            sender,
+            ChatAcknowledgement(timestamp=datetime.now(UTC), acknowledged_msg_id=msg.msg_id),
+        )
+        texts: list[str] = []
+        metadata: dict[str, str] = {}
+        for content in msg.content:
+            if isinstance(content, TextContent):
+                texts.append(content.text)
+            elif isinstance(content, MetadataContent):
+                metadata.update(content.metadata)
+            elif isinstance(content, StartSessionContent):
+                ctx.logger.info(f"session start from {sender}")
+            elif isinstance(content, EndSessionContent):
+                ctx.logger.info(f"session end from {sender}")
+        raw_text = "\n".join(texts).strip()
+        if not raw_text:
+            return
+
+        inbound = Inbound(
+            sender=sender,
+            text=strip_mention(raw_text),
+            session=str(ctx.session),
+            raw=msg,
+            metadata=metadata,
+            selection=parse_selection(raw_text, self._known_actions),
+        )
+        ctx.logger.info(f"<- {sender[:16]}…: {inbound.text[:200]!r}")
+        try:
+            reply = await self._dispatch(ctx, inbound)
+        except Exception:
+            ctx.logger.exception("handler failed")
+            reply = self.error_message
+        try:
+            await self.reply(ctx, sender, reply)
+        except Exception:
+            ctx.logger.exception("could not send reply")
+            await ctx.send(sender, text_message(self.error_message))
+
+    async def _dispatch(self, ctx: Context, inbound: Inbound) -> Reply:
+        action = inbound.action
+        if action and action in self._action_handlers:
+            return await _maybe_await(
+                self._action_handlers[action](ctx, inbound, inbound.selection)
+            )
+        if self._text_handler is not None:
+            return await _maybe_await(self._text_handler(ctx, inbound))
+        return "Hi! This agent has no @agent.on_text handler yet."
+
+    async def _auto_connect(self, ctx: Context) -> None:
+        from .register import connect_mailbox
+
+        if not os.getenv("AGENTVERSE_API_KEY"):
+            ctx.logger.warning(
+                "AGENTVERSE_API_KEY not set: open the inspector link above and click Connect "
+                "(mailbox), or set the key so the agent connects itself."
+            )
+            return
+        result = await connect_mailbox(self)
+        if result.ok:
+            ctx.logger.info(f"Connected to Agentverse as {result.profile_url}")
+            if result.detail:
+                ctx.logger.warning(result.detail)
+        else:
+            ctx.logger.error(f"Agentverse connect failed: {result.detail}")

fetch_hackkit/asi1.py

@@ -0,0 +1,294 @@
+"""ASI:One LLM client: chat, structured output, and a tool-calling loop.
+
+ASI:One speaks the OpenAI Chat Completions format, so this wraps the official
+``openai`` SDK pointed at ``https://api.asi1.ai/v1``.
+
+    llm = ASI1()                                   # reads ASI_ONE_API_KEY
+    text = await llm.ask("Explain uAgents in one line")
+    answer = await llm.run_tools("Weather in Paris?", tools=[get_weather])
+
+Any plain Python function (sync or async) with type hints and a docstring can
+be a tool; its JSON schema is generated for you.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import os
+import re
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, TypeVar, cast, get_type_hints
+
+from openai import AsyncOpenAI
+from pydantic import BaseModel, ValidationError, create_model
+
+ASI1_BASE_URL = "https://api.asi1.ai/v1"
+DEFAULT_MODEL = "asi1"
+_KEY_ENVS = ("ASI_ONE_API_KEY", "ASI1_API_KEY")
+
+log = logging.getLogger("fetch_hackkit.asi1")
+M = TypeVar("M", bound=BaseModel)
+Message = dict[str, Any]
+
+
+class ASI1Error(RuntimeError):
+    pass
+
+
+# --------------------------------------------------------------------------- #
+# Tools
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class Tool:
+    """A function the model may call."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    call: Callable[[dict[str, Any]], Awaitable[Any]]
+
+    def spec(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+def _doc_parts(func: Callable[..., Any]) -> tuple[str, dict[str, str]]:
+    """Summary + per-argument descriptions from a Google-style docstring."""
+    doc = inspect.getdoc(func) or ""
+    summary = doc.split("\n\n", 1)[0].strip().replace("\n", " ")
+    args: dict[str, str] = {}
+    match = re.search(r"^(?:Args|Arguments|Parameters):\s*\n(.*?)(?:\n\S|\Z)", doc, re.S | re.M)
+    if match:
+        for line in match.group(1).splitlines():
+            m = re.match(r"\s+(\w+)(?:\s*\([^)]*\))?:\s*(.+)", line)
+            if m:
+                args[m.group(1)] = m.group(2).strip()
+    return summary or func.__name__.replace("_", " "), args
+
+
+def tool(func: Callable[..., Any], *, name: str | None = None) -> Tool:
+    """Turn a typed Python function (sync or async) into a :class:`Tool`."""
+    if isinstance(func, Tool):
+        return func
+    summary, arg_docs = _doc_parts(func)
+    hints = get_type_hints(func)
+    fields: dict[str, Any] = {}
+    for pname, param in inspect.signature(func).parameters.items():
+        if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
+            continue
+        annotation = hints.get(pname, str)
+        default = ... if param.default is inspect.Parameter.empty else param.default
+        fields[pname] = (annotation, default)
+    model = create_model(f"{func.__name__}_args", **fields)
+    schema = model.model_json_schema()
+    schema.pop("title", None)
+    for pname, prop in schema.get("properties", {}).items():
+        prop.pop("title", None)
+        if pname in arg_docs:
+            prop["description"] = arg_docs[pname]
+
+    async def call(arguments: dict[str, Any]) -> Any:
+        validated = model.model_validate(arguments)
+        kwargs = {k: getattr(validated, k) for k in fields}
+        if inspect.iscoroutinefunction(func):
+            return await func(**kwargs)
+        return await asyncio.to_thread(func, **kwargs)
+
+    return Tool(name=name or func.__name__, description=summary, parameters=schema, call=call)
+
+
+def _to_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, BaseModel):
+        return value.model_dump_json()
+    try:
+        return json.dumps(value, default=str, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _extract_json(text: str) -> str:
+    """Pull a JSON object out of a reply that may wrap it in prose or code fences."""
+    fenced = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.S)
+    if fenced:
+        return fenced.group(1)
+    start, end = text.find("{"), text.rfind("}")
+    return text[start : end + 1] if start != -1 and end > start else text
+
+
+# --------------------------------------------------------------------------- #
+# Client
+# --------------------------------------------------------------------------- #
+
+
+class ASI1:
+    """Thin async ASI:One client."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        model: str | None = None,
+        base_url: str = ASI1_BASE_URL,
+        timeout: float = 60.0,
+        client: AsyncOpenAI | None = None,
+    ) -> None:
+        self.model = model or os.getenv("ASI_ONE_MODEL") or DEFAULT_MODEL
+        if client is not None:
+            self.client = client
+            return
+        key = api_key or next((os.environ[k] for k in _KEY_ENVS if os.getenv(k)), None)
+        if not key:
+            raise ASI1Error(
+                "ASI_ONE_API_KEY is not set. Get a key at https://asi1.ai/developer "
+                "and put it in your .env."
+            )
+        self.client = AsyncOpenAI(api_key=key, base_url=base_url, timeout=timeout)
+
+    async def chat(
+        self, messages: Sequence[Message], *, model: str | None = None, **kwargs: Any
+    ) -> str:
+        """One completion. Returns the assistant text."""
+        resp = await self.client.chat.completions.create(
+            model=model or self.model,
+            messages=cast(Any, list(messages)),
+            **kwargs,
+        )
+        return resp.choices[0].message.content or ""
+
+    async def ask(
+        self, prompt: str, *, system: str | None = None, history: Sequence[Message] = ()
+    ) -> str:
+        """Ask a single question (optionally with a system prompt and prior turns)."""
+        return await self.chat(_messages(prompt, system, history))
+
+    async def structured(
+        self, prompt: str, schema: type[M], *, system: str | None = None, retries: int = 1
+    ) -> M:
+        """Ask for JSON matching a Pydantic model; validated, with one repair retry."""
+        instructions = (
+            "Reply with only a JSON object matching this JSON schema, no prose:\n"
+            + json.dumps(schema.model_json_schema())
+        )
+        messages = _messages(prompt, f"{system}\n\n{instructions}" if system else instructions)
+        for attempt in range(retries + 1):
+            text = await self.chat(messages)
+            try:
+                return schema.model_validate_json(_extract_json(text))
+            except ValidationError as exc:
+                if attempt == retries:
+                    raise ASI1Error(f"model did not return valid {schema.__name__}: {exc}") from exc
+                messages = [
+                    *messages,
+                    {"role": "assistant", "content": text},
+                    {"role": "user", "content": f"That was invalid: {exc}. Try again."},
+                ]
+        raise AssertionError("unreachable")
+
+    async def run_tools(
+        self,
+        prompt: str | Sequence[Message],
+        tools: Sequence[Callable[..., Any] | Tool],
+        *,
+        system: str | None = None,
+        max_steps: int = 6,
+        on_call: Callable[[str, dict[str, Any], Any], None] | None = None,
+    ) -> str:
+        """Let the model call ``tools`` until it can answer; returns the final text.
+
+        Tool exceptions are sent back to the model as ``{"error": ...}`` so it
+        can retry or explain, instead of crashing your agent.
+        """
+        registry = {t.name: t for t in (f if isinstance(f, Tool) else tool(f) for f in tools)}
+        specs = [t.spec() for t in registry.values()]
+        messages: list[Message] = (
+            _messages(prompt, system)
+            if isinstance(prompt, str)
+            else [*([{"role": "system", "content": system}] if system else []), *prompt]
+        )
+        for _ in range(max_steps):
+            resp = await self.client.chat.completions.create(
+                model=self.model,
+                messages=cast(Any, messages),
+                tools=cast(Any, specs),
+            )
+            message = resp.choices[0].message
+            calls: list[Any] = list(message.tool_calls or [])
+            if not calls:
+                return message.content or ""
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": message.content or "",
+                    "tool_calls": [
+                        {
+                            "id": c.id,
+                            "type": "function",
+                            "function": {
+                                "name": c.function.name,
+                                "arguments": c.function.arguments,
+                            },
+                        }
+                        for c in calls
+                        if getattr(c, "function", None) is not None
+                    ],
+                }
+            )
+            for call in calls:
+                fn = getattr(call, "function", None)
+                name = getattr(fn, "name", "")
+                args: dict[str, Any] = {}
+                try:
+                    args = json.loads(getattr(fn, "arguments", None) or "{}")
+                    if name not in registry:
+                        raise ASI1Error(f"unknown tool {name!r}")
+                    result: Any = await registry[name].call(args)
+                except Exception as exc:  # report to the model, keep going
+                    result = {"error": f"{type(exc).__name__}: {exc}"}
+                    log.warning("tool %s failed: %s", name, exc)
+                if on_call:
+                    on_call(name, args, result)
+                messages.append(
+                    {"role": "tool", "tool_call_id": call.id, "content": _to_text(result)[:20_000]}
+                )
+        messages.append(
+            {"role": "user", "content": "Stop calling tools and answer with what you have."}
+        )
+        return await self.chat(messages)
+
+
+def _messages(
+    prompt: str, system: str | None = None, history: Sequence[Message] = ()
+) -> list[Message]:
+    out: list[Message] = [{"role": "system", "content": system}] if system else []
+    return [*out, *history, {"role": "user", "content": prompt}]
+
+
+# --------------------------------------------------------------------------- #
+# Per-conversation memory (ASI:One sends your agent one message at a time)
+# --------------------------------------------------------------------------- #
+
+
+def history(ctx: Any, session: str) -> list[Message]:
+    """Prior turns for this conversation, stored in ``ctx.storage``."""
+    stored = ctx.storage.get(f"hackkit:history:{session}")
+    return list(stored) if isinstance(stored, list) else []
+
+
+def remember(ctx: Any, session: str, role: str, content: str, *, keep: int = 20) -> None:
+    """Append a turn to this conversation's history (keeps the last ``keep``)."""
+    turns = [*history(ctx, session), {"role": role, "content": content}][-keep:]
+    ctx.storage.set(f"hackkit:history:{session}", turns)