COSMIC Command Line Interface

Complete reference for the cosmic CLI tool.

Commands Overview

Command	Description
cosmic chunk	Chunk a document using COSMIC pipeline
cosmic ollama	Manage Ollama integration
cosmic version	Display version information
cosmic benchmark	Run benchmark suite

---

cosmic chunk

Chunk a document using the COSMIC pipeline.

Synopsis

cosmic chunk FILE [OPTIONS]

Arguments

Argument	Description
FILE	Path to the input file to chunk

Options

Option	Short	Default	Description
--strategy	-s	auto	Chunking strategy
--output	-o	stdout	Output JSON file
--config	-c	-	Configuration YAML file
--no-llm	-	-	Disable LLM verification
--no-reference	-	-	Disable reference linking
--ollama	-	-	Use Ollama for LLM verification
--verbose	-v	-	Enable verbose logging

Strategy Values

Strategy	Description
auto	Automatically select based on document structure
full	Full 6-stage COSMIC pipeline
semantic	Semantic boundaries only (DCS-based)
sliding	Sliding window with basic similarity
fixed	Fixed-length token splitting

Examples

Basic Usage

# Chunk with automatic strategy selection
cosmic chunk document.txt

# Chunk a markdown file
cosmic chunk README.md

# Chunk with verbose output
cosmic chunk document.txt -v

Strategy Selection

# Full 6-stage pipeline (highest quality)
cosmic chunk document.txt --strategy full

# Semantic-only (faster, good quality)
cosmic chunk document.txt --strategy semantic

# Sliding window (fast, basic quality)
cosmic chunk document.txt --strategy sliding

# Fixed-length (fastest, baseline quality)
cosmic chunk document.txt --strategy fixed

# Short form
cosmic chunk document.txt -s full

Output Options

# Save to JSON file
cosmic chunk document.txt --output chunks.json
cosmic chunk document.txt -o chunks.json

# Save with specific strategy
cosmic chunk document.txt -s full -o output/chunks.json

# Pretty-print to terminal (default)
cosmic chunk document.txt

Configuration

# Use custom configuration file
cosmic chunk document.txt --config configs/custom.yaml
cosmic chunk document.txt -c configs/custom.yaml

# Combine config with strategy override
cosmic chunk document.txt -c configs/custom.yaml -s semantic

Disabling Pipeline Stages

# Disable LLM verification (Stage 5)
cosmic chunk document.txt --strategy full --no-llm

# Disable reference linking (Stage 6)
cosmic chunk document.txt --strategy full --no-reference

# Disable both
cosmic chunk document.txt --strategy full --no-llm --no-reference

Ollama Integration

# Auto-detect and use best available model
cosmic chunk document.txt --strategy full --ollama

# Equivalent to above (explicit auto)
cosmic chunk document.txt --strategy full --ollama auto

# Use specific model
cosmic chunk document.txt --strategy full --ollama gemma3:latest
cosmic chunk document.txt --strategy full --ollama qwen2.5-coder:7b

# Combine with output
cosmic chunk document.txt -s full --ollama gemma3 -o chunks.json

Output Format

When no --output is specified, results are printed to stdout:

Document: README
Strategy: auto
Chunks: 75

--- Chunk 0 ---
  Tokens: 45
  Coherence: 1.000
  Domain: technical
  Mode: FULL_COSMIC
  Preview: # COSMIC: COncept-aware Semantic Meta-chunking with Intelligent Classification...

--- Chunk 1 ---
  Tokens: 20
  Coherence: 1.000
  Domain: technical
  Mode: FULL_COSMIC
  Preview: ## Research Objectives COSMIC addresses fundamental limitations...

When --output is specified, a JSON file is created:

{
  "document_id": "README",
  "source_file": "README.md",
  "strategy": "auto",
  "num_chunks": 75,
  "chunks": [
    {
      "chunk_id": "abc123def456",
      "document_id": "README",
      "chunk_index": 0,
      "text": "...",
      "token_count": 45,
      "location": { ... },
      "domain": { ... },
      "quality": { ... },
      "references": { ... },
      "intent": { ... },
      "structure": { ... },
      "provenance": { ... }
    }
  ]
}

---

cosmic ollama

Manage Ollama integration for LLM verification.

Synopsis

cosmic ollama [ACTION]

Actions

Action	Description
status	Show Ollama installation and server status (default)
list	List available Ollama models
start	Start the Ollama server
stop	Show how to stop the Ollama server

Examples

Check Status

# Show Ollama status (default action)
cosmic ollama
cosmic ollama status

Output:

Ollama Status:
  Installed: Yes
  Running: Yes
  Models available: 6
  Recommended model: gemma3:latest

List Models

cosmic ollama list

Output:

Available Ollama models:
NAME                                     SIZE
--------------------------------------------------
qwen3:30b-a3b                            18.0 GB
qwen2.5-coder:7b                         4.7 GB
deepseek-coder-v2:latest                 8.9 GB
llama4:latest                            67.0 GB
gemma3:latest                            3.3 GB

Recommended for COSMIC: gemma3:latest

Start Server

cosmic ollama start

Output:

Ollama server started

Stop Server

cosmic ollama stop

Output:

Note: Use 'ollama stop' or 'pkill ollama' to stop the server

---

cosmic version

Display COSMIC version information.

Synopsis

cosmic version

Example

cosmic version

Output:

COSMIC v1.0.0
COncept-aware Semantic Meta-chunking with Intelligent Classification

---

cosmic benchmark

Run the COSMIC benchmark suite.

Synopsis

cosmic benchmark [OPTIONS]

Options

Option	Short	Description
--documents	-d	Directory containing documents to benchmark

Examples

# Quick sanity check
cosmic benchmark

# Benchmark with custom documents
cosmic benchmark --documents ./test_documents/
cosmic benchmark -d ./test_documents/

Output:

Running COSMIC benchmark...
(Use benchmarks/run_validation.py for full benchmark)
Quick test: 1 chunks created

For comprehensive benchmarking, use the Python runner directly:

# Full benchmark suite
python -m benchmarks.runner

# Specific datasets
python -m benchmarks.runner --datasets arxiv pubmed

# Limited samples
python -m benchmarks.runner --limit 100

---

Global Options

These options apply to all commands:

Option	Short	Description
--verbose	-v	Enable verbose/debug logging
--help	-h	Show help message

Examples

# Show main help
cosmic --help
cosmic -h

# Show command-specific help
cosmic chunk --help
cosmic ollama --help

# Enable verbose logging
cosmic -v chunk document.txt
cosmic chunk document.txt -v

---

Environment Variables

The CLI respects these environment variables:

Variable	Default	Description
COSMIC_LLM_PROVIDER	openai	LLM provider: openai, ollama, auto
COSMIC_LLM_URL	http://localhost:8000/v1	LLM API endpoint
COSMIC_LLM_MODEL	default	LLM model name
COSMIC_LLM_API_KEY	-	API key for LLM
OLLAMA_HOST	http://localhost:11434	Ollama server URL
COSMIC_OLLAMA_MODEL	auto	Ollama model to use
COSMIC_EMBEDDING_DEVICE	cuda	Device for embeddings

Examples

# Use CPU for embeddings
COSMIC_EMBEDDING_DEVICE=cpu cosmic chunk document.txt

# Use specific Ollama model by default
COSMIC_OLLAMA_MODEL=gemma3:latest cosmic chunk document.txt --ollama

# Configure LLM endpoint
COSMIC_LLM_URL=http://my-llm-server:8000/v1 cosmic chunk document.txt

---

Exit Codes

Code	Description
0	Success
1	Error (file not found, invalid options, etc.)

---

Common Workflows

Quick Document Chunking

# Simple chunking with sensible defaults
cosmic chunk my_document.txt

High-Quality Chunking with Local LLM

# Use full pipeline with Ollama verification
cosmic chunk document.txt --strategy full --ollama auto

Fast Processing

# Skip expensive stages for speed
cosmic chunk document.txt --strategy semantic --no-reference

Batch Processing via Shell

# Process multiple files
for f in documents/*.txt; do
  cosmic chunk "$f" -o "output/$(basename "$f" .txt).json"
done

# Parallel processing with xargs
ls documents/*.txt | xargs -P4 -I{} cosmic chunk {} -o output/{}.json

CI/CD Integration

# Consistent, reproducible chunking
cosmic chunk document.txt \
  --config configs/production.yaml \
  --strategy full \
  --no-llm \
  --output chunks.json

Development/Testing

# Quick iteration with verbose output
cosmic -v chunk test.txt --strategy semantic

# Benchmark after changes
cosmic benchmark

---

Troubleshooting

File Not Found

Error: File not found: document.txt

Solution: Verify the file path exists and is readable.

Ollama Not Installed

Error: Ollama is not installed
Install from: https://ollama.com/download

Solution: Install Ollama from the official website.

No Ollama Models

Error: No Ollama models available
Pull a model with: ollama pull gemma3

Solution: Pull a model using ollama pull <model>.

LLM Connection Failed

[COSMIC_E003] Failed to connect to LLM endpoint

Solutions:

1. Use --no-llm to disable LLM verification
2. Use --ollama for local LLM
3. Configure a valid endpoint in .env

Memory Issues

Solutions:

1. Use COSMIC_EMBEDDING_DEVICE=cpu
2. Use --strategy semantic or --strategy fixed
3. Process smaller documents

---

See Also

• QUICKSTART.md - Full API documentation
• README.md - Project overview and architecture
• configs/default.yaml - Default configuration