scillm Tools

LLM completions via scillm/Chutes.ai (per SCILLM_PAVED_PATH_CONTRACT.md).

Two Main Patterns

Tools

vlm.py - VLM (Multimodal) Completions

Quick Start

# Describe an image
python .pi/skills/scillm/vlm.py describe /path/to/image.png

# With custom prompt
python .pi/skills/scillm/vlm.py describe /path/to/image.png --prompt "What table headers do you see?"

# JSON output
python .pi/skills/scillm/vlm.py describe /path/to/image.png --json

# Batch describe images
python .pi/skills/scillm/vlm.py batch --input images.jsonl

Commands

Describe single image:

python .pi/skills/scillm/vlm.py describe <image> [--prompt PROMPT] [--json] [--model MODEL]

Batch describe:

python .pi/skills/scillm/vlm.py batch \
  --input images.jsonl \
  --output results.jsonl \
  --concurrency 6

Input Format (Batch)

JSONL with image paths:

{"path": "/path/to/image1.png", "prompt": "Describe this table"}
{"path": "/path/to/image2.png"}

Environment Variables

batch.py - LLM Completions

Quick Start

# Single completion
python .pi/skills/scillm/batch.py single "What is 2+2?"

# Single with JSON response
python .pi/skills/scillm/batch.py single "Return {answer: number}" --json

# Batch from file
python .pi/skills/scillm/batch.py batch --input prompts.jsonl --json

Commands

Single completion:

python .pi/skills/scillm/batch.py single "Your prompt" [--json] [--model MODEL]

Batch completions:

python .pi/skills/scillm/batch.py batch \
  --input prompts.jsonl \
  --output results.jsonl \
  --json \
  --concurrency 6

Input/Output Format

Input JSONL (one per line):

{"prompt": "Summarize..."}
{"prompt": "Translate..."}

Output JSONL:

{"index": 0, "content": "...", "ok": true}
{"index": 1, "error": "timeout", "status": 408}

Environment Variables

prove.py - Lean4 Theorem Proving

Quick Start

# Prove a claim
python .pi/skills/scillm/prove.py "Prove that n + 0 = n"

# With tactic hints
python .pi/skills/scillm/prove.py "Prove n < n + 1" --tactics omega

# Check availability
python .pi/skills/scillm/prove.py --check

Commands

Prove a claim:

python .pi/skills/scillm/prove.py "Your claim" [--tactics simp,omega] [--timeout 120]

Check if ready:

python .pi/skills/scillm/prove.py --check

Output Format

Success:

{
  "ok": true,
  "lean4_code": "theorem add_zero (n : ℕ) : n + 0 = n := by simp",
  "compile_ms": 7406
}

Failure:

{
  "ok": false,
  "diagnosis": "mathematically false",
  "suggestion": "Change to 'Prove that 2 + 2 = 4'"
}

Tactic Hints

Prerequisites

1. lean_runner container running
2. OPENROUTER_API_KEY set
3. scillm[certainly] installed

Importable API (For Other Skills)

The quick_completion function can be imported by sibling skills:

# Add scillm to path (for sibling skills)
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent / "scillm"))

from batch import quick_completion

# Simple completion
result = quick_completion("What is 2+2?")

# With JSON mode
result = quick_completion("Extract {name, age}", json_mode=True)

# With system prompt
result = quick_completion(
    prompt="Translate to French: Hello",
    system="You are a translator",
    temperature=0.3,
)

Parameters:

Approved Import Surfaces (Proxy-First)

All LLM calls route through the scillm proxy on :4001 for global concurrency/budget control.

# Simple one-off calls (default to proxy automatically)
from scillm.paved import chat, chat_json, analyze_image, analyze_image_json

answer = await chat("What is 2+2?")
data = await chat_json('Return {"name": "Alice", "age": 25}')
desc = await analyze_image("/path/to/image.png", "Describe this")

# Batch fan-out (MUST use proxy api_base)
from scillm.batch import parallel_acompletions_iter

async for ev in parallel_acompletions_iter(
    reqs,
    api_base=os.environ.get("SCILLM_API_BASE", "http://localhost:4001"),
    api_key=os.environ.get("SCILLM_PROXY_KEY", "sk-dev-proxy-123"),
    concurrency=6,
):
    ...

# Lean4 proofs (separate from Chutes, no proxy needed)
from scillm.integrations.certainly import prove_requirement
result = await prove_requirement("Prove n + 0 = n", tactics=["simp"])

Forbidden in downstream projects: Direct acompletion(api_base=CHUTES_API_BASE) calls that bypass the proxy. See SCILLM_PAVED_PATH_CONTRACT.md for full rules.