CLAUDE.md@cli · diff
git:20260716.b57c4f0 to git:20260812.d0afc1a
4 added, 4 removed. Audit A to A.
# sandwalk — Project Instructions
## What This Is
- Sandwalk is an autonomous agent for open science and drug discovery research —
- like Claude Code, but for biology. It takes natural language questions about
- compounds/targets/indications and executes multi-step research workflows using
- computational biology tools.
+ Sandwalk is an open, self-hosted agent harness for ambitious work — hard
+ scientific research and any other domain the user directs it toward. It ships a
+ deep science toolkit (compounds, targets, structures, omics, clinical, literature)
+ and grows via skills/MCPs. Natural language in; multi-step workflows out.
## Architecture
**Deep Agents (LangGraph) agentic loop**: Query → model (plans, calls tools, self-corrects, synthesizes) → Report
Built on `deepagents`/LangGraph. A single agentic session orchestrates all domain tools, with native
progressive skill discovery and Programmatic Tool Calling (tools injected as Python callables in the
sandbox). Supports Anthropic and OpenAI (including OpenAI-compatible endpoints via `llm.openai_base_url`).
### Key directories:
```
src/
├── agent/ # Runner, MCP server, system prompt, config
├── agent_server/ # Local FastAPI server for the web UI / Mac app
├── tools/ # All research tools (190+), registered via @registry.register()
├── data/ # Data loaders (DepMap, PRISM, L1000, proteomics)
├── models/ # LLM client abstraction
└── ui/ # Interactive terminal
```
## Tool Pattern
Every tool follows this exact pattern:
```python
@registry.register(
name="category.tool_name",
description="What this tool does",
category="category",
parameters={"param": "description"},
requires_data=["proteomics"], # optional
)
def tool_name(param: str = "default", **kwargs) -> dict:
"""Docstring."""
# ... implementation ...
return {
"summary": "Human-readable result summary",
# ... additional data fields ...
}
```
Rules:
- Name prefix MUST match category
- Always accept `**kwargs`
- Always return a dict with a `"summary"` key
- Use lazy imports for data loaders inside the function body
- Use `from data.loaders import load_X` pattern
## Commands
```bash
sandwalk --version # Check version
sandwalk "your question" # Single query
sandwalk # Interactive mode
sandwalk tool list # List all tools
sandwalk config set key value # Set config
sandwalk data pull depmap # Download dataset
pytest tests/ -v # Run tests
ruff check src # Lint
mypy # Typecheck (scoped packages in pyproject.toml)
pip install -e ".[dev]" # Install for development
```
## Testing
Tests use mocked data loaders — never require real datasets.
Mock pattern: `@patch("tools.module.load_X")` to inject test DataFrames.
## Linting
**ruff** (`E,W,F,I,B,C4,UP`, `E501` ignored) + **mypy** (strict, expanding package by package).
Formatter width is `line-length = 100`; long lines are a formatting preference, not a hard reject.
Prefer cohesive modules. Review unusually large files for mixed responsibilities in PR review, but do **not** split files based only on line count.