netcrawl-sdk 0.1.0__tar.gz

netcrawl_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: netcrawl-sdk
+Version: 0.1.0
+Summary: Python SDK for NetCrawl — the programmable idle game
+Author: NetCrawl
+License: MIT
+Project-URL: Homepage, https://github.com/Starscribers/netcrawl-workspace
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# netcrawl Python SDK
+
+Write NetCrawl workers in Python. Workers communicate with the local game server over HTTP.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Quick start
+
+```python
+from netcrawl import WorkerClass, Route
+from netcrawl.items.equipment import Pickaxe
+
+class Collector(WorkerClass):
+    """Harvests ore and returns to hub."""
+    pickaxe = Pickaxe()
+    to_mine = Route("Path from Hub to ore node")
+    to_hub  = Route("Return path back to Hub")
+
+    def on_startup(self):
+        self.trips = 0
+
+    def on_loop(self):
+        self.move_through(self.to_mine)
+        self.collect()
+        self.move_through(self.to_hub)
+        self.deposit()
+        self.trips += 1
+```
+
+## Field types
+
+| Field | Description |
+|---|---|
+| `Pickaxe()` | Consumes 1 Pickaxe from inventory at deploy time |
+| `Shield()` | Consumes 1 Shield from inventory at deploy time |
+| `Beacon()` | Consumes 1 Beacon from inventory at deploy time |
+| `Route("description")` | User specifies a list of node IDs in the UI |
+
+## Worker API
+
+| Method | Description |
+|---|---|
+| `self.move(node_id)` | Move to adjacent node (blocking) |
+| `self.move_through(route)` | Walk a list of node IDs in order |
+| `self.collect()` / `self.harvest()` | Harvest resources at current node |
+| `self.deposit()` | Deposit carried resources at Hub |
+| `self.scan()` | Scan adjacent nodes |
+| `self.repair(node_id)` | Repair an infected adjacent node |
+| `self.info/warn/error(msg)` | Log a message (visible in UI) |
+| `self.current_node` | Current node ID (property) |
+| `self.carrying` | Currently held resources (property) |
+
+## AdvancedGraphGadget mixin
+
+```python
+from netcrawl.mixins.graph import AdvancedGraphGadget
+
+class Explorer(WorkerClass, AdvancedGraphGadget):
+    def on_loop(self):
+        self.travel_to("r3")           # A* pathfinding
+        nearest = self.find_nearest("ore")
+        nodes = self.explore()         # wide-radius scan
+```
+
+## Schema introspection
+
+```python
+print(Collector.get_schema())
+```
+
+## Running examples
+
+```bash
+cd packages/sdk-python
+python examples/test_sdk.py
+```
+

netcrawl_sdk-0.1.0/README.md

@@ -0,0 +1,81 @@
+# netcrawl Python SDK
+
+Write NetCrawl workers in Python. Workers communicate with the local game server over HTTP.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Quick start
+
+```python
+from netcrawl import WorkerClass, Route
+from netcrawl.items.equipment import Pickaxe
+
+class Collector(WorkerClass):
+    """Harvests ore and returns to hub."""
+    pickaxe = Pickaxe()
+    to_mine = Route("Path from Hub to ore node")
+    to_hub  = Route("Return path back to Hub")
+
+    def on_startup(self):
+        self.trips = 0
+
+    def on_loop(self):
+        self.move_through(self.to_mine)
+        self.collect()
+        self.move_through(self.to_hub)
+        self.deposit()
+        self.trips += 1
+```
+
+## Field types
+
+| Field | Description |
+|---|---|
+| `Pickaxe()` | Consumes 1 Pickaxe from inventory at deploy time |
+| `Shield()` | Consumes 1 Shield from inventory at deploy time |
+| `Beacon()` | Consumes 1 Beacon from inventory at deploy time |
+| `Route("description")` | User specifies a list of node IDs in the UI |
+
+## Worker API
+
+| Method | Description |
+|---|---|
+| `self.move(node_id)` | Move to adjacent node (blocking) |
+| `self.move_through(route)` | Walk a list of node IDs in order |
+| `self.collect()` / `self.harvest()` | Harvest resources at current node |
+| `self.deposit()` | Deposit carried resources at Hub |
+| `self.scan()` | Scan adjacent nodes |
+| `self.repair(node_id)` | Repair an infected adjacent node |
+| `self.info/warn/error(msg)` | Log a message (visible in UI) |
+| `self.current_node` | Current node ID (property) |
+| `self.carrying` | Currently held resources (property) |
+
+## AdvancedGraphGadget mixin
+
+```python
+from netcrawl.mixins.graph import AdvancedGraphGadget
+
+class Explorer(WorkerClass, AdvancedGraphGadget):
+    def on_loop(self):
+        self.travel_to("r3")           # A* pathfinding
+        nearest = self.find_nearest("ore")
+        nodes = self.explore()         # wide-radius scan
+```
+
+## Schema introspection
+
+```python
+print(Collector.get_schema())
+```
+
+## Running examples
+
+```bash
+cd packages/sdk-python
+python examples/test_sdk.py
+```
+

netcrawl_sdk-0.1.0/netcrawl/__init__.py

@@ -0,0 +1,23 @@
+from netcrawl.base import WorkerClass
+from netcrawl.network.edge import Edge
+from netcrawl.network.route import Route
+from netcrawl.app import NetCrawl
+from netcrawl.icons import Icon
+from netcrawl.items import Pickaxe, Shield, Beacon, SensorGadget, BasicSensor, AdvancedSensor
+from netcrawl.services import CacheService, ServiceNotReachable
+from netcrawl.nodes import (
+    BaseNode, HubNode, ResourceNode,
+    ComputeNode, ComputeTask, APINode, APIRequestObj,
+    LockedNode, InfectedNode, NodeEdge,
+)
+from netcrawl.sensors import EdgeInfo, AdvancedEdgeInfo
+
+__all__ = [
+    "WorkerClass", "Edge", "Route", "NetCrawl", "Icon",
+    "Pickaxe", "Shield", "Beacon", "SensorGadget", "BasicSensor", "AdvancedSensor",
+    "CacheService", "ServiceNotReachable",
+    "BaseNode", "HubNode", "ResourceNode",
+    "ComputeNode", "ComputeTask", "APINode", "APIRequestObj",
+    "LockedNode", "InfectedNode", "NodeEdge",
+    "EdgeInfo", "AdvancedEdgeInfo",
+]

netcrawl_sdk-0.1.0/netcrawl/app.py

@@ -0,0 +1,176 @@
+"""
+netcrawl/app.py
+
+NetCrawl code server — registers worker classes with the game server,
+polls for deploy requests, and spawns worker subprocesses.
+"""
+
+import time
+from typing import Type
+
+from netcrawl.base import WorkerClass
+from netcrawl.client import http_post, http_get
+from netcrawl.daemon.spawner import spawn_worker, kill_worker, list_active
+
+
+class NetCrawl:
+    """
+    Code server that bridges your worker classes with the game server.
+
+    Usage:
+        app = NetCrawl(server="http://localhost:4800")
+        app.register(Miner)
+        app.register(Guardian)
+        app.run()
+    """
+
+    def __init__(self, server: str = "http://localhost:4800", api_key: str = ""):
+        self.server = server.rstrip("/")
+        self.api_key = api_key
+        self._classes: dict[str, Type[WorkerClass]] = {}
+        self._class_files: dict[str, str] = {}
+
+    def register(self, cls: Type[WorkerClass]) -> None:
+        """Register a worker class for deployment. Raises on duplicate class_id."""
+        import inspect
+        class_id = cls.class_id
+        class_name = cls.class_name
+
+        if class_id in self._classes:
+            existing = self._classes[class_id]
+            raise ValueError(
+                f"Duplicate class_id '{class_id}': "
+                f"{cls.__name__} conflicts with {existing.__name__}"
+            )
+
+        self._classes[class_id] = cls
+        source_file = inspect.getfile(cls)
+        self._class_files[class_id] = source_file
+        print(f"[NetCrawl] Registered: {class_name} (id={class_id})")
+
+    def _post(self, path: str, data: dict) -> dict:
+        return http_post(f"{self.server}{path}", data)
+
+    def _get(self, path: str) -> dict:
+        return http_get(f"{self.server}{path}")
+
+    def _register_all(self) -> None:
+        """Register all worker classes with the game server."""
+        classes = []
+        for class_id, cls in self._classes.items():
+            schema = cls.get_schema()
+            schema["file"] = self._class_files.get(class_id, "")
+            schema["language"] = "python"
+            classes.append(schema)
+
+        result = self._post("/api/worker-classes/register", {"classes": classes})
+        if result.get("ok"):
+            print(f"[NetCrawl] Registered {result.get('registered', 0)} worker classes")
+        else:
+            print(f"[NetCrawl] Registration failed: {result.get('error')}")
+
+    def _poll_deploy_queue(self) -> None:
+        """Poll the game server for pending deploy requests and spawn workers."""
+        try:
+            result = self._get("/api/deploy-queue")
+            requests = result.get("requests", [])
+            for req in requests:
+                self._handle_deploy(req)
+        except Exception as e:
+            pass  # Server might be temporarily unreachable
+
+    def _handle_deploy(self, deploy_req: dict) -> None:
+        """Spawn a worker subprocess for a deploy request."""
+        worker_id = deploy_req["workerId"]
+        class_id = deploy_req["classId"]
+        node_id = deploy_req["nodeId"]
+        injected_fields = deploy_req.get("injectedFields", {})
+
+        cls = self._classes.get(class_id)
+        if not cls:
+            print(f"[NetCrawl] Unknown class_id: {class_id}")
+            self._post("/api/deploy-ack", {
+                "workerId": worker_id,
+                "error": f"Unknown worker class_id: {class_id}",
+            })
+            return
+
+        script_path = self._class_files.get(class_id, "")
+        print(f"[NetCrawl] Spawning {cls.class_name} (id={class_id}, worker={worker_id}) on node {node_id}")
+
+        try:
+            pid = spawn_worker(
+                worker_id=worker_id,
+                script_path=script_path,
+                class_name=cls.__name__,  # Python class name for import
+                api_url=self.server,
+                injected_fields=injected_fields,
+            )
+            print(f"[NetCrawl] Spawned {cls.class_name} — PID {pid}")
+            self._post("/api/deploy-ack", {
+                "workerId": worker_id,
+                "pid": pid,
+            })
+        except Exception as e:
+            print(f"[NetCrawl] Spawn failed: {e}")
+            self._post("/api/deploy-ack", {
+                "workerId": worker_id,
+                "error": str(e),
+            })
+
+    def _wait_for_server(self, timeout: int = 30) -> bool:
+        """Wait for the game server to be reachable."""
+        start = time.time()
+        while time.time() - start < timeout:
+            try:
+                result = self._get("/health")
+                if result.get("status") == "ok":
+                    return True
+            except Exception:
+                pass
+            time.sleep(1)
+        return False
+
+    def run(self) -> None:
+        """
+        Start the code server:
+        1. Wait for the game server
+        2. Register all worker classes
+        3. Poll for deploy requests every second
+        4. Re-register every 30s to handle server restarts
+        """
+        print(f"[NetCrawl] Code Server starting...")
+        print(f"[NetCrawl] Server: {self.server}")
+        worker_list = ', '.join(f"{cls.class_name}({cid})" for cid, cls in self._classes.items())
+        print(f"[NetCrawl] Workers: {worker_list}")
+        print()
+
+        # Wait for server
+        print("[NetCrawl] Waiting for game server...")
+        if not self._wait_for_server():
+            print("[NetCrawl] ERROR: Game server not reachable. Is it running?")
+            return
+
+        print("[NetCrawl] Game server connected!")
+        self._register_all()
+
+        print()
+        print("[NetCrawl] Code server running. Polling for deploy requests...")
+        print("[NetCrawl] Press Ctrl+C to stop.")
+
+        register_counter = 0
+        try:
+            while True:
+                self._poll_deploy_queue()
+                time.sleep(1)
+
+                # Re-register every 30 polls (~30s)
+                register_counter += 1
+                if register_counter >= 30:
+                    register_counter = 0
+                    self._register_all()
+        except KeyboardInterrupt:
+            print("\n[NetCrawl] Shutting down...")
+            for u in list_active():
+                kill_worker(u["worker_id"])
+            print("[NetCrawl] All workers stopped. Goodbye!")