3.0 KiB
Invocación de LLM: SIEMPRE ask_llm, NUNCA claude -p
REGLA DURA. Para ejecutar un modelo LLM desde cualquier código del ecosistema (scripts, heredocs, apps, pipelines, agentes), usa el grupo claude-direct — empezando por ask_llm_py_core. NUNCA uses claude -p ni lances el binario claude como subproceso para obtener una respuesta del modelo.
Por qué
claude -p |
ask_llm / claude-direct |
|
|---|---|---|
| Mecanismo | Lanza Claude Code entero (proceso claude) |
Habla directo a api.anthropic.com/v1/messages |
| Arranque | ~7-15s (carga MCP + CLAUDE.md ~100k tokens) |
0 — request HTTP directa |
| Latencia/msg | ~9-15s | ~2.5s |
| Coste | Alto (re-carga contexto cada vez) | Mínimo (solo tu prompt) |
| Tools | Las de Claude Code (no controlables) | Las que tú defines (run_claude_tool_loop) |
| Streaming | indirecto | nativo (stream_anthropic_messages) |
claude -p es lento, caro y arranca todo Claude Code para una completion. ask_llm es la API directa: arranque 0, rápido, con tus propias tools. Usa el token OAuth que Claude Code ya guarda en ~/.claude/.credentials.json.
Cómo (según el caso)
| Caso | Usa |
|---|---|
| Pregunta/chat one-shot | fn run ask_llm "..." o from core.ask_llm import ask_llm |
| Streaming de eventos crudos (text/tool_use deltas) | stream_anthropic_messages_py_core |
| Agente con TUS tools (tool-use loop) | run_claude_tool_loop_py_core (defines tools + dispatch) |
| Token OAuth | load_claude_oauth_token_py_core (automático dentro de las anteriores) |
| Distribuir fuera del registry | apps/llm_cli/llm.py (versión standalone autocontenida) |
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from core.ask_llm import ask_llm
respuesta = ask_llm("resume esto en 3 lineas: ...", model="claude-haiku-4-5-20251001", echo=False)
Legacy
claude_stream_go_core (lanza claude -p --output-format stream-json) es el camino antiguo. No usarlo en código nuevo — preferir las funciones claude-direct. Queda solo para compatibilidad de consumidores existentes.
Excepción acotada
Si una tarea necesita genuinamente las capacidades de Claude Code (sus tools nativas, los MCP del repo, plan mode, el contexto del proyecto) y no basta con el modelo + tus propias tools via run_claude_tool_loop, entonces NO es una "invocación LLM" simple: documenta por qué en el código. El default sin excepción es ask_llm.
Telemetría / auditoría
Un claude -p o un subprocess(["claude", "-p", ...]) en código nuevo es un antipatrón auditable: sustituir por ask_llm / claude-direct. Buscar usos: grep -rn 'claude -p' --include='*.py' --include='*.sh' --include='*.go'.
Relación con otras reglas
- registry_calls — patrones canónicos de invocación de funciones; esta regla fija el patrón para la sub-tarea "invocar un LLM".
- registry_first — reusar antes que reescribir;
ask_llmes la función reutilizable para LLM.