awdk 3.6.0__py3-none-any.whl

adk/AGENT_PROMPT.md

@@ -0,0 +1,236 @@
+# AitherADK Agent Setup Prompt
+# Copy this entire block into Claude Code, Cursor, Copilot, or any AI coding agent.
+# Version: 1.5.0 | Updated: 2026-05-23
+
+You are setting up the AitherADK agent development kit. Follow these steps exactly.
+Do NOT deviate from these instructions -- they encode solutions to real failure modes.
+
+## Critical Facts
+
+- The CLI command is `adk`, NOT `aither`. The `aither` command is a separate REPL.
+- The pip package is `awdk`. Install: `pip install awdk`
+- Auto-detection works. `LLMRouter()` with no args finds vLLM, Ollama, or cloud backends.
+- All config lives in `~/.aither/` -- never set env vars manually unless told to.
+
+## Step 1: Install
+
+```bash
+pip install "awdk"
+adk --help
+```
+
+Verify `adk --help` shows subcommands: init, setup, login, connect, run, status, whoami.
+If `adk` is not found, check `pip show awdk` and ensure your PATH includes pip scripts.
+
+## Step 2: Check existing infrastructure
+
+```bash
+adk status
+```
+
+Read the output carefully:
+- **vLLM UP on :8200** -> You already have inference. DO NOT run `adk setup`. Go to Step 4.
+- **Ollama UP** -> You have inference. Go to Step 4.
+- **Genesis UP on :8001** -> Full AitherOS is running. Go to Step 4.
+- **Everything DOWN** -> You need inference. Go to Step 3.
+
+## Step 3: Set up inference (ONLY if nothing is running)
+
+```bash
+adk setup
+```
+
+This is an interactive wizard. It auto-detects your GPU and recommends a tier.
+
+- NVIDIA GPU with 8GB+ VRAM -> vLLM containers (parallel inference, recommended)
+- AMD/Apple/No GPU -> Ollama (serialized, but works everywhere)
+- First run downloads 16-30GB of model weights. Takes 10-15 minutes. Be patient.
+- For CI/automation: `adk setup --non-interactive`
+- For dry run: `adk setup --dry-run`
+
+**WARNING: NEVER run `adk setup` if vLLM is already running on your GPU.**
+It will start a competing container that fights for VRAM and crash with OOM.
+v1.1.2+ detects this and offers "connect to existing" automatically.
+
+After setup completes, verify: `adk status` should show vLLM or Ollama as UP.
+
+## Step 4: Authenticate
+
+Check current auth status:
+```bash
+adk whoami
+```
+
+If not logged in, choose one:
+```bash
+adk login                        # Opens browser -- approve on portal (recommended)
+adk login --email you@example.com  # Email/password flow
+adk login --api-key aither_pat_... # Direct API key (from portal)
+```
+
+To generate a key manually: portal.aitherium.com → Settings → API Keys → "+ New Token".
+
+Auth is optional for local-only usage. Required for cloud inference, sovereign deploy, and fleet sync.
+
+## Step 5: Create an agent project
+
+```bash
+adk init my-agent
+cd my-agent
+```
+
+This creates:
+- `agent.py` -- Agent definition with a sample tool
+- `config.yaml` -- Backend, model, port configuration
+- `tools.py` -- Custom tool definitions
+
+## Step 6: Test basic chat
+
+```python
+import asyncio
+from adk import AitherAgent
+
+async def main():
+    agent = AitherAgent("my-agent")
+    response = await agent.chat("Hello! What can you help me with?")
+    print(response.content)
+
+asyncio.run(main())
+```
+
+The LLMRouter auto-detects backends in this priority order:
+1. vLLM on port 8200 (highest priority -- continuous batching)
+2. Desktop AitherOS MicroScheduler
+3. Ollama on port 11434
+4. Aitherium Gateway (cloud, needs auth)
+5. OpenAI/Anthropic API keys (if set)
+
+## Step 7: Add custom tools
+
+```python
+import asyncio
+from adk import AitherAgent
+
+agent = AitherAgent("my-agent")
+
+@agent.tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"Weather in {city}: 72F, sunny"
+
+@agent.tool
+def search_docs(query: str) -> str:
+    """Search project documentation."""
+    return f"Found 3 results for: {query}"
+
+async def main():
+    response = await agent.chat("What's the weather in Tokyo?")
+    print(response.content)
+
+asyncio.run(main())
+```
+
+The agent has 7 built-in tools enabled by default:
+`file_read`, `file_write`, `file_edit`, `file_list`, `file_search`, `web_search`, `web_fetch`
+
+## Step 8: Run the API server
+
+```bash
+adk run                                    # Single agent, reads config.yaml
+adk run --identity lyra --port 9000        # Specific identity + port
+adk run --agents lyra,atlas,demiurge       # Fleet mode (parallel agents)
+```
+
+This starts a FastAPI server with an OpenAI-compatible endpoint at `/v1/chat/completions`.
+
+## Step 9: Fleet mode (multi-agent)
+
+```python
+import asyncio
+from adk.fleet import FleetConfig
+
+async def main():
+    fleet = FleetConfig(agent_names=["aither", "lyra", "atlas"])
+    # Each agent gets its own personality, tools, and conversation state
+    # All share the same LLM backend via continuous batching
+
+asyncio.run(main())
+```
+
+17 bundled identities: aither, apollo, athena, atlas, chaos, demiurge, hera,
+hydra, iris, lyra, morgana, muse, prometheus, saga, themis, vera, viviane.
+
+## Step 10: Graph memory (optional)
+
+```python
+# Store knowledge
+await agent.graph_remember("user", "prefers", "dark mode")
+await agent.graph_remember("project", "uses", "FastAPI")
+
+# Query knowledge
+results = await agent.graph_query("What does the user prefer?")
+```
+
+Graph memory is SQLite-backed, works offline, persisted at `~/.aither/graph/`.
+
+## Step 11: Deploy sovereign node (optional)
+
+Deploy a full AitherOS instance on your own hardware that federates with the hub.
+
+```bash
+# Full node with GPU, dashboard, and mesh + register with hub
+adk deploy node --gpu --dashboard --mesh --sovereign
+
+# Lighter: core services only + federation
+adk deploy core --sovereign
+
+# Specify tenant and hub URL
+adk deploy node --sovereign --tenant my-org --hub https://portal.aitherium.com
+
+# Dry run (show what would happen)
+adk deploy node --sovereign --dry-run
+```
+
+After deployment:
+- Node auto-registers with `portal.aitherium.com/federation/register`
+- Federation credentials saved to `~/.aither/.env.federation`
+- Node appears in your fleet dashboard at `/workspace/fleet`
+- Heartbeats keep the hub updated with status and metrics
+
+Check federation status: `adk connect`
+
+---
+
+## Common Mistakes (avoid these)
+
+1. **Wrong CLI**: `aither` is NOT `adk`. Use `adk init`, `adk setup`, `adk run`.
+2. **Double vLLM**: Never run `adk setup` when vLLM is already on your GPU.
+   Always check `adk status` first.
+3. **Wrong env var**: Don't set `AITHER_API_KEY`. Run `adk login` instead --
+   it saves the token to `~/.aither/config.yaml` automatically.
+4. **Wrong tool names**: Built-in tools are `file_read`, `file_write`,
+   `file_edit` -- NOT `read_file`, `write_file`.
+5. **Wrong memory API**: Use `agent.graph_remember()` and `agent.graph_query()`,
+   NOT `GraphMemory.add_triple()`.
+6. **Elysium no-key**: `Elysium()` without args works -- it reads from saved config.
+   Don't pass `api_key=""` explicitly.
+7. **IRC noise**: `adk run` starts an IRC bridge on port 6667. This is normal,
+   not an error.
+
+## Quick Reference
+
+| I want to...              | Command / Code                                    |
+|---------------------------|---------------------------------------------------|
+| Install                   | `pip install awdk`                          |
+| Check system              | `adk status`                                      |
+| Set up GPU inference      | `adk setup`                                       |
+| Login                     | `adk login`                                       |
+| Check auth                | `adk whoami`                                      |
+| Create project            | `adk init my-agent`                               |
+| Run agent                 | `adk run`                                         |
+| Run fleet                 | `adk run --agents lyra,atlas`                     |
+| Start API server          | `adk run --port 8080`                             |
+| Diagnose issues           | `adk doctor`                                      |
+| Connect to cloud          | `adk connect --api-key KEY`                       |
+| Deploy sovereign node     | `adk deploy node --sovereign`                     |
+| Register with hub         | `adk register`                                    |

adk/LANDMARK_MAP_INTEGRATION.md

@@ -0,0 +1,286 @@
+# Landmark Map Integration Guide
+
+## Overview
+
+`landmark_map.py` implements Prospector Phase 1's semantic region indexing. It:
+
+1. **Extends project_map** with landmark metadata (tools, skills, intent hints)
+2. **Persists snapshots** with HMAC integrity (CodeGraph pattern)
+3. **Ranks landmarks** by keyword + intent multiplier
+4. **Fails open** — empty snapshot returns [], never crashes
+5. **Reuses proven patterns** — no core-service edits needed
+
+## Architecture
+
+### Dataclasses
+
+```python
+@dataclass
+class LandmarkNode:
+    id: str                          # "landmark_0", "landmark_auth", etc.
+    name: str                        # "Authentication", "Routing", etc.
+    rank: int                        # 0=highest importance
+    purpose: str                     # "auth", "routing", "api", etc.
+    files: List[str]                # absolute paths in this landmark
+    tools: List[str]                # tool names defined here (Phase 2+)
+    skills: List[str]]              # skills available here (Phase 2+)
+    intent_hints: Dict[str, float]  # {"CODE": 1.3, "DEBUG": 1.1, ...}
+
+@dataclass
+class LandmarkSnapshot:
+    root: str                        # project root
+    n_landmarks: int                 # from project_map
+    landmarks: List[LandmarkNode]   # indexed semantic regions
+    edges: List[LandmarkEdge]       # cross-landmark dependencies
+    built_at: str                    # ISO timestamp
+    hint_quality: Dict              # surprise_events, precision_metrics, etc.
+```
+
+### Persistence (HMAC Pattern)
+
+Files are stored in `$AITHER_DATA_DIR/Library/Data/`:
+
+```
+{root-sha8}_landmark_snapshot.pkl      # pickle object
+{root-sha8}_landmark_snapshot.pkl.hmac # HMAC-SHA256 sidecar
+```
+
+**HMAC key** comes from `$AITHER_INTERNAL_SECRET` env var (or default).
+
+**Verification**: missing/corrupt HMAC → refuse load, return `None` (fail-open).
+
+## Public APIs
+
+### Load & Query
+
+```python
+from adk.landmark_map import load_landmark_snapshot, hints_for
+
+# Load snapshot (returns None if missing or corrupt)
+snapshot = load_landmark_snapshot(root="/path/to/project")
+
+# Query with intent scaling
+if snapshot:
+    dirs = snapshot.hints_for(
+        "where is tool ranking decided?",
+        intent_type="CODE",  # optional: "CODE", "DEBUG", "CONVERSATION", etc.
+        k=3
+    )
+else:
+    # Graceful fallback to project_map
+    from lib.cognitive.project_map import hints_for as pm_hints
+    dirs = pm_hints("where is tool ranking?", root)
+```
+
+### Build from project_map
+
+```python
+from lib.cognitive.project_map import load_map
+from adk.landmark_map import LandmarkSnapshot, save_landmark_snapshot
+
+# Load project_map (from arc-agi-3 builder)
+pm = load_map(root="/path/to/project")
+
+# Enrich into snapshot (Phase 1: synthetic landmarks from purpose grouping)
+snapshot = LandmarkSnapshot.from_project_map(pm)
+
+# Persist with HMAC
+save_landmark_snapshot(snapshot, root_path=pm["root"])
+```
+
+### Export for Embedding
+
+```python
+# Export deterministic JSONL for vLLM embedding (concept_card style)
+result = snapshot.export_jsonl("/tmp/landmarks.jsonl")
+# {"exported": 42, "output_path": "...", "generated_at": "2026-07-15T..."}
+```
+
+### Status
+
+```python
+from adk.landmark_map import landmark_status
+
+status = landmark_status(root="/project")
+# {
+#   "available": true,
+#   "root": "/project",
+#   "n_landmarks": 42,
+#   "built_at": "2026-07-15T...",
+#   "landmarks": ["Auth", "Routing", ...],
+#   "edges": 156
+# }
+```
+
+## Ranking Algorithm
+
+For each landmark, compute:
+
+```
+keyword_score = 4 * distinct_terms + name_hits*3 + purpose_hits*2 + file_hits
+intent_boost = landmark.intent_hints[intent_type] * INTENT_RELEVANCE_SCALE[intent_type]
+final_score = keyword_score * intent_boost
+
+sorted by final_score (descending)
+```
+
+Where:
+- `distinct_terms` = number of unique query terms matched (not repetition count)
+- `intent_type` defaults to `"DEFAULT"` (scale = 1.0)
+- Returns top-k **files** (not landmarks), sorted by score
+
+## Fail-Open Behavior
+
+**Never crashes.** Returns empty results on:
+
+- Missing snapshot
+- Corrupt HMAC
+- Empty query
+- No matching landmarks
+- Unparseable pickle
+
+All error paths log and return `[]` or `None` gracefully.
+
+## Integration Points (Zero Core Edits)
+
+### Read-Only Reuse
+
+| Component | Lines | Usage |
+|-----------|-------|-------|
+| `project_map.load_map()` | 52-85 | Load base map for enrichment |
+| `project_map._keyword_rank()` | 108-131 | Stopword set (reused) |
+| `CodeGraph.concept_card()` | 368-393 | Deterministic JSON format pattern |
+| `CodeGraph._verify_pickle_hmac()` | 246-265 | Exact HMAC verification logic |
+| `CodeGraph._compute_file_hmac()` | 237-243 | Exact HMAC computation logic |
+| `CodeGraph._write_pickle_hmac()` | 268-275 | Exact sidecar writing logic |
+| `ContextPipeline._INTENT_RELEVANCE_SCALE` | 4257-4277 | Intent → score mapping |
+| `ContextPipeline._coarse_code_intent()` | 263-277 | Fallback classifier (not used yet) |
+
+### Subscribe-Only (Phase 2+)
+
+- `SurpriseDetector.observe()` — feed surprise signals for training
+- `LearnedWorldModel.TransitionDataset.record()` — persist training data for fine-tuning
+- `CodeGraph.hybrid_query()` — semantic rank (when enriching from arc-agi-3)
+
+## Phase Roadmap
+
+**Phase 1 (NOW):**
+- [x] LandmarkNode + LandmarkSnapshot dataclasses
+- [x] Persistence with HMAC (atomic tmp+replace)
+- [x] Keyword ranking from purpose grouping
+- [x] Export to deterministic JSONL
+- [x] Fail-open behavior (no crashes)
+
+**Phase 2 (next):**
+- [ ] Enrich from arc-agi-3 builder (tools[], skills[], edges[])
+- [ ] Semantic rank (CodeGraph.hybrid_query integration)
+- [ ] MCP tool `map_localize()` in Genesis
+- [ ] Integrate `hints_for()` into ContextPipeline context seams
+
+**Phase 3 (research):**
+- [ ] Subscribe to SurpriseDetector for training signals
+- [ ] Regret tracking (when hint was used but unhelpful)
+- [ ] Fine-tune intent_hints via LearnedWorldModel
+- [ ] Concept-card embedding (vLLM prompt cache reuse)
+
+## Example: Full Workflow
+
+```python
+#!/usr/bin/env python3
+"""Complete Prospector Phase 1 workflow."""
+
+from lib.cognitive.project_map import load_map
+from adk.landmark_map import (
+    LandmarkSnapshot,
+    save_landmark_snapshot,
+    load_landmark_snapshot,
+    hints_for,
+)
+
+# Step 1: Load project_map from arc-agi-3
+root = "/path/to/project"
+pm = load_map(root)
+if not pm:
+    print("No project_map found — run arc-agi-3 builder first")
+    exit(1)
+
+# Step 2: Enrich into snapshot (Phase 1: synthetic from purpose)
+snapshot = LandmarkSnapshot.from_project_map(pm)
+print(f"Created {len(snapshot.landmarks)} landmarks")
+
+# Step 3: Persist with HMAC
+if save_landmark_snapshot(snapshot, root_path=root):
+    print(f"Saved snapshot to Library/Data/")
+
+# Step 4: Query with intent scaling
+hints = hints_for(
+    "where is rate limiting enforced?",
+    root=root,
+    intent_type="CODE",
+    k=3
+)
+print(f"Top-3 directories to search:\n{chr(10).join(hints)}")
+
+# Step 5: Export for embedding (Phase 2+)
+snapshot = load_landmark_snapshot(root)
+if snapshot:
+    result = snapshot.export_jsonl("/tmp/landmarks.jsonl")
+    print(f"Exported {result['exported']} landmarks to JSONL")
+```
+
+## Testing
+
+All 9 core tests pass:
+
+```bash
+pytest adk/test_landmark_map.py -v
+
+✓ test_terms_of
+✓ test_landmark_node_to_dict
+✓ test_landmark_snapshot_from_project_map
+✓ test_snapshot_hints_for_code_intent
+✓ test_snapshot_hints_for_conversation_intent
+✓ test_snapshot_fail_open_empty
+✓ test_save_and_load_snapshot
+✓ test_export_jsonl
+✓ test_hints_for_public_api
+```
+
+## Lint Status
+
+```bash
+ruff check adk/landmark_map.py
+ruff check adk/test_landmark_map.py
+
+# Result: All checks passed!
+```
+
+## Key Design Decisions
+
+1. **Fail-open**: Returns `[]` or `None`, never crashes. Users can always fall back to `project_map.hints_for()`.
+
+2. **HMAC integrity**: Exact CodeGraph pattern. Any deviation breaks cache validation.
+
+3. **Deterministic output**: JSON with `sort_keys=True, ensure_ascii=True`, sorted edge lists. Same state → byte-identical JSONL.
+
+4. **Lazy imports**: Core deps (CodeGraph, ContextPipeline) imported in functions, not at module level. Allows fallback if unavailable.
+
+5. **Intent scaling**: Reads `_INTENT_RELEVANCE_SCALE` read-only; never edits ContextPipeline.
+
+6. **Standalone**: Zero core-service edits. Lives in awdk, importable as `from adk.landmark_map import ...`.
+
+## Future: Moving to Core
+
+When Phase 2/3 integrate into Genesis. This describes a change inside the
+AitherOS server-side core, not anything you run from this package — the import
+below is server-side and will not resolve in an `awdk` install.
+
+```python
+# Before (Phase 1 — awdk, what this package ships)
+from adk.landmark_map import hints_for
+
+# After (Phase 2+ — AitherOS core library, server-side; same code)
+from lib.cognitive.landmark_map import hints_for
+```
+
+Zero API changes needed — just move the file.