Setting Up CASSIA

First, install the CASSIA package using pip:

pip install CASSIA
bash

Import CASSIA

import CASSIA
Python

Command-Line Interface

The Python package also installs a cassia command for agent-native workflows. It can run through the standard CASSIA API providers or through local agent CLIs such as Claude Code, Codex CLI, Cursor Agent, or a custom shell command.

cassia doctor
cassia backends list
cassia examples --out cassia_example
cassia validate markers.csv

cassia annotate \
  --input markers.csv \
  --backend codex-cli \
  --tissue brain \
  --species human \
  --out runs/brain_codex

cassia boost query \
  --markers raw_findallmarkers.csv \
  --cluster 3 \
  --genes CD3D,CD3E,TRAC

cassia boost run \
  --run runs/brain_codex \
  --markers raw_findallmarkers.csv \
  --cluster 3 \
  --backend codex-cli

cassia boost auto \
  --run runs/brain_codex \
  --markers raw_findallmarkers.csv \
  --backend codex-cli \
  --max-clusters 5

cassia subcluster run \
  --markers cd8_subcluster_markers.csv \
  --major-cluster-info "CD8 T cell in human tumor" \
  --backend codex-cli \
  --out runs/cd8_subcluster

cassia consensus \
  --inputs runs/brain_codex/summary.csv runs/brain_claude/summary.csv \
  --out runs/brain_consensus.csv
bash

Agent CLI backends do not require CASSIA API keys; they reuse the local tool's own authentication. API-backed CLI runs still use the same keys described below. cassia examples creates a runnable mini project with marker tables, consensus inputs, shell scripts, and an offline toy agent. cassia validate checks marker CSV structure, inferred columns, ranking columns, and prepared marker counts before annotation. cassia boost auto prioritizes low-confidence, mixed, or ambiguous clusters and writes aggregate CSV/HTML reports under RUN/boost/_auto. cassia subcluster run annotates subclusters inside one parent cluster from a subcluster marker table and writes CSV/HTML reports in the requested output directory. cassia consensus votes across multiple CASSIA summary/subcluster CSVs and writes CSV/HTML consensus reports without calling an LLM.

Setting API Keys

To use LLMs like OpenAI's GPT-4, Anthropic's Claude, or models via OpenRouter, you will first need to get your API keys from the provider and then set your API keys using the set_api_key function.

Note: API-backed CASSIA workflows require at least one API key.

You only need to choose one provider. OpenRouter is recommended as it provides access to multiple models. You can also use custom API providers like DeepSeek or local LLMs.

# Set API key (choose one provider)
CASSIA.set_api_key("your-openrouter-key", provider="openrouter")  # Recommended
# CASSIA.set_api_key("your-openai-key", provider="openai")
# CASSIA.set_api_key("your-anthropic-key", provider="anthropic")
Python

• Replace "your-key" with your actual API key.
• Set provider to "openai", "anthropic", or "openrouter" depending on your provider.

Validating API Keys

You can verify that your API keys are working correctly before running analyses:

# Validate all configured providers
CASSIA.validate_api_keys(force_revalidate=True)

# Validate a specific provider
CASSIA.validate_api_keys("openai", force_revalidate=True)
Python

How to Select Models and Providers

There are three providers to choose from: openrouter, openai, and anthropic. Each provider has its own models and pricing. Note that the model name must be set exactly as shown below or the model will not be found.

OpenRouter

OpenRouter is a platform that offers access to almost all the models supported by major providers. It is recommended to use OpenRouter due to its higher rate limits and access to a variety of models including open source options.

• anthropic/claude-sonnet-4.6: Current default high-performance model.
• openai/gpt-5.4: Balanced option.
• google/gemini-3-flash-preview: One of the best-performed low-cost models.

OpenAI

• gpt-5.4: High-performance model.

Anthropic

• claude-sonnet-4.6: High-performance model.

Other Providers

These models can be used via their own APIs. See Custom API Providers for setup.

• deepseek-chat (DeepSeek v3.2): High performance, very affordable. Provider: https://api.deepseek.com
• glm-5 (GLM 4.6): Fast and cost-effective. Provider: https://api.z.ai/api/paas/v4/
• kimi-k2.5 (Kimi K2): Strong reasoning capabilities. Provider: https://api.moonshot.cn/v1

Local LLMs

• gpt-oss:20b: Can run locally via Ollama. Good for large bulk analysis with acceptable accuracy. See Local LLMs for setup.

Smart Model Settings (Recommended)

CASSIA includes a smart model selection system that allows you to use simple aliases or "tiers" instead of remembering exact model version strings. This makes your code more robust to model version updates.

Tier Shortcuts

You can use these shortcuts with any provider to get the appropriate model for your needs:

• "best": Selects the highest performing model (e.g., gpt-5.4, claude-opus-4.6)
• "balanced": Selects a good balance of performance and cost (e.g., gpt-4o, claude-sonnet-4.6)
• "fast": Selects the fastest/cheapest model (e.g., gpt-5.4-mini, claude-haiku-4.5)

Example:

# This will automatically select the best model for OpenAI
CASSIA.runCASSIA_pipeline(..., model = "best", provider = "openai")
Python

Fuzzy Matching & Aliases

You can also use common names, and CASSIA will resolve them to the correct version:

• "gpt" -> resolves to gpt-5.4 (for OpenAI)
• "claude" -> resolves to claude-sonnet-4.6 (for Anthropic)
• "gemini" -> resolves to google/gemini-3-flash-preview (for OpenRouter)

Custom API Providers

CASSIA supports any OpenAI-compatible API endpoint, allowing you to use custom providers like DeepSeek, local LLM servers, or other third-party services.

Setting Up Custom Providers

To use a custom API provider, specify the full base URL as the provider parameter:

# Set API key for custom provider
CASSIA.set_api_key("your-api-key", provider="https://api.your-provider.com")

# Use in analysis
CASSIA.runCASSIA_batch(
    marker=markers,
    output_name="results",
    provider="https://api.your-provider.com",
    model="your-model-name",
    tissue="brain",
    species="human"
)
Python

DeepSeek Example

DeepSeek offers high-performance models at competitive prices:

1. Get your API key from DeepSeek Platform
2. Set up in CASSIA:

CASSIA.set_api_key("your-deepseek-key", provider="https://api.deepseek.com")

CASSIA.runCASSIA_pipeline(
    output_file_name="analysis",
    marker=markers,
    annotation_provider="https://api.deepseek.com",
    annotation_model="deepseek-chat",
    tissue="brain",
    species="human"
)
Python

Local LLMs (Ollama, LM Studio)

For complete data privacy and zero API costs, you can run LLMs locally. CASSIA supports any OpenAI-compatible local server.

No API key required for localhost URLs.

Ollama Setup

1. Install Ollama from ollama.ai
2. Pull a model: ollama pull gpt-oss:20b
3. Ollama runs automatically on http://localhost:11434

Usage

CASSIA.runCASSIA_batch(
    marker=markers,
    output_name="results",
    provider="http://localhost:11434/v1",
    model="gpt-oss:20b",
    tissue="brain",
    species="human"
)
Python

Reasoning Effort Parameter

Note: This parameter is only meaningful for OpenAI GPT-5 series models (e.g., gpt-5.4). Use via OpenRouter (recommended) or as a verified OpenAI user.

The reasoning parameter controls the model's reasoning depth for compatible models.

Syntax

# Simple string format
reasoning="high"    # Maximum reasoning depth
reasoning="medium"  # Balanced (recommended for GPT-5.1)
reasoning="low"     # Minimal reasoning

# Dictionary format (Python only)
reasoning={"effort": "high"}

# Standard mode (no extended reasoning)
reasoning=None  # or omit the parameter
Python

Provider Notes

• OpenAI via OpenRouter: Full control with reasoning parameter. Recommended to avoid identity verification required by direct OpenAI API.
• OpenAI direct: Requires identity verification for reasoning models.
• Anthropic Claude: Default uses highest reasoning effort automatically.
• Gemini: Dynamic thinking - model decides when and how much to think.

Recommendations

• GPT-5.1: Use reasoning="medium" - highest effort may take a very long time
• GPT-4o: Still excellent performance without reasoning parameter
• Claude: No need to set - uses optimal reasoning automatically
• General: Higher effort = longer processing time + higher cost

Example:

# Using reasoning with GPT-5.1 via OpenRouter
CASSIA.runCASSIA_batch(
    marker=markers,
    output_name="results",
    model="openai/gpt-5.4",
    provider="openrouter",
    reasoning="medium",  # Recommended for balanced speed/quality
    tissue="brain",
    species="human"
)
Python