AI Providers

AetherShell has built-in AI capabilities with a provider-agnostic architecture. Connect to cloud APIs, local models, or self-hosted inference servers — all using the same simple syntax.

Quick Start

# Set your API key
set_env "OPENAI_API_KEY" "sk-..."

# Ask a question
ai "What is Rust's ownership model?"

# Specify a model
ai "Explain monads" { model: "openai:gpt-4o" }

Model URI Scheme

AetherShell uses a URI scheme to reference models across providers:

URI	Provider	Example
`openai:model-name`	OpenAI	`openai:gpt-4o-mini`
`ollama:model-name`	Ollama (local)	`ollama:llama3`
`compat:model-name`	OpenAI-compatible API	`compat:mixtral`
`tgi:model-name`	HuggingFace TGI	`tgi:mistral-7b`
`vllm:model-name`	vLLM	`vllm:meta-llama/Llama-3-8B`
`llamacpp:model-name`	llama.cpp	`llamacpp:mistral-7b`

# Use different providers
ai "Hello" { model: "openai:gpt-4o" }
ai "Hello" { model: "ollama:llama3" }
ai "Hello" { model: "compat:mixtral" }

Providers

OpenAI

The default cloud provider. Requires an API key.

set_env "OPENAI_API_KEY" "sk-..."
set_env "AETHER_AI" "openai"

ai "Explain closures in Rust"

Environment variables:

OPENAI_API_KEY — API authentication key
OPENAI_MODEL — Default model (default: gpt-4o-mini)

Ollama (Local)

Run models locally with Ollama. No API key needed.

set_env "AETHER_AI" "ollama"

ai "Summarize this code" { model: "ollama:codellama" }

Environment variables:

OLLAMA_URL — Ollama endpoint (default: http://localhost:11434)
OLLAMA_MODEL — Default model (default: llama3)

OpenAI-Compatible

Any server implementing the OpenAI API format (LiteLLM, LocalAI, etc.).

set_env "AETHER_AI" "compat"
set_env "AETHER_COMPAT_BASE" "http://localhost:8000/v1"

ai "Hello" { model: "compat:mixtral" }

Environment variables:

AETHER_COMPAT_BASE — API base URL (default: http://localhost:8000/v1)
AETHER_COMPAT_MODEL — Default model (default: mixtral)

HuggingFace TGI

Connect to a Text Generation Inference server.

set_env "AETHER_AI" "tgi"
set_env "TGI_URL" "http://localhost:8080"

vLLM

Connect to a vLLM inference server.

set_env "VLLM_URL" "http://localhost:8000/v1"
set_env "VLLM_MODEL" "meta-llama/Llama-3-8B"

llama.cpp

Connect to a llama.cpp server.

set_env "LLAMACPP_URL" "http://localhost:8080/v1"

Provider Selection

The AETHER_AI environment variable selects the default provider:

set_env "AETHER_AI" "openai"    # Use OpenAI
set_env "AETHER_AI" "ollama"    # Use Ollama
set_env "AETHER_AI" "compat"    # Use OpenAI-compatible server
set_env "AETHER_AI" "tgi"       # Use TGI

Override per-call with the model option:

# Default is OpenAI, but use Ollama for this one call
ai "Quick question" { model: "ollama:llama3" }

Multimodal AI

AetherShell supports sending images, audio, and video to models that accept them.

Images

ai "Describe this image" { images: ["photo.jpg"] }
ai "Compare these" { images: ["before.png", "after.png"] }

Audio

ai "Transcribe this recording" { audio: ["meeting.mp3"] }

Video

ai "What happens in this clip?" { video: ["demo.mp4"] }

Combined

ai "Analyze this screenshot and narration" {
  images: ["screen.png"],
  audio: ["narration.mp3"]
}

Note: Multimodal support depends on the provider. OpenAI supports images; Ollama supports images with vision models. Audio and video support varies by model.

Backend Detection

Discover which AI backends are available on your system:

ai_backends
# [
#   { provider: "openai", available: true, model: "gpt-4o-mini" },
#   { provider: "ollama", available: true, url: "http://localhost:11434", models: ["llama3", "codellama"] },
#   { provider: "vllm", available: false },
#   ...
# ]

Shell Helpers

Four helpers answer from the shell’s own catalogue. No model is consulted (use ai(...) for that), so they work offline and give the same answer every time.

# Declared builtins whose name or description matches every word
suggest("sha256 digest")
# [{name: "sha256", signature: "sha256(...) -> String", doc: "SHA-256 hex digest of a string."}]

# A builtin's declared signature, or what an error code means
explain("crypto_hash")

# Builtin names starting with a prefix
complete("git_st")
# ["git_stash", "git_stash_list", "git_stash_pop", "git_status"]

# The minimal repair context for an error, from its text or a caught record
try { crypto_hash("x", "blake3") } catch e { fix(e) }

Pipeline Integration

AI calls compose naturally with pipelines:

# Summarize a file
cat "README.md" | ai "Summarize this document"

# Classify data
["bug report", "feature request", "question"]
  | map(fn(item) => {
      let category = ai "Classify: ${item}" { model: "openai:gpt-4o-mini" }
      { text: item, category: category }
  })

# Generate documentation
ls "src" 
  | where(fn(f) => f.extension == "rs")
  | map(fn(f) => { file: f.name, doc: ai "Write a one-line description of: ${cat f.path}" })

Global Override

Set a global model URI that overrides all defaults:

set_env "AETHER_MODEL_URI" "ollama:codellama"
# All ai/agent calls now use this model unless explicitly overridden

Keyboard shortcuts

AetherShell Documentation