crabpath

# CrabPath Pure graph core: zero required deps and no network calls. Caller provides callbacks. ## Design Tenets - No network calls in core - No secret discovery (no dotfiles, keychain, or env probing) - No subprocess provider wrappers - Embedder identity in state metadata; dimension mismatches are errors - One canonical state format (`state.json`) ## Quick Start ```python from crabpath import split_workspace, HashEmbedder, VectorIndex graph, texts = split_workspace("./workspace") embedder = HashEmbedder() index = VectorIndex() for nid, content in texts.items(): index.upsert(nid, embedder.embed(content)) ``` ## Embeddings and LLM callbacks - Default: `HashEmbedder` (hash-v1, 1024-dim) - Real: callback `embed_fn` / `embed_batch_fn` (e.g., `text-embedding-3-small`) - LLM routing: callback `llm_fn` using `gpt-5-mini` (example) ## Session Replay `replay_queries(graph, queries)` can warm-start from historical turns. ## CLI `--state` is preferred: `crabpath query TEXT --state S [--top N] [--json]` `crabpath query TEXT --state S --chat-id CID` `crabpath doctor --state S` `crabpath info --state S` `crabpath init --workspace W --output O --embedder openai` `crabpath query TEXT --state S --llm openai` `crabpath inject --state S --type TEACHING [--type DIRECTIVE]` Real-time correction flow: `python3 query_brain.py --chat-id CHAT_ID` `python3 learn_correction.py --chat-id CHAT_ID` ## Quick Reference - `crabpath init/query/learn/inject/health/doctor/info` - `query_brain.py --chat-id` and `learn_correction.py` for real-time correction pipelines - `query_brain.py` traversal limits: `beam_width=8`, `max_hops=30`, `fire_threshold=0.01` - Hard traversal caps: `max_fired_nodes` and `max_context_chars` (defaults `None`; `query_brain.py` defaults `max_context_chars=20000`) - `examples/correction_flow/`, `examples/cold_start/`, `examples/openai_embedder/` ## API Reference - Core lifecycle: - `split_workspace` - `load_state` - `save_state` - `ManagedState` - `VectorIndex` - Traversal and learning: - `traverse` - `TraversalConfig` - `TraversalConfig.beam_width`, `.max_hops`, `.fire_threshold`, `.max_fired_nodes`, `.max_context_chars`, `.reflex_threshold`, `.habitual_range`, `.inhibitory_threshold` - `TraversalResult` - `apply_outcome` - Runtime injection APIs: - `inject_node` - `inject_correction` - `inject_batch` - Maintenance helpers: - `suggest_connections`, `apply_connections` - `suggest_merges`, `apply_merge` - `measure_health`, `autotune`, `replay_queries` - Embedding utilities: - `HashEmbedder` - `OpenAIEmbedder` - `default_embed` - `default_embed_batch` - `openai_llm_fn` - LLM routing callbacks: - `chat_completion` - Graph primitives: - `Node` - `Edge` - `Graph` - `split_workspace` - `generate_summaries` ## CLI Commands - `crabpath init --workspace W --output O [--sessions S] [--embedder openai]` - `crabpath query TEXT --state S [--top N] [--json] [--chat-id CHAT_ID]` - `crabpath learn --state S --outcome N --fired-ids a,b,c [--json]` - `crabpath inject --state S --id NODE_ID --content TEXT [--type CORRECTION|TEACHING|DIRECTIVE] [--json] [--connect-min-sim 0.0]` - `crabpath inject --state S --id NODE_ID --content TEXT --type TEACHING` - `crabpath inject --state S --id NODE_ID --content TEXT --type DIRECTIVE` - `crabpath health --state S` - `crabpath doctor --state S` - `crabpath info --state S` - `crabpath replay --state S --sessions S` - `crabpath merge --state S [--llm openai]` - `crabpath connect --state S [--llm openai]` - `crabpath journal [--stats]` - `query_brain.py --chat-id CHAT_ID` - `learn_correction.py --chat-id CHAT_ID` ## Traversal defaults - `beam_width=8` - `max_hops=30` - `fire_threshold=0.01` - `reflex_threshold=0.6` - `habitual_range=0.2-0.6` - `inhibitory_threshold=-0.01` - `max_fired_nodes` (hard node-count cap, default `None`) - `max_context_chars` (hard context cap, default `None`; `query_brain.py` default is `20000`) ## Paper https://jonathangu.com/crabpath/