crawlerverse 0.1.0__tar.gz

crawlerverse-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+.next/
+out/
+dist/
+build/
+next-env.d.ts
+
+# Turbo
+.turbo/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Headless runner traces
+.traces/
+
+# Playwright
+playwright-report/
+test-results/
+.playwright-mcp/
+
+# Worktrees
+.worktrees/
+
+# Generated assets (copied by postinstall)
+packages/crawler-core/public/dice-box-assets/
+apps/web/public/dice-box-assets/
+
+# PWA service worker (generated at build time)
+packages/crawler-core/public/sw.js
+packages/crawler-core/public/workbox-*.js
+
+# Misc
+*.tsbuildinfo

crawlerverse-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: crawlerverse
+Version: 0.1.0
+Summary: Python SDK for the Crawler Agent API
+Project-URL: Homepage, https://crawlerver.se
+Project-URL: Documentation, https://crawlerver.se/docs/agent-api
+Project-URL: Repository, https://github.com/reluctantfuturist/crawlerverse
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.78.0; extra == 'dev'
+Requires-Dist: openai>=2.17.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crawlerverse
+
+Python SDK for the [Crawler Agent API](https://crawlerver.se/docs/agent-api). Build AI agents that play the Crawler roguelike game.
+
+## Installation
+
+```bash
+pip install crawlerverse
+```
+
+## Quick Start
+
+```python
+from crawlerverse import CrawlerClient, run_game, Move, Wait, Direction, Observation, Action
+
+def my_agent(observation: Observation) -> Action:
+    # Attack any adjacent monster
+    monster = observation.nearest_monster()
+    if monster:
+        tile, _ = monster
+        dx = tile.x - observation.player.position[0]
+        dy = tile.y - observation.player.position[1]
+        if abs(dx) <= 1 and abs(dy) <= 1:
+            # Monster is adjacent, determine direction
+            for d in Direction:
+                if observation.can_move(d):
+                    return Move(direction=d)
+
+    # Otherwise just wait
+    return Wait()
+
+with CrawlerClient(api_key="cra_...") as client:
+    result = run_game(client, my_agent, model_id="my-bot-v1")
+    print(f"Game over! Floor {result.outcome.floor}, result: {result.outcome.status}")
+```
+
+## Authentication
+
+Set your API key via parameter or environment variable:
+
+```python
+# Option 1: Pass directly
+client = CrawlerClient(api_key="cra_...")
+
+# Option 2: Environment variable
+# export CRAWLERVERSE_API_KEY=cra_...
+client = CrawlerClient()
+```
+
+## Async Support
+
+```python
+from crawlerverse import AsyncCrawlerClient, async_run_game
+
+async with AsyncCrawlerClient() as client:
+    result = await async_run_game(client, my_agent)
+```
+
+## API Reference
+
+### Client Methods
+
+```python
+client.games.create(model_id="gpt-4o")      # Start a new game
+client.games.list(status="completed")         # List your games
+client.games.get(game_id)                     # Get game state
+client.games.action(game_id, Move(...))       # Submit action
+client.games.abandon(game_id)                 # Abandon game
+client.health()                               # Health check
+```
+
+### Actions
+
+```python
+Move(direction=Direction.NORTH)
+Attack(direction=Direction.EAST)
+Wait()
+Pickup()
+Drop(item_type="health-potion")
+Use(item_type="health-potion")
+Equip(item_type="iron-sword")
+EnterPortal()
+RangedAttack(direction=Direction.SOUTH, distance=5)
+```
+
+### Observation Helpers
+
+```python
+obs.tile_at(x, y)          # Look up tile by coordinates
+obs.monsters()              # All visible monsters
+obs.nearest_monster()       # Closest monster
+obs.items_at_feet()         # Items at player's position
+obs.has_item("sword")       # Check inventory
+obs.can_move(Direction.NORTH)  # Check if direction is walkable
+```
+
+## Examples
+
+All examples default to a local API at `http://localhost:3000/api/agent`. Set `CRAWLERVERSE_BASE_URL` to point at production.
+
+### OpenAI
+
+See [`examples/openai_agent.py`](examples/openai_agent.py):
+
+```bash
+pip install openai
+export CRAWLERVERSE_API_KEY=cra_...
+export OPENAI_API_KEY=sk-...
+python examples/openai_agent.py
+```
+
+Works with any OpenAI-compatible provider (Ollama, LMStudio, Azure, etc.) via `OPENAI_BASE_URL`.
+
+### Anthropic (Claude)
+
+See [`examples/anthropic_agent.py`](examples/anthropic_agent.py):
+
+```bash
+pip install anthropic
+export CRAWLERVERSE_API_KEY=cra_...
+export ANTHROPIC_API_KEY=sk-ant-...
+python examples/anthropic_agent.py
+```
+
+Uses Claude Haiku 4.5 by default. Override with `ANTHROPIC_MODEL=claude-sonnet-4-5`.
+
+### Local LLM (Ollama / LMStudio)
+
+See [`examples/local_llm_agent.py`](examples/local_llm_agent.py) for a script with configurable turn limits and error recovery:
+
+```bash
+pip install openai
+export CRAWLERVERSE_API_KEY=cra_...
+export OPENAI_BASE_URL=http://localhost:11434/v1
+export OPENAI_MODEL=llama3
+python examples/local_llm_agent.py
+```
+
+Supports `MAX_TURNS` (default 25) and `MODEL_ID` env vars.
+
+## License
+
+MIT

crawlerverse-0.1.0/README.md

@@ -0,0 +1,143 @@
+# crawlerverse
+
+Python SDK for the [Crawler Agent API](https://crawlerver.se/docs/agent-api). Build AI agents that play the Crawler roguelike game.
+
+## Installation
+
+```bash
+pip install crawlerverse
+```
+
+## Quick Start
+
+```python
+from crawlerverse import CrawlerClient, run_game, Move, Wait, Direction, Observation, Action
+
+def my_agent(observation: Observation) -> Action:
+    # Attack any adjacent monster
+    monster = observation.nearest_monster()
+    if monster:
+        tile, _ = monster
+        dx = tile.x - observation.player.position[0]
+        dy = tile.y - observation.player.position[1]
+        if abs(dx) <= 1 and abs(dy) <= 1:
+            # Monster is adjacent, determine direction
+            for d in Direction:
+                if observation.can_move(d):
+                    return Move(direction=d)
+
+    # Otherwise just wait
+    return Wait()
+
+with CrawlerClient(api_key="cra_...") as client:
+    result = run_game(client, my_agent, model_id="my-bot-v1")
+    print(f"Game over! Floor {result.outcome.floor}, result: {result.outcome.status}")
+```
+
+## Authentication
+
+Set your API key via parameter or environment variable:
+
+```python
+# Option 1: Pass directly
+client = CrawlerClient(api_key="cra_...")
+
+# Option 2: Environment variable
+# export CRAWLERVERSE_API_KEY=cra_...
+client = CrawlerClient()
+```
+
+## Async Support
+
+```python
+from crawlerverse import AsyncCrawlerClient, async_run_game
+
+async with AsyncCrawlerClient() as client:
+    result = await async_run_game(client, my_agent)
+```
+
+## API Reference
+
+### Client Methods
+
+```python
+client.games.create(model_id="gpt-4o")      # Start a new game
+client.games.list(status="completed")         # List your games
+client.games.get(game_id)                     # Get game state
+client.games.action(game_id, Move(...))       # Submit action
+client.games.abandon(game_id)                 # Abandon game
+client.health()                               # Health check
+```
+
+### Actions
+
+```python
+Move(direction=Direction.NORTH)
+Attack(direction=Direction.EAST)
+Wait()
+Pickup()
+Drop(item_type="health-potion")
+Use(item_type="health-potion")
+Equip(item_type="iron-sword")
+EnterPortal()
+RangedAttack(direction=Direction.SOUTH, distance=5)
+```
+
+### Observation Helpers
+
+```python
+obs.tile_at(x, y)          # Look up tile by coordinates
+obs.monsters()              # All visible monsters
+obs.nearest_monster()       # Closest monster
+obs.items_at_feet()         # Items at player's position
+obs.has_item("sword")       # Check inventory
+obs.can_move(Direction.NORTH)  # Check if direction is walkable
+```
+
+## Examples
+
+All examples default to a local API at `http://localhost:3000/api/agent`. Set `CRAWLERVERSE_BASE_URL` to point at production.
+
+### OpenAI
+
+See [`examples/openai_agent.py`](examples/openai_agent.py):
+
+```bash
+pip install openai
+export CRAWLERVERSE_API_KEY=cra_...
+export OPENAI_API_KEY=sk-...
+python examples/openai_agent.py
+```
+
+Works with any OpenAI-compatible provider (Ollama, LMStudio, Azure, etc.) via `OPENAI_BASE_URL`.
+
+### Anthropic (Claude)
+
+See [`examples/anthropic_agent.py`](examples/anthropic_agent.py):
+
+```bash
+pip install anthropic
+export CRAWLERVERSE_API_KEY=cra_...
+export ANTHROPIC_API_KEY=sk-ant-...
+python examples/anthropic_agent.py
+```
+
+Uses Claude Haiku 4.5 by default. Override with `ANTHROPIC_MODEL=claude-sonnet-4-5`.
+
+### Local LLM (Ollama / LMStudio)
+
+See [`examples/local_llm_agent.py`](examples/local_llm_agent.py) for a script with configurable turn limits and error recovery:
+
+```bash
+pip install openai
+export CRAWLERVERSE_API_KEY=cra_...
+export OPENAI_BASE_URL=http://localhost:11434/v1
+export OPENAI_MODEL=llama3
+python examples/local_llm_agent.py
+```
+
+Supports `MAX_TURNS` (default 25) and `MODEL_ID` env vars.
+
+## License
+
+MIT

crawlerverse-0.1.0/examples/anthropic_agent.py

@@ -0,0 +1,227 @@
+"""Example: Use Anthropic Claude to play Crawler.
+
+Usage:
+    export CRAWLERVERSE_API_KEY=cra_...
+    export ANTHROPIC_API_KEY=sk-ant-...
+    python examples/anthropic_agent.py
+
+Requirements (not included in crawlerverse):
+    pip install anthropic
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+
+from anthropic import Anthropic
+
+from crawlerverse import (
+    Action,
+    Attack,
+    CrawlerClient,
+    Drop,
+    EnterPortal,
+    Equip,
+    Move,
+    Observation,
+    Pickup,
+    RangedAttack,
+    Use,
+    Wait,
+    run_game,
+)
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+log = logging.getLogger("crawlerverse")
+log.setLevel(logging.DEBUG)
+
+SYSTEM_PROMPT = """\
+You are an AI agent playing Crawler, a roguelike dungeon game.
+Each turn you receive an observation and must choose ONE action.
+Respond with a JSON object (no markdown, no explanation).
+
+## Actions
+  {"action": "move", "direction": "<dir>"}
+  {"action": "attack", "direction": "<dir>"}
+  {"action": "ranged_attack", "direction": "<dir>", "distance": <1-15>}
+  {"action": "pickup"}
+  {"action": "drop", "itemType": "<item>"}
+  {"action": "use", "itemType": "<item>"}
+  {"action": "equip", "itemType": "<item>"}
+  {"action": "wait"}
+  {"action": "enter_portal"}
+
+Directions: north, south, east, west, northeast, northwest, southeast, southwest
+
+## Strategy Tips
+- Kill monsters to clear the path. Attack adjacent monsters.
+- Pick up items (potions, weapons, armor) — they help you survive.
+- Equip weapons and armor for better stats.
+- Use health potions when HP is low.
+- Find stairs down to descend to the next floor.
+- Explore systematically; avoid getting surrounded.
+
+Always include a "reasoning" field explaining your decision."""
+
+ACTION_MAP: dict[str, type[Action]] = {
+    "move": Move,
+    "attack": Attack,
+    "wait": Wait,
+    "pickup": Pickup,
+    "drop": Drop,
+    "use": Use,
+    "equip": Equip,
+    "enter_portal": EnterPortal,
+    "ranged_attack": RangedAttack,
+}
+
+
+def format_observation(obs: Observation) -> str:
+    """Format observation into a detailed prompt for Claude."""
+    p = obs.player
+    lines = [
+        f"Turn {obs.turn} | Floor {obs.floor}",
+        f"HP: {p.hp}/{p.max_hp} | ATK: {p.attack} | DEF: {p.defense}",
+        f"Position: ({p.position[0]}, {p.position[1]})",
+    ]
+
+    if p.equipped_weapon:
+        lines.append(f"Weapon: {p.equipped_weapon}")
+    if p.equipped_armor:
+        lines.append(f"Armor: {p.equipped_armor}")
+
+    if obs.inventory:
+        inv = ", ".join(f"{i.name} ({i.type})" for i in obs.inventory)
+        lines.append(f"Inventory: {inv}")
+
+    lines.append("")
+    lines.append("Visible tiles:")
+    for tile in obs.visible_tiles:
+        parts = [f"  ({tile.x},{tile.y}) {tile.type}"]
+        if tile.monster:
+            m = tile.monster
+            parts.append(f"[MONSTER: {m.type} HP:{m.hp}/{m.max_hp}]")
+        if tile.items:
+            parts.append(f"[ITEMS: {', '.join(tile.items)}]")
+        lines.append(" ".join(parts))
+
+    if obs.messages:
+        lines.append("")
+        lines.append("Messages:")
+        for msg in obs.messages:
+            lines.append(f"  {msg}")
+
+    return "\n".join(lines)
+
+
+def parse_action(raw: str) -> Action:
+    """Parse Claude's response into an Action, with fallback to Wait."""
+    text = raw.strip()
+    if text.startswith("```"):
+        text = text.split("\n", 1)[1] if "\n" in text else text[3:]
+    if text.endswith("```"):
+        text = text[:-3]
+    text = text.strip()
+
+    # Extract JSON if surrounded by other text
+    if not text.startswith("{"):
+        start = text.find("{")
+        if start >= 0:
+            end = text.rfind("}")
+            if end > start:
+                text = text[start : end + 1]
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        log.warning("Failed to parse Claude response as JSON: %s", text[:100])
+        return Wait(reasoning="Failed to parse response")
+
+    action_type = data.get("action", "wait")
+    cls = ACTION_MAP.get(action_type)
+    if cls is None:
+        log.warning("Unknown action type: %s", action_type)
+        return Wait(reasoning=f"Unknown action: {action_type}")
+
+    # Build kwargs from the response, filtering to known fields
+    valid_fields = set(cls.model_fields.keys())
+    kwargs = {}
+    for k, v in data.items():
+        if k != "action" and k in valid_fields:
+            kwargs[k] = v
+
+    # Handle camelCase -> snake_case for itemType
+    if "itemType" in data and "item_type" in valid_fields:
+        kwargs["item_type"] = data["itemType"]
+
+    try:
+        return cls(**kwargs)
+    except Exception as e:
+        log.warning("Failed to construct %s: %s", action_type, e)
+        return Wait(reasoning=f"Failed to construct {action_type}")
+
+
+def make_agent(model: str = "claude-haiku-4-5-20251001"):
+    """Create an agent function that uses Anthropic Claude to decide actions."""
+    client = Anthropic()
+    messages: list[dict[str, str]] = []
+
+    def agent(obs: Observation) -> Action:
+        prompt = format_observation(obs)
+        messages.append({"role": "user", "content": prompt})
+
+        # Prefill assistant turn with "{" to force JSON output
+        prefill = {"role": "assistant", "content": "{"}
+        response = client.messages.create(
+            model=model,
+            system=SYSTEM_PROMPT,
+            messages=[*messages, prefill],
+            temperature=0.3,
+            max_tokens=200,
+        )
+
+        reply = "{" + response.content[0].text
+        messages.append({"role": "assistant", "content": reply})
+
+        action = parse_action(reply)
+        log.info("Turn %d: %s", obs.turn, action.model_dump_json(by_alias=True))
+        return action
+
+    return agent
+
+
+def main():
+    model = os.environ.get("ANTHROPIC_MODEL", "claude-haiku-4-5-20251001")
+    model_id = os.environ.get("MODEL_ID", f"anthropic/{model}")
+
+    print(f"Starting game with model: {model} (leaderboard ID: {model_id})")
+    print()
+
+    agent = make_agent(model=model)
+
+    base_url = os.environ.get(
+        "CRAWLERVERSE_BASE_URL", "http://localhost:3000/api/agent"
+    )
+
+    with CrawlerClient(base_url=base_url) as client:
+        result = run_game(
+            client,
+            agent,
+            model_id=model_id,
+            on_step=lambda obs, action: None,
+        )
+
+    outcome = result.outcome
+    print()
+    print(f"Game over! {outcome.status}")
+    print(f"  Floor reached: {outcome.floor}")
+    print(f"  Total turns: {outcome.turns}")
+    if hasattr(outcome, "result"):
+        print(f"  Result: {outcome.result}")
+    print(f"  Watch replay: {result.spectator_url}")
+
+
+if __name__ == "__main__":
+    main()