llamero: Instructions file for Codex

llamero — agent quick reference

llamero is a Crystal library for AI applications: cloud provider clients (OpenAI, Anthropic, Groq, OpenRouter) with failover, plus native local inference and LoRA/QLoRA adapter training on Apple Silicon via MLX. One require: require "llamero".

This file is the condensed API contract. Fuller task recipes live in the shipped skills: cloud-providers, local-inference, adapter-training (installed as .claude/skills/llamero--<name>/ in consuming projects).

Cloud chat with failover

require "llamero"

class MyAIClient < Llamero::Client # abstract base - MUST subclass
  def initialize
    super(primary: :openai, fallbacks: [:anthropic, :groq])
  end
end

client = MyAIClient.new
response = client.chat([Llamero::Message.user("Hello!")])
puts response.content

Keys via env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY. Streaming: client.chat_stream(messages) { |chunk| print chunk }. Direct clients without failover: Llamero::OpenAIClient.new, Llamero::AnthropicClient.new, Llamero::GroqClient.new, Llamero::OpenRouterClient.new.

Structured JSON output (cloud and local, same pattern)

class PersonInfo < Llamero::BaseGrammar
  property name : String = ""   # every property needs a default
  property age : Int32 = 0
end

response = client.chat_structured([Llamero::Message.user("Random person")], PersonInfo)
person = response.parsed.not_nil!

Storage root for consuming apps

Default storage is ~/.llamero. Apps that need app-owned AI data set this at boot before creating runtimes:

Llamero.storage_root = Path.home.join(".scribe")

LLAMERO_HOME=/path/to/root is the env alternative; programmatic wins. The root controls models/, adapters/, bridge lib/ lookup, and configured audio model caches under audio_models/. FluidAudio 0.15.2 still pins English Kokoro G2P assets to its own TTS cache; see development_docs/storage_configuration.md.