---
name: ask_llm
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "def ask_llm(prompt: str, model: str = 'claude-haiku-4-5-20251001', system: str = '', max_tokens: int = 4096, echo: bool = True) -> str"
description: "Atajo de una linea para preguntar al modelo via la API directa de Anthropic con el token OAuth de Claude Max. Arranque 0 (sin proceso claude, sin daemon). Stream a stdout y devuelve el texto. Lanzable como CLI o importable."
error_type: error_go_core
tags: ["claude-direct", "llm", "anthropic", "cli", "oauth", "chat"]
uses_functions:
  - stream_anthropic_messages_py_core
uses_types: []
params:
  - name: prompt
    desc: "El mensaje del usuario (string). Si vacio y stdin es un pipe, se lee de stdin."
  - name: model
    desc: "Id del modelo Anthropic. Default claude-haiku-4-5-20251001 (mas cuota, rapido). Otros: claude-opus-4-8, claude-sonnet-4-6."
  - name: system
    desc: "System prompt opcional (string vacio = ninguno)."
  - name: max_tokens
    desc: "Maximo de tokens de salida. Default 4096."
  - name: echo
    desc: "Si True, escribe la respuesta a stdout segun llega (streaming). Si False, solo la devuelve."
output: "El texto completo de la respuesta del modelo (string). Cadena vacia si hubo error (mensaje a stderr)."
file_path: python/functions/core/ask_llm.py
---

# ask_llm

Atajo CLI para ejecutar el modelo **rapido** desde la terminal o un script, usando la API directa
de Anthropic con el token OAuth de Claude Max. No lanza el proceso `claude` ni mantiene ningun
daemon — el arranque es 0. Es el wrapper conveniente del grupo `claude-direct`.

## Ejemplo

```bash
# Desde la terminal (fn run)
fn run ask_llm "que es un pseudo-terminal en una frase"

# Directo con el venv
python/.venv/bin/python3 python/functions/core/ask_llm.py "explica los punteros en Go" --model claude-opus-4-8

# Por pipe (lee el prompt de stdin)
echo "resume esto en 2 lineas: ..." | python/.venv/bin/python3 python/functions/core/ask_llm.py

# Importable en un script
import sys, os
sys.path.insert(0, "python/functions")
from core.ask_llm import ask_llm
texto = ask_llm("dame 3 ideas", model="claude-haiku-4-5-20251001", echo=False)
```

## Cuando usarla

- Cuando quieras preguntar al modelo **rapido** desde la terminal o un script, sin lanzar claude
  ni montar un servidor. Respuesta en streaming, arranque 0.
- Para chat one-shot. Si necesitas **tools / loop agentico**, usa `run_claude_tool_loop_py_core`.
  Si necesitas los **eventos crudos** (tool_use, deltas), usa `stream_anthropic_messages_py_core`.

## Gotchas

- **Rate limits**: el plan limita la frecuencia. En rafagas se reciben `HTTP 429`; espacia las
  llamadas o usa `claude-haiku-4-5-20251001` (mas cuota) para tareas frecuentes.
- **Nombre del modelo**: `claude-opus-4-8` es valido; los ids con sufijo de fecha que no existen
  dan `404 not_found_error`. Default haiku por cuota y velocidad.
- **No es Claude Code**: es el modelo crudo. Sin tools, MCP, contexto del repo ni plan mode, salvo
  los que tu pases (via `run_claude_tool_loop`).
