inkvell 0.2.2
InkVell - Multi-agent framework for scientific research and data science
License: MIT
Requires Python: <3.13,>=3.12
Keywords: adk, agents, ai, claude, data-science, llm, multi-agent, scientific-research

# InkVell

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/inkvell.svg?icon=si%3Apython)](https://badge.fury.io/py/inkvell)

**Multi-Agent Framework for Scientific Research and Data Science**

InkVell is an open-source framework that uses a sophisticated multi-agent workflow to tackle complex data science and scientific research tasks. Built on Google's Agent Development Kit (ADK) and Claude Agent SDK, it separates planning from execution, validates work continuously, and adapts its approach based on progress.

## Features

- **@mention-Based Agent Routing**: Simply `@karpathy` for data science or `@feynman` for scientific writing
- **Adaptive Multi-Agent Workflow**: Iterative planning, execution, validation, and reflection
- **Scientific Writer Agent**: Generate LaTeX papers, citations, and research documents
- **Cross-Agent Handoff**: Seamlessly pass analysis results to the scientific writer
- **Intelligent Planning**: Creates comprehensive analysis plans before starting work
- **Continuous Validation**: Tracks progress against success criteria at every step
- **Self-Correcting**: Reviews and adapts the plan based on discoveries during execution
- **MCP Integration**: Tool access via Model Context Protocol servers
- **Scientific Skills**: 380+ pre-built scientific analysis capabilities
- **Web Application**: Hosted version with real-time streaming UI
- **Network Access Control**: Optional isolation for enterprise environments
- **Extensible**: Customize prompts, agents, and workflows
- **Easy Installation**: Available via pip and uvx

## Quick Start

### Prerequisites

Before using InkVell, you must have:

1. **Claude Code CLI** installed
   ```bash
   npm install -g @anthropic-ai/claude-code
   ```
   Or visit [Claude Code Quickstart](https://docs.anthropic.com/en/docs/claude-code/quickstart)

2. **Required API Keys** configured (see Configuration section below)
   - OPENROUTER_API_KEY (for planning and review agents)
   - ANTHROPIC_API_KEY (for coding agent)

### Installation

```bash
# Install from PyPI
uv tool install inkvell

# Or use with uvx (no installation needed)
uvx inkvell --mode simple "your query here"
```

### Configuration

**API Keys**

You must configure two API keys:

1. **OpenRouter API Key** (required for planning and review agents):
   ```bash
   export OPENROUTER_API_KEY="your_key_here"
   ```
   Get your key at: https://openrouter.ai/keys

2. **Anthropic API Key** (required for coding agent):
   ```bash
   export ANTHROPIC_API_KEY="your_key_here"
   ```
   Get your key at: https://console.anthropic.com/

Alternatively, create a `.env` file in your project directory:
```bash
OPENROUTER_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
```

**Network Access Control** (Optional)

By default, agents have access to network tools (web search and URL fetching). To disable network access:

```bash
export DISABLE_NETWORK_ACCESS=true
```

This disables:
- `fetch_url` tool for ADK agents
- `WebFetch` and `WebSearch` tools for Claude Code agent

Network access is enabled by default. Set to "true" or "1" to disable.

### Basic Usage

InkVell uses **@mentions** to route queries to specialized agents:

| Mention | Agent | Use Case |
|---------|-------|----------|
| `@karpathy` | Data Scientist | Complex analysis, ML, statistics |
| `@feynman` | Scientific Writer | Papers, LaTeX, citations |
| *(none)* | Claude Code | Quick coding, explanations |

**Working Directory**: By default, files are saved to `./inkvell_output/` in your current directory and preserved after completion.

#### @karpathy - Data Scientist (Orchestrated Analysis)

```bash
# Complex analysis with planning, execution, and validation
inkvell "@karpathy Perform differential expression analysis" --files data.csv

# Multiple files with custom working directory
inkvell "@karpathy Compare datasets and identify trends" -f data1.csv -f data2.csv --working-dir ./my_analysis

# Directory upload (recursive)
inkvell "@karpathy Analyze all data and build predictive model" --files data_folder/
```

#### @feynman - Scientific Writer (Papers & Documents)

```bash
# Write a research paper based on prior analysis
inkvell "@feynman Write a Nature-style paper based on my analysis results"

# Generate documentation with citations
inkvell "@feynman Create a methods section with proper citations" --files methods_notes.md

# Cross-agent handoff: Run @karpathy first, then @feynman in the same directory
inkvell "@karpathy Analyze RNA-seq data for differential expression" --files data.csv --working-dir ./project
inkvell "@feynman Write a paper about the differential expression findings" --working-dir ./project
```

#### Simple Mode (Direct Claude Code)

```bash
# Quick coding tasks without @mention (defaults to simple mode)
inkvell "Write a Python script to parse CSV files"

# Question answering
inkvell "Explain how gradient boosting works"

# Explicitly use --mode simple
inkvell "Quick data exploration" --mode simple --files data.csv --temp-dir
```

#### Additional Options

```bash
# Custom log file location
inkvell "@karpathy Analyze data" --files data.csv --log-file ./analysis.log

# Verbose logging for debugging
inkvell "Debug issue" --files data.csv --verbose

# Temporary directory with auto-cleanup
inkvell "Quick test" --files data.csv --temp-dir
```

## How It Works

InkVell provides three specialized agents, each designed for different tasks:

### Agent Routing

When you use `@mentions`, InkVell automatically routes your query to the appropriate agent:

```
@karpathy → Data Scientist Agent (orchestrated multi-agent workflow)
@feynman  → Scientific Writer Agent (papers, LaTeX, citations)
(no mention) → Claude Code Agent (direct coding, simple mode)
```

### @karpathy: Data Scientist Workflow

The Data Scientist uses a multi-phase workflow designed for complex analyses:

**Why separate planning from execution?**
- Thorough analysis of requirements before starting reduces errors and rework
- Clear success criteria established upfront ensure all requirements are met
- Plans can be validated and refined before committing resources to implementation

**Why use iterative refinement?**
- Multiple review loops catch issues early when they're easier to fix
- Both plans and implementations are validated before proceeding
- Continuous feedback improves quality at every step

**Why adapt during execution?**
- Discoveries during implementation often reveal new requirements
- Rigid plans can't accommodate unexpected insights or challenges
- Adaptive replanning ensures the final deliverable meets actual needs

**Why continuous validation?**
- Success criteria tracking provides objective progress measurement
- Early detection of issues prevents wasted effort
- Clear visibility into what's been accomplished and what remains

### The Multi-Agent Workflow

```
┌─────────────────────────────────────────────────────────────┐
│                     USER QUERY                              │
└─────────────────────┬───────────────────────────────────────┘
                      │
        ┌─────────────▼────────────────┐
        │   PLANNING PHASE             │
        │  ┌───────────────────────┐   │
        │  │ Plan Maker            │◄──┤ Iterative refinement
        │  │ "What needs to be     │   │ until plan is complete
        │  │  done?"               │   │ and validated
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ Plan Reviewer         │   │
        │  │ "Is this complete?"   │───┤
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ Plan Parser           │   │
        │  │ Structures into       │   │
        │  │ executable stages     │   │
        │  └──────────┬────────────┘   │
        └─────────────┼────────────────┘
                      │
        ┌─────────────▼────────────────┐
        │   EXECUTION PHASE            │
        │   (Repeated for each stage)  │
        │                              │
        │  ┌───────────────────────┐   │
        │  │ Coding Agent          │   │
        │  │ Implements the stage  │   │  Stage-by-stage
        │  │ (uses Claude Code)    │   │  implementation with
        │  └──────────┬────────────┘   │  continuous validation
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ Review Agent          │◄──┤ Iterates until
        │  │ "Was this done        │   │ implementation
        │  │  correctly?"          │───┤ is approved
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ Criteria Checker      │   │
        │  │ "What have we         │   │
        │  │  accomplished?"       │   │
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ Stage Reflector       │   │
        │  │ "What should we do    │   │
        │  │  next?" Adapts plan   │   │
        │  └──────────┬────────────┘   │
        └─────────────┼────────────────┘
                      │
        ┌─────────────▼────────────────┐
        │   SUMMARY PHASE              │
        │  ┌───────────────────────┐   │
        │  │ Summary Agent         │   │
        │  │ Creates comprehensive │   │
        │  │ final report          │   │
        │  └───────────────────────┘   │
        └──────────────────────────────┘
```

### Agent Roles

Each agent in the Data Scientist workflow has a specific responsibility:

- **Plan Maker**: "What needs to be done?" - Creates comprehensive analysis plans with clear stages and success criteria
- **Plan Reviewer**: "Is this plan complete?" - Validates that plans address all requirements before execution begins
- **Plan Parser**: Converts natural language plans into structured, executable stages with trackable success criteria
- **Stage Orchestrator**: Manages the execution cycle - runs stages one at a time, validates progress, and adapts as needed
- **Coding Agent**: Does the actual implementation work (powered by Claude Code SDK)
- **Review Agent**: "Was this done correctly?" - Validates implementations against requirements before proceeding
- **Criteria Checker**: "What have we accomplished?" - Objectively tracks progress against success criteria after each stage
- **Stage Reflector**: "What should we do next?" - Analyzes progress and adapts remaining stages based on what's been learned
- **Summary Agent**: Synthesizes all work into a comprehensive, publication-ready report

### @feynman: Scientific Writer

The Scientific Writer agent specializes in generating research documents:

**Capabilities:**
- LaTeX document generation with proper formatting
- Citation management and research lookup
- Cross-references and bibliography handling
- Multiple effort levels: "low" (Haiku), "medium" (Sonnet), "high" (Opus)

**Cross-Agent Handoff:**

When you run `@karpathy` analysis first, then `@feynman` in the same working directory, the Scientific Writer automatically:

1. Reads the `context/` folder for analysis summaries
2. Imports figures and results from `results/`
3. References actual findings in the generated paper
4. Uses real file paths for figures and data

```bash
# Step 1: Run analysis
inkvell "@karpathy Perform differential expression analysis" \
  --files rna_seq_data.csv --working-dir ./my_paper

# Step 2: Generate paper (inherits context from Step 1)
inkvell "@feynman Write a research paper about the DEG findings" \
  --working-dir ./my_paper
```

## Architecture

### System Overview

```
┌──────────────────────────────────────────────────────────────┐
│                  CLI / Web Interface                         │
├──────────────────────────────────────────────────────────────┤
│                     Agent Router                             │
│         @karpathy    │    @feynman    │    (default)         │
├──────────────────────┼────────────────┼──────────────────────┤
│   Data Scientist     │  Scientific    │    Claude Code       │
│   (ADK Workflow)     │    Writer      │    (Direct)          │
├──────────────────────────────────────────────────────────────┤
│                   InkVell Core                               │
│        (Session & Event Management)                          │
├──────────────────────────────────────────────────────────────┤
│                     Tool Layer                               │
│  • File Ops (sandboxed) • Web Fetch • Scientific Skills      │
└──────────────────────────────────────────────────────────────┘
```

### Data Scientist Workflow (@karpathy)

```
┌────────────────────────────────────────────────────────────┐
│ Planning Loop (Plan Maker → Reviewer → Parser)             │
└────────────────────────────────────────────────────────────┘
                            │
┌────────────────────────────────────────────────────────────┐
│ Stage Orchestrator                                         │
│   ├─> Implementation Loop (Coding → Review)                │
│   ├─> Criteria Checker                                     │
│   └─> Stage Reflector                                      │
└────────────────────────────────────────────────────────────┘
                            │
┌────────────────────────────────────────────────────────────┐
│ Summary Agent                                              │
└────────────────────────────────────────────────────────────┘
```

### Web Application Architecture

InkVell includes a web application for hosted deployments:

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Frontend     │     │  Orchestrator   │     │   Workspaces    │
│   (Next.js)     │────▶│   (FastAPI)     │────▶│   (Backend)     │
│                 │     │                 │     │                 │
│  • React UI     │     │  • Auth/JWT     │     │  • Agent Exec   │
│  • WebSocket    │     │  • Session Mgmt │     │  • File Storage │
│  • Streaming    │     │  • Fly.io API   │     │  • Claude Code  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

**Deployment:**
- Frontend, orchestrator, and workspaces deploy independently to Fly.io
- GitHub Actions auto-deploy on push to main
- Workspaces include pre-installed data science packages for fast startup

## Configuration

### Environment Variables

Create a `.env` file:

```bash
# Required: API keys
ANTHROPIC_API_KEY=your_key_here      # For coding agent and scientific writer
OPENROUTER_API_KEY=your_key_here     # For planning and review agents

# Optional: Model configuration
DEFAULT_MODEL=google/gemini-2.5-pro   # Planning/review agents
CODING_MODEL=claude-sonnet-4-5-20250929  # Coding agent
JUDGMENT_MODEL=anthropic/claude-opus-4.5  # High-stakes decisions

# Optional: Network access control
DISABLE_NETWORK_ACCESS=false          # Set to "true" to disable web tools
```

### Tools

**Built-in Tools** (planning/review agents):
- **File Operations**: Read-only file access within working directory
  - `read_file`, `read_media_file`, `list_directory`, `directory_tree`, `search_files`, `get_file_info`
- **Web Operations**: HTTP fetch for retrieving web content
  - `fetch_url`

All tools are sandboxed to the working directory for security.

## Documentation

- [Getting Started Guide](docs/getting_started.md) - Learn how the workflow operates step by step
- [API Reference](docs/api_reference.md) - Complete API documentation
- [Tools Configuration](docs/tools_configuration.md) - Configure tools and skills
- [Extending](docs/extending.md) - Customize prompts, agents, and workflows

## Examples

### @karpathy: Data Science Use Cases

**Complex Data Analysis**
```bash
# Differential expression analysis with multiple files
inkvell "@karpathy Perform DEG analysis comparing treatment vs control" \
  --files treatment_data.csv \
  --files control_data.csv
```

**Multi-Step Workflows**
```bash
# Complete analysis pipeline with visualization
inkvell "@karpathy Analyze customer churn, create predictive model, and generate report" \
  --files customers.csv \
  --working-dir ./churn_analysis
```

**Directory Processing**
```bash
# Process entire dataset directory
inkvell "@karpathy Analyze all CSV files and create summary statistics" \
  --files ./raw_data/
```

### @feynman: Scientific Writing Use Cases

**Research Paper Generation**
```bash
# Write a paper from scratch
inkvell "@feynman Write a methods paper about machine learning in genomics"
```

**Analysis-to-Paper Pipeline**
```bash
# Step 1: Run analysis with @karpathy
inkvell "@karpathy Analyze RNA-seq data for tumor vs normal differential expression" \
  --files counts.csv --files metadata.csv \
  --working-dir ./cancer_study

# Step 2: Write paper with @feynman (uses analysis results)
inkvell "@feynman Write a Nature Communications paper about the differential expression findings" \
  --working-dir ./cancer_study
```

**Documentation with Citations**
```bash
# Generate methods section with proper citations
inkvell "@feynman Create a detailed methods section for our CRISPR screening approach" \
  --files protocol_notes.md
```

### Simple Mode Use Cases

**Quick Scripts** (no @mention = simple mode)
```bash
# Generate utility scripts
inkvell "Write a Python script to merge CSV files by common column"
```

**Code Explanation**
```bash
# Technical questions
inkvell "Explain the difference between Random Forest and Gradient Boosting"
```

**Fast Prototypes**
```bash
# Quick analysis with temporary workspace
inkvell "Create a basic scatter plot from this data" \
  --files data.csv \
  --temp-dir
```

### Working Directory Examples

```bash
# Default behavior (./inkvell_output/ with file preservation)
inkvell "@karpathy Analyze data" --files data.csv

# Temporary directory (auto-cleanup)
inkvell "Quick test" --files data.csv --temp-dir

# Custom location for project
inkvell "@karpathy Full analysis pipeline" --files data.csv --working-dir ./my_project

# Cross-agent handoff in shared directory
inkvell "@karpathy Analyze the data" --files data.csv --working-dir ./paper_project
inkvell "@feynman Write paper from analysis" --working-dir ./paper_project
```

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/ishaan1124/inkvell-ai-scientist.git
cd inkvell

# Install with dev dependencies using uv
uv sync --extra dev

# Run tests
uv run pytest tests/

# Format code
uv run ruff format .

# Lint
uv run ruff check --fix .
```

### Project Structure

```
inkvell/
├── src/agentic_data_scientist/
│   ├── core/                    # Core API, events, and routing
│   │   ├── api.py               # DataScientist class
│   │   ├── events.py            # Event system
│   │   └── router.py            # @mention agent routing
│   ├── agents/                  # Agent implementations
│   │   ├── adk/                 # ADK multi-agent workflow (@karpathy)
│   │   │   ├── agent.py         # Agent factory
│   │   │   ├── stage_orchestrator.py
│   │   │   ├── implementation_loop.py
│   │   │   ├── loop_detection.py
│   │   │   └── event_compression.py
│   │   ├── claude_code/         # Claude Code integration
│   │   └── scientific_writer/   # Scientific Writer agent (@feynman)
│   ├── prompts/                 # Jinja2 prompt templates
│   │   ├── base/                # Agent role prompts
│   │   └── domain/              # Domain-specific prompts
│   ├── tools/                   # Built-in tools (file ops, web fetch)
│   └── cli/                     # CLI interface
├── web/                         # Web application
│   ├── frontend/                # Next.js React UI
│   ├── backend/                 # FastAPI workspace backend
│   └── orchestrator/            # Session & auth orchestrator
├── tests/                       # Test suite
└── docs/                        # Documentation
```

## Requirements

- Python 3.12+
- Node.js (for Claude Code)
- API keys for Anthropic and OpenRouter

## Contributing

Contributions welcome!

```bash
# Fork and clone, then:
uv sync --extra dev
# Make changes, add tests
uv run pytest tests/ -v
# Submit PR
```

## Technical Notes

### Context Window Management

The framework implements aggressive event compression to manage context window usage during long-running analyses:

#### Event Compression Strategy

- **Automatic Compression**: Events are automatically compressed when count exceeds threshold (default: 40 events)
- **LLM-based Summarization**: Old events are summarized using LLM before removal to preserve critical context
- **Aggressive Truncation**: Large text content (>10KB) is truncated to prevent token overflow
- **Direct Event Queue Manipulation**: Uses direct assignment to `session.events` to ensure changes take effect

#### Preventing Token Overflow

The system employs multiple layers of protection:

- **Callback-based compression**: Triggers automatically after each agent turn
- **Manual compression**: Triggered at key orchestration points (e.g., after implementation loop)
- **Hard limit trimming**: Emergency fallback that discards old events if count exceeds maximum
- **Large text truncation**: Prevents individual events from consuming excessive tokens

These mechanisms work together to keep the total context under 1M tokens even during complex multi-stage analyses.

## Support

- GitHub Issues: [Report bugs or request features](https://github.com/ishaan1124/inkvell-ai-scientist/issues)
- Documentation: [Full documentation](https://github.com/ishaan1124/inkvell-ai-scientist/blob/main/docs)

## Acknowledgments

Built with:
- [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/)
- [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## License

MIT License - see [LICENSE](LICENSE) for details.

Copyright 2025 InkVell