51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
## 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) |
|
|
|
|
```python
|
|
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_llm` es la función reutilizable para LLM.
|