trajrl 0.2.0__tar.gz

trajrl-0.2.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: trajrl
+Version: 0.2.0
+Summary: CLI for TrajectoryRL, Bittensor subnet 11 — agent-friendly access to live validator, miner, and evaluation data.
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9
+Requires-Dist: httpx>=0.25
+Requires-Dist: rich>=13.0
+
+# trajrl
+
+CLI for the [TrajectoryRL subnet](https://trajrl.com) (Bittensor SN11). Query live validator, miner, and evaluation data from the terminal.
+
+Designed for AI agents (Claude Code, Cursor) and humans alike — outputs JSON when piped, Rich tables when interactive.
+
+## Install
+
+```bash
+pip install trajrl
+```
+
+## Commands
+
+```
+trajrl status                          # Network health overview
+trajrl validators                      # List all validators
+trajrl scores <validator_hotkey>       # Per-miner scores from a validator
+trajrl scores --uid <uid>              # Query by validator UID instead
+trajrl miner <hotkey>                  # Miner detail + diagnostics
+trajrl miner --uid <uid>               # Query by miner UID instead
+trajrl pack <hotkey> <pack_hash>       # Pack evaluation detail
+trajrl submissions [--failed]          # Recent pack submissions
+trajrl eval-history <validator>        # List eval cycle IDs for a validator
+trajrl eval-history <v> --from <date>  # Filter by date range
+trajrl cycle-log <validator>           # Download and display a cycle log
+trajrl cycle-log <v> --format summary  # Show parsed summary tables
+trajrl logs [--type cycle|miner]       # Eval log archives
+trajrl --version                       # Show CLI version
+```
+
+### Global Options
+
+Every command accepts:
+
+| Option | Description |
+|--------|-------------|
+| `--json` / `-j` | Force JSON output (auto-enabled when stdout is piped) |
+| `--base-url URL` | Override API base (default: `https://trajrl.com`, env: `TRAJRL_BASE_URL`) |
+| `--version` / `-v` | Show CLI version and exit |
+
+### New in v0.2.0
+
+- **UID support**: Query validators and miners by UID instead of hotkey
+  ```bash
+  trajrl miner --uid 65      # Instead of full hotkey
+  trajrl scores --uid 221    # Query validator by UID
+  ```
+
+- **Date filtering**: Filter eval history by date range
+  ```bash
+  trajrl eval-history 5Cd6h... --from 2026-03-25 --to 2026-03-26
+  ```
+
+- **Cycle log summary**: Parse cycle logs into structured tables
+  ```bash
+  trajrl cycle-log 5Cd6h... --format summary
+  ```
+  Shows: eval metrics, winner info, top qualified miners in tables instead of raw text
+
+- **Version command**: Check your CLI version
+  ```bash
+  trajrl --version
+  ```
+
+## Usage Examples
+
+### Quick network check
+
+```bash
+trajrl status
+```
+```
+╭──────────────────── Network Status ────────────────────╮
+│   Validators: 7 total, 7 active (seen <1h)             │
+│   LLM Models: zhipu/glm-5 (3), chutes/GLM-5-TEE (3)    │
+│   Latest Eval: 7h ago                                  │
+│   Submissions: 65 passed, 35 failed (last batch)       │
+╰────────────────────────────────────────────────────────╯
+```
+
+### List validators
+
+```bash
+trajrl validators
+```
+```
+ Hotkey         UID  Version  LLM Model              Last Eval   Last Seen
+ 5Cd6h…sn11     29  0.2.7    chutes/zai-org/GLM-5…   7h ago      2m ago
+ 5EcgNd…797f   221  0.2.7    zhipu/glm-5             10h ago     6m ago
+ ...
+```
+
+### Inspect a miner
+
+By hotkey:
+```bash
+trajrl miner 5HMgR6LnNqUAtaKRwa6bLF4Vy4KBf7TaxCLehyff9mWPhSHt
+```
+
+Or by UID (v0.2.0+):
+```bash
+trajrl miner --uid 65
+```
+
+Shows rank, qualification status, cost, scenario breakdown, per-validator reports, recent submissions, and ban records.
+
+### View failed submissions
+
+```bash
+trajrl submissions --failed
+```
+
+### Investigate a validator's eval cycle
+
+First, list recent eval cycles for a validator:
+
+```bash
+trajrl eval-history 5Cd6h...
+```
+```
+            Eval IDs (5) — 5Cd6h…sn11
+ Eval ID            Validator    Block  Logs  Created
+ 20260325_060012    5Cd6h…sn11  421890    12  3h ago
+ 20260324_060008    5Cd6h…sn11  421530    11  1d ago
+ 20260323_060015    5Cd6h…sn11  421170    13  2d ago
+ ...
+```
+
+Then fetch the full cycle log for a specific eval:
+
+```bash
+trajrl cycle-log 5Cd6h... --eval-id 20260325_060012
+```
+
+Or just grab the latest one:
+
+```bash
+trajrl cycle-log 5Cd6h...
+```
+
+The cycle log contains the complete eval cycle output: metagraph sync, miner enumeration, per-miner eval timing, WEIGHT RESULTS, and set_weights status.
+
+> **Note:** Eval IDs are defined by each validator independently (typically a timestamp like `20260325_060012`). They are **not** globally unique — the same eval ID from different validators refers to different evaluation cycles. Always pair an eval ID with a specific validator hotkey.
+
+### Filter eval logs
+
+```bash
+trajrl logs --type cycle --limit 5
+trajrl logs --validator 5Cd6h... --type miner
+trajrl logs --eval-id 20260324_000340
+```
+
+### JSON output for agents
+
+Pipe to any tool — JSON is automatic:
+
+```bash
+trajrl validators | jq '.validators[].hotkey'
+trajrl scores 5Cd6h... --json | python3 -c "
+  import sys, json
+  d = json.load(sys.stdin)
+  for e in d['entries'][:5]:
+      print(f\"{e['minerHotkey'][:12]}  qual={e['qualified']}  cost={e['costUsd']}\")
+"
+```
+
+Force JSON in an interactive terminal:
+
+```bash
+trajrl miner 5HMgR6... --json
+```
+
+## API Reference
+
+All data comes from the [TrajectoryRL Public API](https://trajrl.com) — read-only, no authentication required.
+
+| Endpoint | CLI Command |
+|----------|-------------|
+| `GET /api/validators` | `trajrl validators` |
+| `GET /api/scores/by-validator?validator=` | `trajrl scores <hotkey>` |
+| `GET /api/miners/:hotkey` | `trajrl miner <hotkey>` |
+| `GET /api/miners/:hotkey/packs/:hash` | `trajrl pack <hotkey> <hash>` |
+| `GET /api/submissions` | `trajrl submissions` |
+| `GET /api/eval-logs` | `trajrl logs` |
+| `GET /api/eval-logs?log_type=cycle` | `trajrl eval-history <hotkey>` |
+| `GET /api/eval-logs` + GCS download | `trajrl cycle-log <hotkey>` |
+
+## Development
+
+```bash
+git clone <repo> && cd trajrl
+pip install -e .
+trajrl --help
+```

trajrl-0.2.0/README.md

@@ -0,0 +1,195 @@
+# trajrl
+
+CLI for the [TrajectoryRL subnet](https://trajrl.com) (Bittensor SN11). Query live validator, miner, and evaluation data from the terminal.
+
+Designed for AI agents (Claude Code, Cursor) and humans alike — outputs JSON when piped, Rich tables when interactive.
+
+## Install
+
+```bash
+pip install trajrl
+```
+
+## Commands
+
+```
+trajrl status                          # Network health overview
+trajrl validators                      # List all validators
+trajrl scores <validator_hotkey>       # Per-miner scores from a validator
+trajrl scores --uid <uid>              # Query by validator UID instead
+trajrl miner <hotkey>                  # Miner detail + diagnostics
+trajrl miner --uid <uid>               # Query by miner UID instead
+trajrl pack <hotkey> <pack_hash>       # Pack evaluation detail
+trajrl submissions [--failed]          # Recent pack submissions
+trajrl eval-history <validator>        # List eval cycle IDs for a validator
+trajrl eval-history <v> --from <date>  # Filter by date range
+trajrl cycle-log <validator>           # Download and display a cycle log
+trajrl cycle-log <v> --format summary  # Show parsed summary tables
+trajrl logs [--type cycle|miner]       # Eval log archives
+trajrl --version                       # Show CLI version
+```
+
+### Global Options
+
+Every command accepts:
+
+| Option | Description |
+|--------|-------------|
+| `--json` / `-j` | Force JSON output (auto-enabled when stdout is piped) |
+| `--base-url URL` | Override API base (default: `https://trajrl.com`, env: `TRAJRL_BASE_URL`) |
+| `--version` / `-v` | Show CLI version and exit |
+
+### New in v0.2.0
+
+- **UID support**: Query validators and miners by UID instead of hotkey
+  ```bash
+  trajrl miner --uid 65      # Instead of full hotkey
+  trajrl scores --uid 221    # Query validator by UID
+  ```
+
+- **Date filtering**: Filter eval history by date range
+  ```bash
+  trajrl eval-history 5Cd6h... --from 2026-03-25 --to 2026-03-26
+  ```
+
+- **Cycle log summary**: Parse cycle logs into structured tables
+  ```bash
+  trajrl cycle-log 5Cd6h... --format summary
+  ```
+  Shows: eval metrics, winner info, top qualified miners in tables instead of raw text
+
+- **Version command**: Check your CLI version
+  ```bash
+  trajrl --version
+  ```
+
+## Usage Examples
+
+### Quick network check
+
+```bash
+trajrl status
+```
+```
+╭──────────────────── Network Status ────────────────────╮
+│   Validators: 7 total, 7 active (seen <1h)             │
+│   LLM Models: zhipu/glm-5 (3), chutes/GLM-5-TEE (3)    │
+│   Latest Eval: 7h ago                                  │
+│   Submissions: 65 passed, 35 failed (last batch)       │
+╰────────────────────────────────────────────────────────╯
+```
+
+### List validators
+
+```bash
+trajrl validators
+```
+```
+ Hotkey         UID  Version  LLM Model              Last Eval   Last Seen
+ 5Cd6h…sn11     29  0.2.7    chutes/zai-org/GLM-5…   7h ago      2m ago
+ 5EcgNd…797f   221  0.2.7    zhipu/glm-5             10h ago     6m ago
+ ...
+```
+
+### Inspect a miner
+
+By hotkey:
+```bash
+trajrl miner 5HMgR6LnNqUAtaKRwa6bLF4Vy4KBf7TaxCLehyff9mWPhSHt
+```
+
+Or by UID (v0.2.0+):
+```bash
+trajrl miner --uid 65
+```
+
+Shows rank, qualification status, cost, scenario breakdown, per-validator reports, recent submissions, and ban records.
+
+### View failed submissions
+
+```bash
+trajrl submissions --failed
+```
+
+### Investigate a validator's eval cycle
+
+First, list recent eval cycles for a validator:
+
+```bash
+trajrl eval-history 5Cd6h...
+```
+```
+            Eval IDs (5) — 5Cd6h…sn11
+ Eval ID            Validator    Block  Logs  Created
+ 20260325_060012    5Cd6h…sn11  421890    12  3h ago
+ 20260324_060008    5Cd6h…sn11  421530    11  1d ago
+ 20260323_060015    5Cd6h…sn11  421170    13  2d ago
+ ...
+```
+
+Then fetch the full cycle log for a specific eval:
+
+```bash
+trajrl cycle-log 5Cd6h... --eval-id 20260325_060012
+```
+
+Or just grab the latest one:
+
+```bash
+trajrl cycle-log 5Cd6h...
+```
+
+The cycle log contains the complete eval cycle output: metagraph sync, miner enumeration, per-miner eval timing, WEIGHT RESULTS, and set_weights status.
+
+> **Note:** Eval IDs are defined by each validator independently (typically a timestamp like `20260325_060012`). They are **not** globally unique — the same eval ID from different validators refers to different evaluation cycles. Always pair an eval ID with a specific validator hotkey.
+
+### Filter eval logs
+
+```bash
+trajrl logs --type cycle --limit 5
+trajrl logs --validator 5Cd6h... --type miner
+trajrl logs --eval-id 20260324_000340
+```
+
+### JSON output for agents
+
+Pipe to any tool — JSON is automatic:
+
+```bash
+trajrl validators | jq '.validators[].hotkey'
+trajrl scores 5Cd6h... --json | python3 -c "
+  import sys, json
+  d = json.load(sys.stdin)
+  for e in d['entries'][:5]:
+      print(f\"{e['minerHotkey'][:12]}  qual={e['qualified']}  cost={e['costUsd']}\")
+"
+```
+
+Force JSON in an interactive terminal:
+
+```bash
+trajrl miner 5HMgR6... --json
+```
+
+## API Reference
+
+All data comes from the [TrajectoryRL Public API](https://trajrl.com) — read-only, no authentication required.
+
+| Endpoint | CLI Command |
+|----------|-------------|
+| `GET /api/validators` | `trajrl validators` |
+| `GET /api/scores/by-validator?validator=` | `trajrl scores <hotkey>` |
+| `GET /api/miners/:hotkey` | `trajrl miner <hotkey>` |
+| `GET /api/miners/:hotkey/packs/:hash` | `trajrl pack <hotkey> <hash>` |
+| `GET /api/submissions` | `trajrl submissions` |
+| `GET /api/eval-logs` | `trajrl logs` |
+| `GET /api/eval-logs?log_type=cycle` | `trajrl eval-history <hotkey>` |
+| `GET /api/eval-logs` + GCS download | `trajrl cycle-log <hotkey>` |
+
+## Development
+
+```bash
+git clone <repo> && cd trajrl
+pip install -e .
+trajrl --help
+```

trajrl-0.2.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trajrl"
+version = "0.2.0"
+description = "CLI for TrajectoryRL, Bittensor subnet 11 — agent-friendly access to live validator, miner, and evaluation data."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "typer>=0.9",
+    "httpx>=0.25",
+    "rich>=13.0",
+]
+
+[project.scripts]
+trajrl = "trajrl.cli:app"

trajrl-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trajrl-0.2.0/trajrl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

trajrl-0.2.0/trajrl/api.py

@@ -0,0 +1,185 @@
+"""Typed HTTP client for the TrajectoryRL public API."""
+
+from __future__ import annotations
+
+import gzip
+import io
+import tarfile
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://trajrl.com"
+_TIMEOUT = 30.0
+
+
+def extract_cycle_log(archive_bytes: bytes) -> str | None:
+    """Extract validator.log text from a cycle log archive (tar.gz or gzip)."""
+    try:
+        buf = io.BytesIO(archive_bytes)
+        with tarfile.open(fileobj=buf, mode="r:gz") as tar:
+            for member in tar.getmembers():
+                if member.name.endswith("validator.log"):
+                    f = tar.extractfile(member)
+                    if f:
+                        return f.read().decode("utf-8", errors="replace")
+    except Exception:
+        pass
+    try:
+        return gzip.decompress(archive_bytes).decode("utf-8", errors="replace")
+    except Exception:
+        pass
+    return archive_bytes.decode("utf-8", errors="replace")
+
+
+@dataclass
+class TrajRLClient:
+    base_url: str = DEFAULT_BASE_URL
+    _client: httpx.Client = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._client = httpx.Client(
+            base_url=self.base_url.rstrip("/"),
+            timeout=_TIMEOUT,
+            headers={"Accept": "application/json"},
+        )
+
+    # -- endpoints ---------------------------------------------------------
+
+    def validators(self) -> dict[str, Any]:
+        """GET /api/validators"""
+        return self._get("/api/validators")
+
+    def scores_by_validator(self, validator: str | None = None, uid: int | None = None) -> dict[str, Any]:
+        """GET /api/scores/by-validator?validator=<hotkey> or resolve UID to hotkey."""
+        if uid is not None:
+            # Resolve UID to hotkey via validators endpoint
+            validators_data = self.validators()
+            for vali in validators_data.get("validators", []):
+                if vali.get("uid") == uid:
+                    validator = vali.get("hotkey")
+                    if validator:
+                        return self._get("/api/scores/by-validator", params={"validator": validator})
+            raise ValueError(f"Could not find validator with UID {uid}")
+        if validator is None:
+            raise ValueError("Either validator hotkey or uid must be provided")
+        return self._get("/api/scores/by-validator", params={"validator": validator})
+
+    def miner(self, hotkey: str | None = None, uid: int | None = None) -> dict[str, Any]:
+        """GET /api/miners/:hotkey or resolve UID to hotkey first."""
+        if uid is not None:
+            # Resolve UID to hotkey via validators endpoint
+            validators_data = self.validators()
+            # Search through validator scores to find miner by UID
+            # This is a fallback - ideally the API would support UID lookup
+            for vali in validators_data.get("validators", []):
+                vali_key = vali.get("hotkey")
+                if vali_key:
+                    try:
+                        scores = self.scores_by_validator(vali_key)
+                        for entry in scores.get("entries", []):
+                            if entry.get("uid") == uid:
+                                hotkey = entry.get("minerHotkey")
+                                if hotkey:
+                                    return self._get(f"/api/miners/{hotkey}")
+                    except Exception:
+                        continue
+            raise ValueError(f"Could not resolve UID {uid} to a miner hotkey")
+        if hotkey is None:
+            raise ValueError("Either hotkey or uid must be provided")
+        return self._get(f"/api/miners/{hotkey}")
+
+    def pack(self, hotkey: str, pack_hash: str) -> dict[str, Any]:
+        """GET /api/miners/:hotkey/packs/:packHash"""
+        return self._get(f"/api/miners/{hotkey}/packs/{pack_hash}")
+
+    def submissions(self, limit: int | None = None) -> dict[str, Any]:
+        """GET /api/submissions"""
+        return self._get("/api/submissions", params=_compact({"limit": limit}))
+
+    def eval_logs(
+        self,
+        *,
+        validator: str | None = None,
+        miner: str | None = None,
+        log_type: str | None = None,
+        eval_id: str | None = None,
+        pack_hash: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict[str, Any]:
+        """GET /api/eval-logs
+
+        Args:
+            from_date: ISO 8601 date/datetime string (e.g. "2026-03-25" or "2026-03-25T00:00:00Z")
+            to_date: ISO 8601 date/datetime string (e.g. "2026-03-26" or "2026-03-26T23:59:59Z")
+        """
+        params = _compact({
+            "validator": validator,
+            "miner": miner,
+            "type": log_type,
+            "eval_id": eval_id,
+            "pack_hash": pack_hash,
+            "from": from_date,
+            "to": to_date,
+            "limit": limit,
+            "offset": offset,
+        })
+        return self._get("/api/eval-logs", params=params)
+
+    def cycle_log(
+        self,
+        validator: str,
+        *,
+        eval_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Fetch the latest cycle log text for a validator.
+
+        Uses the eval-logs endpoint to find the cycle log entry, then
+        downloads and extracts the validator.log from the archive.
+
+        Returns ``{"log_entry": <metadata dict>, "text": <log text>}``.
+        Raises ``ValueError`` when no usable cycle log is found.
+        """
+        params: dict[str, Any] = {"validator": validator, "log_type": "cycle"}
+        if eval_id is not None:
+            params["eval_id"] = eval_id
+        else:
+            params["limit"] = 5
+
+        data = self.eval_logs(**params)
+        logs = data.get("logs", [])
+        if not logs:
+            raise ValueError("No cycle logs found for this validator")
+
+        log_entry = logs[0]
+        gcs_url = log_entry.get("gcsUrl")
+        if not gcs_url:
+            raise ValueError("Cycle log has no download URL")
+
+        try:
+            resp = httpx.get(gcs_url, timeout=30, follow_redirects=True)
+            resp.raise_for_status()
+        except Exception as exc:
+            raise ValueError(f"Failed to download cycle log: {exc}") from exc
+
+        text = extract_cycle_log(resp.content)
+        if not text:
+            raise ValueError("Failed to extract validator.log from archive")
+
+        return {"log_entry": log_entry, "text": text}
+
+    # -- internal ----------------------------------------------------------
+
+    def _get(self, path: str, params: dict | None = None) -> dict[str, Any]:
+        resp = self._client.get(path, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _compact(d: dict) -> dict:
+    """Remove None values from a dict."""
+    return {k: v for k, v in d.items() if v is not None}