fetch-hackkit 0.1.0__tar.gz → 0.2.0__tar.gz

{fetch_hackkit-0.1.0 → fetch_hackkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fetch-hackkit
-Version: 0.1.0
+Version: 0.2.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
@@ -34,6 +34,14 @@ Batteries for [Fetch.ai](https://fetch.ai) hackathon agents. Build a uAgent that
 - **Multi-agent**: `ask_agent(ctx, "@handle", "question")`.
 - **Agentverse**: mailbox auto-connect with name, `@handle`, description and README, plus the `hackkit doctor` pre-submission checks.
 
+Start a new project in one command (fresh seed, a free `@handle`, README, tests, Dockerfile, AGENTS.md and coding-agent configs):
+
+```bash
+uvx --from "fetch-hackkit[mcp]" hackkit new "Trip Planner"
+```
+
+Or add it to an existing project:
+
 ```bash
 pip install fetch-hackkit          # or: pip install "fetch-hackkit[mcp]"
 ```
@@ -63,6 +71,7 @@ Environment (`.env` is loaded automatically):
 ## CLI
 
 ```
+hackkit new NAME        create a ready-to-run agent project
 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?

{fetch_hackkit-0.1.0 → fetch_hackkit-0.2.0}/README.md

@@ -10,6 +10,14 @@ Batteries for [Fetch.ai](https://fetch.ai) hackathon agents. Build a uAgent that
 - **Multi-agent**: `ask_agent(ctx, "@handle", "question")`.
 - **Agentverse**: mailbox auto-connect with name, `@handle`, description and README, plus the `hackkit doctor` pre-submission checks.
 
+Start a new project in one command (fresh seed, a free `@handle`, README, tests, Dockerfile, AGENTS.md and coding-agent configs):
+
+```bash
+uvx --from "fetch-hackkit[mcp]" hackkit new "Trip Planner"
+```
+
+Or add it to an existing project:
+
 ```bash
 pip install fetch-hackkit          # or: pip install "fetch-hackkit[mcp]"
 ```
@@ -39,6 +47,7 @@ Environment (`.env` is loaded automatically):
 ## CLI
 
 ```
+hackkit new NAME        create a ready-to-run agent project
 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?

{fetch_hackkit-0.1.0 → fetch_hackkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fetch-hackkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Batteries for Fetch.ai hackathon agents: chat protocol, ASI:One interactive cards, ASI:One LLM + tools, payments, MCP, and Agentverse registration."
 readme = "README.md"
 license = "MIT"

{fetch_hackkit-0.1.0 → fetch_hackkit-0.2.0}/src/fetch_hackkit/__init__.py

@@ -9,7 +9,7 @@ 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"
+__version__ = "0.2.0"
 
 __all__ = [
     "ASI1",

{fetch_hackkit-0.1.0 → fetch_hackkit-0.2.0}/src/fetch_hackkit/cli.py

@@ -1,4 +1,4 @@
-"""``hackkit`` command line: seed, whoami, handle, doctor."""
+"""``hackkit`` command line: new, seed, whoami, handle, doctor."""
 
 from __future__ import annotations
 
@@ -51,6 +51,37 @@ def _handle(args: argparse.Namespace) -> int:
     return 1
 
 
+def _new(args: argparse.Namespace) -> int:
+    from .scaffold import create_project
+
+    try:
+        project = create_project(
+            args.name,
+            directory=Path(args.dir) if args.dir else None,
+            handle=args.handle,
+            check_handle=not args.no_check,
+        )
+    except (FileExistsError, ValueError) as exc:
+        print(f"❌ {exc}")
+        return 1
+    try:
+        where = project.path.relative_to(Path.cwd())
+    except ValueError:
+        where = project.path
+    print(f"✅ Created {project.name} in {where}/")
+    print(f"   handle:  @{project.handle} ({project.handle_note})")
+    print(f"   address: {project.address}")
+    print("   identity: a fresh seed is in .env (never commit it)\n")
+    print("Next:")
+    print(f"  cd {where}")
+    print("  # add ASI_ONE_API_KEY and AGENTVERSE_API_KEY to .env")
+    print("  uv sync")
+    print("  uv run python agent.py")
+    print(f"  # then on https://asi1.ai say: @{project.handle} hi")
+    print("\nCoding agent: run `opencode` here (ASI:One + Agentverse MCP), or Claude Code/Cursor.")
+    return 0
+
+
 def _doctor(args: argparse.Namespace) -> int:
     from .doctor import run
 
@@ -69,6 +100,12 @@ def main(argv: list[str] | None = None) -> int:
     load_dotenv(find_dotenv(usecwd=True))
     parser = argparse.ArgumentParser(prog="hackkit", description="Fetch.ai hackathon helpers")
     sub = parser.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("new", help="create a ready-to-run agent project")
+    p.add_argument("name", help='agent name, e.g. "Trip Planner"')
+    p.add_argument("--dir", help="where to create it (default: ./<name-slug>)")
+    p.add_argument("--handle", help="Agentverse @handle (default: from the name)")
+    p.add_argument("--no-check", action="store_true", help="don't check handle availability")
+    p.set_defaults(fn=_new)
     sub.add_parser("seed", help="generate a secure seed phrase + show its address").set_defaults(
         fn=_seed
     )

fetch_hackkit-0.2.0/src/fetch_hackkit/scaffold.py

@@ -0,0 +1,122 @@
+"""``hackkit new``: generate a minimal, ready-to-run agent project.
+
+The project gets an agent with a menu card and an ASI:One tool, a README in
+Agentverse profile shape, a fresh seed in ``.env``, tests, a Dockerfile, and
+AGENTS.md plus opencode/Claude Code/Cursor configs for coding agents.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+from .register import HANDLE_MAX_LEN, resolve, validate_handle
+
+# template file (under templates/project) -> path in the new project
+FILES = {
+    "agent.py.tmpl": "agent.py",
+    "README.md.tmpl": "README.md",
+    "pyproject.toml.tmpl": "pyproject.toml",
+    "python-version.tmpl": ".python-version",
+    "env.example.tmpl": ".env.example",
+    "gitignore.tmpl": ".gitignore",
+    "dockerignore.tmpl": ".dockerignore",
+    "Dockerfile.tmpl": "Dockerfile",
+    "tests/test_agent.py.tmpl": "tests/test_agent.py",
+    "opencode.json.tmpl": "opencode.json",
+    "mcp.json.tmpl": ".mcp.json",
+    "cursor_mcp.json.tmpl": ".cursor/mcp.json",
+}
+
+
+@dataclass
+class Project:
+    path: Path
+    name: str
+    handle: str
+    address: str
+    handle_note: str = ""
+
+
+def slugify(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    return slug or "my-agent"
+
+
+def _template(rel: str) -> str:
+    return (files("fetch_hackkit") / "templates" / rel).read_text(encoding="utf-8")
+
+
+def _choose_handle(wanted: str, check: bool) -> tuple[str, str]:
+    """Return (handle, note). Picks a free variant if ``wanted`` is taken."""
+    handle = validate_handle(wanted[:HANDLE_MAX_LEN].strip("-") or "my-agent")
+    if not check:
+        return handle, "not checked (--no-check)"
+    try:
+        if resolve(handle) is None:
+            return handle, "available"
+        for _ in range(5):
+            candidate = validate_handle(f"{handle[: HANDLE_MAX_LEN - 5]}-{secrets.token_hex(2)}")
+            if resolve(candidate) is None:
+                return candidate, f"@{handle} was taken"
+    except Exception as exc:  # offline etc.: keep the wanted handle
+        return handle, f"could not check availability ({type(exc).__name__})"
+    return handle, f"@{handle} is taken; pick another with `hackkit handle`"
+
+
+def create_project(
+    name: str,
+    *,
+    directory: Path | None = None,
+    handle: str | None = None,
+    check_handle: bool = True,
+) -> Project:
+    """Write a new agent project and return where it is and who it is."""
+    from . import __version__
+    from .doctor import identity_from_seed
+
+    path = (directory or Path.cwd() / slugify(name)).resolve()
+    if path.exists() and any(path.iterdir()):
+        raise FileExistsError(f"{path} already exists and is not empty")
+
+    chosen, note = _choose_handle(
+        handle.removeprefix("@") if handle else slugify(name), check_handle
+    )
+    seed = secrets.token_urlsafe(32)
+    address, _wallet = identity_from_seed(seed)
+    values = {
+        "__AGENT_NAME__": name,
+        "__AGENT_HANDLE__": chosen,
+        "__AGENT_ADDRESS__": address,
+        "__PROJECT_SLUG__": slugify(name),
+        "__HACKKIT_VERSION__": __version__,
+    }
+
+    def render(text: str) -> str:
+        for key, value in values.items():
+            text = text.replace(key, value)
+        return text
+
+    for src, dest in FILES.items():
+        target = path / dest
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(render(_template(f"project/{src}")), encoding="utf-8")
+
+    agents_md = render(_template("project/AGENTS.md.tmpl")) + _template("agents_reference.md")
+    (path / "AGENTS.md").write_text(agents_md, encoding="utf-8")
+    try:
+        os.symlink("AGENTS.md", path / "CLAUDE.md")
+    except OSError:  # e.g. Windows without symlink rights
+        (path / "CLAUDE.md").write_text(agents_md, encoding="utf-8")
+
+    env = render(_template("project/env.example.tmpl")).replace(
+        "AGENT_SEED_PHRASE=\n", f"AGENT_SEED_PHRASE={seed}\n", 1
+    )
+    env_path = path / ".env"
+    env_path.write_text(env, encoding="utf-8")
+    env_path.chmod(0o600)
+    return Project(path=path, name=name, handle=chosen, address=address, handle_note=note)

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/agents_reference.md

@@ -0,0 +1,237 @@
+## Golden rules
+
+1. **Use `HackAgent`, not a bare `uagents.Agent`.** It includes the chat protocol, publishes its manifest, sends acknowledgements, and turns handler exceptions into a friendly reply.
+2. **Handlers return replies; they don't call `ctx.send` for chat.** Return a `str`, a `cards.Card`, a `ChatMessage`, or a list of these.
+3. **Never block the event loop.** Use `httpx.AsyncClient` / `async` SDKs. Wrap blocking calls in `await asyncio.to_thread(fn, ...)`.
+4. **Secrets live in `.env`** (gitignored): `AGENT_SEED_PHRASE`, `ASI_ONE_API_KEY`, `AGENTVERSE_API_KEY`.
+   - Never hard-code them. Never print the seed.
+   - The seed *is* the agent: the same seed always gives the same address and wallet.
+5. **Keep per-conversation state in `ctx.storage`, keyed by `msg.session`.** ASI:One sends your agent one message at a time.
+6. **Every card has a narration.** It's the fallback text if a card fails to render.
+7. **Run `uv run pytest -q` and `uv run ruff check .` after changes.**
+
+## The agent pattern
+
+```python
+from fetch_hackkit import HackAgent, cards
+
+agent = HackAgent(
+    name="Trip Planner",                 # display name on Agentverse
+    handle="trip-planner",               # @handle: unique, <= 40 chars
+    description="Plans weekend trips with live prices.",   # short description
+    readme_path="README.md",             # long description (ASI:One routing reads it)
+)
+
+@agent.on_text                           # free text (leading @mentions already stripped)
+async def on_text(ctx, msg):             # msg: Inbound(sender, text, session, selection, raw)
+    return cards.carousel("Pick a city", [
+        cards.item("sf", "San Francisco", action="pick_city"),
+        cards.item("la", "Los Angeles", action="pick_city"),
+    ], narration="Where to?")
+
+@agent.on_action("pick_city")            # card taps, routed by selection["action"]
+async def pick_city(ctx, msg, sel):      # sel == {"action": "pick_city", "id": "sf"}
+    return f"Planning a trip to {sel['id']}..."
+
+if __name__ == "__main__":
+    agent.run()
+```
+
+`HackAgent` subclasses `uagents.Agent`, so `@agent.on_interval(period=60)`, `@agent.on_event("startup")`, `agent.include(protocol)` and `ctx.storage` all work.
+
+## Interactive cards (ASI:One UI)
+
+A card is a chat message with narration text plus a `MetadataContent` declaration. ASI:One renders it as UI. When the user taps a button, the button's **selection** comes back to your agent as a message.
+
+### Pick the right card
+
+| Card | Use for | Builder |
+|---|---|---|
+| `carousel` | Menus, search results, options (one button per item) | `cards.carousel(title, [cards.item(id, title, action=...)])` |
+| `detail` | One thing in depth: image, key/value rows, radio choice, several buttons | `cards.detail(title, rows={...}, ctas=[cards.cta(...)], sub_options=cards.radio(...))` |
+| `form` | Collect input (`text`, `number`, `email`, `select`, `checkbox`) | `cards.form(title, [cards.field(...)], submit=cards.cta(...))` |
+| `review` | Confirm before anything irreversible (payment, booking, sending) | `cards.review(title, rows=..., approve=cards.cta(...), reject=cards.cta(...))` |
+| `custom` | Anything else, built from primitives | `cards.custom(ui.section(title, [ui.text(...), ui.button(...)]))` |
+| read-only | Show a result that needs no input | `cards.info(title, rows=...)` |
+
+Custom primitives live in `fetch_hackkit.cards.ui`:
+- **Layout:** `section`, `group(direction="row"|"column")`, `divider`.
+- **Content:** `text(style=)`, `heading(level=)`, `image`, `badge(variant="info"|"success"|"warning")`.
+- **Interactive:** `button`, `input`, `list_items` + `list_item`, `choice_grid` (image picker).
+
+### Selections: what comes back
+
+Every button built with `cards.cta(label, action, **data)`, `cards.item(..., action=...)` or `ui.button(label, action, **data)` sends `{"action": action, **data}`. The values that come back depend on the card:
+
+| Card | What arrives |
+|---|---|
+| carousel item | `{"action", "id", ...data}` |
+| detail | the button's selection, plus the radio value under `sub_options.name` |
+| form | the submit button's selection, plus **every field value** keyed by field name |
+| review | the approve or the reject selection |
+| custom | the button's selection, plus every `input` / `choice_grid` value keyed by `name` |
+
+It arrives in one of two formats, and `HackAgent` handles both:
+- **Direct @mention:** JSON. `sel` is the full dict.
+- **Routed by the ASI:One planner:** a prose sentence containing the selection's identifiers. `HackAgent` finds the action word and gives you `{"action": ..., "prose": "<sentence>"}`. Field values may only be inside `msg.text`.
+
+Design rules that follow:
+- **Make `action` names distinctive tokens** (`book_hotel`, not `ok`) so they can be found in prose.
+- **For important values, check `"prose" in sel`** and either recover them from `msg.text` or ask again.
+- **Unique ids in `data`** (e.g. `id="trip_42"`) also appear in the prose.
+- **One active card:** pass `card_id=` to `Card.to_message(card_id=...)` (or `cards.card_message`), and ignore taps whose `sel.get("card_id")` isn't the latest one.
+
+### Limits (enforced by `cards.validate`, which raises `CardError`)
+- Payload of 64 KB or less (the kit aims for under 60 KB).
+- Custom trees at most 8 levels deep.
+- `select` fields need `options`.
+- Only these card kinds exist; there is no standalone "buttons" kind. Use `custom` with `ui.button`.
+
+If ASI:One rejects a card, the user sees only the narration. That's why every card needs one.
+
+## ASI:One LLM (`fetch_hackkit.asi1`)
+
+The API is OpenAI-compatible (`https://api.asi1.ai/v1`). Models: `asi1` (default), `asi1-ultra`, `asi1-mini`. Set `ASI_ONE_MODEL` to switch.
+
+```python
+from fetch_hackkit import ASI1, history, remember
+
+llm = ASI1()                                        # raises ASI1Error if no key
+text = await llm.ask("Summarise this", system="Be brief")
+plan = await llm.structured("Plan a trip to SF", TripPlan)   # Pydantic model, validated
+answer = await llm.run_tools(question, tools=[get_weather, search_flights])
+```
+
+- **Tools are plain functions,** sync or async, with type hints and a docstring. Google-style `Args:` lines become parameter descriptions.
+- **Failures don't crash the agent:** a tool exception goes back to the model as `{"error": ...}`.
+- **Use `run_tools`** to make the agent *act*, not just chat. Judges penalise "a thin wrapper around an API".
+- **Multi-turn memory:** `history(ctx, msg.session)` and `remember(ctx, msg.session, role, text)`.
+
+## Payments (`@agent.paid`)
+
+```python
+@agent.paid("premium_report", amount="0.5", description="Premium market report")
+async def premium(ctx, msg, sel):      # runs only after payment is verified on-chain
+    return await build_report(sel)
+```
+
+1. A tap with `action="premium_report"`, or `await agent.charge(ctx, msg, "premium_report")`, sends `RequestPayment` (FET, `fet_direct`, the agent's wallet as recipient).
+2. The user approves in ASI:One. The agent receives `CommitPayment(transaction_id)`.
+3. The kit verifies the transfer on-chain (recipient, amount, buyer) with cosmpy, retrying while the transaction indexes. It then sends `CompletePayment` and runs your handler. Otherwise it sends `CancelPayment(reason)`.
+4. Replayed commits are acknowledged but never delivered twice.
+
+Notes:
+- **Network:** stable testnet by default (`FET_NETWORK=mainnet` for real FET). Test FET is free from the Fetch.ai testnet faucet.
+- **Show the price first:** put a `review` card before an expensive paid action.
+- **Never deliver paid work before the handler runs.**
+
+## MCP
+
+**Use an MCP server's tools inside your agent:**
+```python
+from fetch_hackkit.mcp import mcp_tools, call_mcp_tool
+tools = await mcp_tools("https://mcp.deepwiki.com/mcp", include={"ask_wiki_question"})
+answer = await ASI1().run_tools("How does X work in fetchai/uAgents?", tools=tools)
+```
+Pass `headers={"Authorization": "Bearer ..."}` for authenticated servers.
+
+**Publish an MCP server as an Agentverse agent:** use `uagents-adapter[mcp]` (`MCPServerAdapter`). It's not part of this kit.
+
+## Multi-agent
+
+```python
+from fetch_hackkit.peers import ask_agent, PeerError
+reply = await ask_agent(ctx, "@some-handle", "question", timeout=60)  # or an agent1... address
+```
+
+`ask_agent` works with any chat-protocol agent on Agentverse. For your own specialist, run a second `HackAgent` with its own seed and port, then call it by address or `@handle`.
+
+## Registration and the Agentverse profile
+
+### How the agent gets onto Agentverse
+
+`HackAgent` uses a **mailbox** by default, so it runs on your laptop but is reachable through Agentverse.
+- **With `AGENTVERSE_API_KEY` set:** on startup it proves ownership of its address and publishes its profile. No clicks needed.
+- **Without the key:** open the inspector link the agent logs and click **Connect → Mailbox**.
+- **Agent at a public URL** (Render, Fly, a VM): call `fetch_hackkit.register.register_endpoint_agent(agent, "https://.../submit")`.
+
+### Where each profile field comes from
+
+| Profile field | Set it in code | Change it later via the Agentverse MCP |
+|---|---|---|
+| Name | `HackAgent(name=...)` | `update_user_agent_mailbox` (mailbox/local) / `update_user_agent` (hosted): `name` |
+| **@handle** | `HackAgent(handle=...)` or `AGENT_HANDLE` in `.env` | **Not possible via MCP.** Change it in code and restart. |
+| Short description | `HackAgent(description=...)` | same tools: `short_description` |
+| README | `HackAgent(readme_path=...)` | same tools: `readme` |
+| Avatar | `HackAgent(avatar_url=...)` | same tools: `avatar_url` |
+| Protocols | automatic: chat, plus payment if `@agent.paid` is used | read-only |
+
+Handle rules:
+- 1–40 characters: letters, digits, `-`, `_` and `.`.
+- Unique across all of Agentverse.
+- Check availability first with `uv run hackkit handle <name>`. A taken handle fails registration with HTTP 409.
+- Agentverse only applies `handle` when it *updates* an existing agent, not when it first creates one. `HackAgent`'s auto-connect checks and re-sends for you. If you connect another way (e.g. the inspector button), restart the agent once or run `hackkit doctor` to confirm the handle stuck.
+
+### Agentverse MCP (configured in `opencode.json`, `.mcp.json`, `.cursor/mcp.json`)
+
+- **Server:** `https://mcp.agentverse.ai/mcp` (streamable HTTP, ~126 tools), enabled by default.
+- **Lite server** (`https://mcp-lite.agentverse.ai/mcp`): fewer tools, so it's friendlier to smaller models. It's included but disabled in `opencode.json` because it wasn't responding when this starter was tested (2026-10-22). Enable it if it's back up.
+- **Auth:** an `Authorization: Bearer $AGENTVERSE_API_KEY` header covers public lookups (`get_agent`, `get_agent_search_api_internal`, `search_agents`). Tools that act on *your* agents (`get_user_agent_*`, `update_user_agent_*`, `create_user_agent`, …) also need the key passed as their `api_token` argument. Read it from the environment; never paste it into chat.
+
+Useful workflows:
+- **Inspect your agent:**
+  - `get_user_agent_details` / `get_agent` with your address;
+  - `agent_readiness_probe_mailbox` (mailbox) / `agent_readiness_probe` (hosted).
+- **Edit your profile:** `update_user_agent_mailbox(address, name, short_description, readme)`.
+- **Hosted agent** (runs on Agentverse, no laptop): `create_user_agent` → `update_user_agent_code` → `start_specific_user_agent` → `get_latest_logs_for_user_agent`. See *Keeping your agent online* for the catch.
+- **Discoverability:**
+  - `search_agents` with the words a user would type, to see where you rank;
+  - `start_agent_seo_eval` → `get_agent_seo_eval_results` to see how well ASI:One can match you.
+
+### Getting discovered by ASI:One
+
+ASI:One routes users by your **name, description, README and handle**:
+- Write the README for routing: what the agent does, concrete example prompts, and the domains it covers.
+- Keep the agent running (status `active`). A stopped mailbox agent isn't routed to.
+
+## Keeping your agent online
+
+A mailbox agent only answers while its process is running. Judges will message yours, so plan for it.
+
+- **It needs only outbound internet:** no public URL, no open ports, no domain.
+- **While hacking:** run it on your laptop. On macOS, keep the laptop awake with `caffeinate -i uv run python agent.py`.
+- **For judging and after:** run the `Dockerfile` on any always-on host as a *background worker* (no HTTP service), with your `.env` values as environment variables:
+  ```bash
+  docker build -t my-agent .
+  docker run -d --restart unless-stopped --env-file .env my-agent
+  ```
+  Any container host works: a small VM, Render (Background Worker), Railway, Fly.io Machines.
+- **Run exactly one copy per seed.** Two processes with the same seed poll the same mailbox and split your messages.
+- **`ctx.storage` is a local JSON file.** On hosts with throwaway disks it resets on redeploy. That's fine for a demo; use a database for anything you must keep.
+- **Agentverse-hosted agents** (`create_user_agent` via MCP) run in Agentverse's own sandbox with a fixed set of packages, so they can't install `fetch-hackkit`. Prefer the mailbox + Docker route.
+
+## Submission checklist (Fetch.ai prize)
+
+- [ ] Registered on Agentverse, status active, chat protocol published. `hackkit doctor` checks all of this.
+- [ ] The agent stays online through judging (see *Keeping your agent online*).
+- [ ] Works end-to-end inside ASI:One chat, with no custom frontend.
+- [ ] Real tool use, MCP, or multi-agent orchestration, not just one LLM call.
+- [ ] (Bonus) Interactive cards, the Payment Protocol, and error handling and recovery.
+- [ ] Public GitHub repo README with **agent name + address** and both badges:
+  `![tag:innovationlab](https://img.shields.io/badge/innovationlab-3D8BD3)`
+  `![tag:hackathon](https://img.shields.io/badge/hackathon-5F43F1)`
+- [ ] A 3–5 minute demo video.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `No seed phrase` | `uv run hackkit seed`, then put the phrase in `.env` |
+| Agent not found in ASI:One | Is it running? Run `hackkit doctor`. Make the README specific, then try `@your-handle` directly. |
+| `HTTP 409` on connect | Handle (or address) taken by another account. Pick a new handle. |
+| `HTTP 401` on connect | Bad or expired `AGENTVERSE_API_KEY` |
+| Card shows as plain text | The card is invalid. Look for `CardError` in the logs. |
+| Button tap ignored | No `@agent.on_action` for that action, so it falls through to `on_text`. Check `msg.selection`. |
+| Payment "not found" | The transaction is still indexing; the kit retries 3 times. On mainnet, check `FET_NETWORK`. |
+| Log warns `not enough funds to register on Almanac contract` | Harmless. Agentverse (API) registration is what ASI:One uses; the on-chain contract registration is optional. |
+| `There is no current event loop` (Python 3.14) | Use `HackAgent`, which creates the loop for you, or run on Python 3.13 |

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/AGENTS.md.tmpl

@@ -0,0 +1,33 @@
+# AGENTS.md
+
+Guide for AI coding agents (opencode, Claude Code, Cursor, Codex, and others) working in this project. Humans: this is also the fastest complete reference.
+
+You are helping a hackathon team build a **Fetch.ai agent** called **__AGENT_NAME__** (`@__AGENT_HANDLE__`). To win, the agent must:
+- be registered on **Agentverse**;
+- be discoverable and usable inside **ASI:One** chat (the Agent Chat Protocol);
+- do real work: tools, APIs, MCP, or other agents;
+- ideally use **interactive cards** and the **Payment Protocol**.
+
+The `fetch-hackkit` package does the plumbing. Write agent code against it.
+
+## Project map
+
+| Path | What it is |
+|---|---|
+| `agent.py` | The agent: `HackAgent`, its handlers, cards and tools. Start here. |
+| `README.md` | Shown on the Agentverse profile; ASI:One reads it to route users here. Keep it specific. |
+| `tests/` | Tests. At minimum, every card you send must pass `cards.validate`. |
+| `.env` | Secrets and identity (gitignored). `.env.example` documents every variable. |
+| `Dockerfile` | Runs the agent on an always-on host (see *Keeping your agent online*). |
+
+## Commands
+
+```bash
+uv sync                                # install (Python 3.11+)
+uv run python agent.py                 # run the agent
+uv run hackkit whoami                  # address, wallet, Agentverse profile URL
+uv run hackkit handle my-agent         # is @my-agent free on Agentverse?
+uv run hackkit doctor                  # pre-submission checks
+uv run pytest -q && uv run ruff check .
+```
+

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/Dockerfile.tmpl

@@ -0,0 +1,13 @@
+# Runs the agent as a background worker. It needs outbound internet only:
+#   docker build -t __PROJECT_SLUG__ .
+#   docker run -d --restart unless-stopped --env-file .env __PROJECT_SLUG__
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy PYTHONUNBUFFERED=1
+WORKDIR /app
+
+COPY pyproject.toml uv.lock* ./
+RUN uv sync --no-dev --no-install-project
+
+COPY . .
+CMD ["uv", "run", "--no-dev", "python", "agent.py"]

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/README.md.tmpl

@@ -0,0 +1,29 @@
+![tag:innovationlab](https://img.shields.io/badge/innovationlab-3D8BD3)
+![tag:hackathon](https://img.shields.io/badge/hackathon-5F43F1)
+
+# __AGENT_NAME__
+
+TODO: what your agent does, for whom, and why it's useful, in 2-3 sentences. Agentverse shows this README on your agent's profile, and ASI:One reads it to decide when to send users to you.
+
+**Handle:** `@__AGENT_HANDLE__`
+
+**Agent address:** `__AGENT_ADDRESS__`
+
+## What it can do
+
+- TODO: capability 1
+- TODO: capability 2
+
+## Example prompts
+
+- Hi
+- What's the weather in Berkeley?
+
+## Run it
+
+```bash
+uv sync
+uv run python agent.py
+```
+
+Built with [fetch-hackkit](https://pypi.org/project/fetch-hackkit/), uAgents, the Agent Chat Protocol and ASI:One.

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/agent.py.tmpl

@@ -0,0 +1,102 @@
+"""__AGENT_NAME__: a Fetch.ai agent built with fetch-hackkit.
+
+Run it:  uv run python agent.py
+Then chat with it on ASI:One (https://asi1.ai):  @__AGENT_HANDLE__ hi
+
+Start here: change the description, replace get_weather with your own tools,
+and add cards for the steps of your workflow. AGENTS.md has every pattern.
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+from fetch_hackkit import ASI1, ASI1Error, HackAgent, cards, history, remember
+
+agent = HackAgent(
+    name="__AGENT_NAME__",
+    handle=os.getenv("AGENT_HANDLE") or None,
+    # One sentence ASI:One users would search for. ASI:One routes by this + README.md.
+    description="TODO: describe what your agent does in one sentence.",
+    readme_path="README.md",
+)
+
+SYSTEM = (
+    "You are __AGENT_NAME__, an agent on Fetch.ai. Be concise. "
+    "Use your tools for facts instead of guessing."
+)
+
+GREETINGS = {"hi", "hello", "hey", "menu", "start", "help"}
+
+
+async def get_weather(city: str) -> str:
+    """Current weather for a city.
+
+    Args:
+        city: City name, e.g. Berkeley.
+    """
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.get(f"https://wttr.in/{city}", params={"format": "3"})
+        resp.raise_for_status()
+        return resp.text.strip()
+
+
+def menu() -> cards.Card:
+    return cards.carousel(
+        "__AGENT_NAME__",
+        [
+            cards.item(
+                "ask",
+                "Ask a question",
+                action="ask_help",
+                subtitle="ASI:One answers, calling tools when needed",
+            ),
+            cards.item(
+                "about", "What can you do?", action="about", subtitle="A quick tour of this agent"
+            ),
+        ],
+        narration="Hi! I'm **__AGENT_NAME__**. Pick an option or just ask me something.",
+    )
+
+
+@agent.on_text
+async def on_text(ctx, msg):
+    """Greetings open the menu; everything else goes to ASI:One with tools."""
+    if msg.text.strip().lower() in GREETINGS:
+        return menu()
+    try:
+        llm = ASI1()
+    except ASI1Error:
+        return "Add ASI_ONE_API_KEY to .env so I can answer questions."
+    past = history(ctx, msg.session)
+    reply = await llm.run_tools(
+        [*past, {"role": "user", "content": msg.text}],
+        tools=[get_weather],
+        system=SYSTEM,
+    )
+    remember(ctx, msg.session, "user", msg.text)
+    remember(ctx, msg.session, "assistant", reply)
+    return reply
+
+
+@agent.on_action("ask_help")
+async def ask_help(ctx, msg, sel):
+    return "Ask me anything. Try: *What's the weather in Berkeley?*"
+
+
+@agent.on_action("about")
+async def about(ctx, msg, sel):
+    return cards.info(
+        "About __AGENT_NAME__",
+        rows={
+            "Talks via": "Agent Chat Protocol (ASI:One)",
+            "Brain": "ASI:One LLM with tool calling",
+            "Tools": "get_weather (replace with yours)",
+        },
+        narration="Here's what I'm built from.",
+    )
+
+
+if __name__ == "__main__":
+    agent.run()

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/cursor_mcp.json.tmpl

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "agentverse": {
+      "url": "https://mcp.agentverse.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer ${env:AGENTVERSE_API_KEY}"
+      }
+    }
+  }
+}

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/dockerignore.tmpl

@@ -0,0 +1,7 @@
+.env
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+agent*_data.json
+.git/

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/env.example.tmpl

@@ -0,0 +1,17 @@
+# Your agent's identity. `hackkit new` already generated one into .env.
+# Never commit .env: the seed *is* your agent (address + wallet).
+AGENT_SEED_PHRASE=
+
+# ASI:One LLM key: https://asi1.ai/developer
+ASI_ONE_API_KEY=
+# ASI_ONE_MODEL=asi1
+
+# Agentverse API key: https://agentverse.ai/profile/api-keys
+# With it, the agent registers itself (name, @handle, description, README) on startup.
+AGENTVERSE_API_KEY=
+
+# Your unique @handle on Agentverse (max 40 chars). Check: uv run hackkit handle <name>
+AGENT_HANDLE=__AGENT_HANDLE__
+
+# AGENT_PORT=8000
+# FET_NETWORK=stable-testnet   # or mainnet (real money!)

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/gitignore.tmpl

@@ -0,0 +1,9 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+# uAgents local storage
+agent*_data.json
+private_keys.json

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/mcp.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "agentverse": {
+      "type": "http",
+      "url": "https://mcp.agentverse.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer ${AGENTVERSE_API_KEY}"
+      }
+    }
+  }
+}

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/opencode.json.tmpl

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "asi1/asi1",
+  "small_model": "asi1/asi1-mini",
+  "provider": {
+    "asi1": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "ASI:One",
+      "options": {
+        "baseURL": "https://api.asi1.ai/v1",
+        "apiKey": "{env:ASI_ONE_API_KEY}"
+      },
+      "models": {
+        "asi1": {
+          "name": "ASI1",
+          "limit": {
+            "context": 196000,
+            "output": 40000
+          },
+          "modalities": {
+            "input": [
+              "text",
+              "image"
+            ],
+            "output": [
+              "text"
+            ]
+          }
+        },
+        "asi1-ultra": {
+          "name": "ASI1 Ultra",
+          "limit": {
+            "context": 196000,
+            "output": 40000
+          },
+          "modalities": {
+            "input": [
+              "text"
+            ],
+            "output": [
+              "text"
+            ]
+          }
+        },
+        "asi1-mini": {
+          "name": "ASI1 Mini",
+          "limit": {
+            "context": 196000,
+            "output": 40000
+          },
+          "modalities": {
+            "input": [
+              "text"
+            ],
+            "output": [
+              "text"
+            ]
+          }
+        }
+      }
+    }
+  },
+  "mcp": {
+    "agentverse": {
+      "type": "remote",
+      "url": "https://mcp.agentverse.ai/mcp",
+      "enabled": true,
+      "headers": {
+        "Authorization": "Bearer {env:AGENTVERSE_API_KEY}"
+      },
+      "oauth": false
+    },
+    "agentverse-lite": {
+      "type": "remote",
+      "url": "https://mcp-lite.agentverse.ai/mcp",
+      "enabled": false,
+      "headers": {
+        "Authorization": "Bearer {env:AGENTVERSE_API_KEY}"
+      },
+      "oauth": false
+    }
+  }
+}

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/pyproject.toml.tmpl

@@ -0,0 +1,21 @@
+[project]
+name = "__PROJECT_SLUG__"
+version = "0.1.0"
+description = "__AGENT_NAME__: a Fetch.ai agent built with fetch-hackkit"
+requires-python = ">=3.11"
+dependencies = ["fetch-hackkit[mcp]>=__HACKKIT_VERSION__"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.8"]
+
+[tool.uv]
+package = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.format]
+exclude = ["*.md"]  # keep doc snippets compact

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/python-version.tmpl

@@ -0,0 +1 @@
+3.13

fetch_hackkit-0.2.0/src/fetch_hackkit/templates/project/tests/test_agent.py.tmpl

@@ -0,0 +1,23 @@
+"""Every card your agent can send must pass ASI:One's validation."""
+
+import os
+import sys
+from pathlib import Path
+
+os.environ.setdefault("AGENT_SEED_PHRASE", "unit test seed phrase, not a real agent")
+os.environ["AGENTVERSE_API_KEY"] = ""  # never connect to Agentverse from tests
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from fetch_hackkit.cards import collect_actions, validate
+
+import agent
+
+
+def test_menu_card_is_valid() -> None:
+    card = agent.menu()
+    assert validate(card.kind, card.payload) == []
+
+
+def test_every_menu_button_has_a_handler() -> None:
+    actions = collect_actions(agent.menu().payload)
+    assert actions <= set(agent.agent._action_handlers)

fetch_hackkit-0.2.0/tests/test_scaffold.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import importlib.util
+import stat
+import sys
+from pathlib import Path
+
+import pytest
+from fetch_hackkit import __version__, scaffold
+from fetch_hackkit.cards import collect_actions, validate
+from fetch_hackkit.cli import main
+
+
+def _load_agent(path: Path):
+    spec = importlib.util.spec_from_file_location("generated_agent", path / "agent.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["generated_agent"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+async def test_create_project_writes_a_runnable_project(tmp_path: Path, monkeypatch) -> None:
+    project = scaffold.create_project(
+        "Trip Planner", directory=tmp_path / "trip", check_handle=False
+    )
+    root = project.path
+    expected = {
+        "agent.py",
+        "README.md",
+        "pyproject.toml",
+        ".python-version",
+        ".env",
+        ".env.example",
+        ".gitignore",
+        ".dockerignore",
+        "Dockerfile",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "opencode.json",
+        ".mcp.json",
+        ".cursor/mcp.json",
+        "tests/test_agent.py",
+    }
+    assert expected <= {str(p.relative_to(root)) for p in root.rglob("*") if p.is_file()}
+
+    for path in root.rglob("*"):
+        if path.is_file():
+            assert "__AGENT_" not in path.read_text() and "__PROJECT_" not in path.read_text(), path
+
+    assert project.handle == "trip-planner"
+    env = (root / ".env").read_text()
+    assert "AGENT_HANDLE=trip-planner" in env
+    seed = next(
+        line.split("=", 1)[1] for line in env.splitlines() if line.startswith("AGENT_SEED_PHRASE=")
+    )
+    assert len(seed) >= 32
+    assert stat.S_IMODE((root / ".env").stat().st_mode) == 0o600
+    assert project.address in (root / "README.md").read_text()
+    assert f'"fetch-hackkit[mcp]>={__version__}"' in (root / "pyproject.toml").read_text()
+    agents_md = (root / "AGENTS.md").read_text()
+    assert "Trip Planner" in agents_md and "## Interactive cards (ASI:One UI)" in agents_md
+    assert (root / "CLAUDE.md").resolve() == (root / "AGENTS.md").resolve()
+
+    monkeypatch.setenv("AGENT_SEED_PHRASE", seed)
+    monkeypatch.chdir(root)
+    generated = _load_agent(root)
+    menu = generated.menu()
+    assert validate(menu.kind, menu.payload) == []
+    assert collect_actions(menu.payload) <= set(generated.agent._action_handlers)
+    assert generated.agent.address == project.address
+
+
+def test_refuses_non_empty_directory(tmp_path: Path) -> None:
+    (tmp_path / "x.txt").write_text("hi")
+    with pytest.raises(FileExistsError):
+        scaffold.create_project("A", directory=tmp_path, check_handle=False)
+
+
+def test_taken_handle_gets_a_free_variant(monkeypatch) -> None:
+    monkeypatch.setattr(scaffold, "resolve", lambda h: {"address": "x"} if h == "taken" else None)
+    handle, note = scaffold._choose_handle("taken", check=True)
+    assert handle.startswith("taken-") and "taken" in note
+    assert scaffold._choose_handle("free", check=True) == ("free", "available")
+
+
+def test_slugify() -> None:
+    assert scaffold.slugify("Trip Planner 2.0!") == "trip-planner-2-0"
+    assert scaffold.slugify("🙂") == "my-agent"
+
+
+def test_cli_new(tmp_path: Path, capsys) -> None:
+    assert main(["new", "Rent Splitter", "--dir", str(tmp_path / "rs"), "--no-check"]) == 0
+    out = capsys.readouterr().out
+    assert "@rent-splitter" in out and "uv run python agent.py" in out
+    assert main(["new", "Rent Splitter", "--dir", str(tmp_path / "rs"), "--no-check"]) == 1