# Req LLM Adapter

> Skill: ReqLLM Adapter (Serena/Codex)

- Skill: `layeddie/req-llm-adapter` (Agent Skill)
- Install (CLI): `npx skillmds@latest add layeddie/req-llm-adapter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/layeddie/req-llm-adapter/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: layeddie (https://skillmd.com/u/layeddie)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/layeddie/req-llm-adapter

---

# Skill: ReqLLM Adapter (Serena/Codex)

Goal: Give agents a compact, provider-agnostic recipe for using `req_llm` in BEAM projects (OpenCode/Serena/Codex). Keep opt-in and align with `docs/req_llm.md`.

## When to use
- Project wants a unified LLM client without bespoke HTTP calls.
- Need standard prompts for `generate_text/3`, `stream_text/3`, or `generate_object/4`.
- Need to surface usage/cost telemetry and keep keys out of git.

## Quick setup (per project)
1) Ensure dep is available (templates mark optional): `{:req_llm, "~> 1.5", optional: true}`.
2) Keys via env or `.env` (preferred): `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, or `REQ_LLM_PROVIDERS_JSON`.
3) For local endpoints (LM Studio/Ollama with OpenAI plugin) set `REQ_LLM_OPENAI_BASE_URL` and a dummy key.
4) Add a thin wrapper module (or copy from `templates/llm/req_llm_example.ex`) and wire telemetry hook below.

## Prompt snippets (drop into agent messages)
- Text:
  ```
  Use ReqLLM.generate_text/3 with opts:
  - :provider (e.g., :openai, :anthropic, :openrouter)
  - :model (string)
  - :messages (list of %{role: :user|:assistant|:system, content: string})
  - :max_output_tokens (optional)
  Return {:ok, %ReqLLM.Response{content, usage}} or {:error, reason}.
  ```
- Streaming:
  ```
  Use ReqLLM.stream_text/3. Consume stream of %ReqLLM.StreamChunk{type: :content|:tool_call|:meta, data: ...}.
  Accumulate content chunks; handle :tool_call separately.
  ```
- Object generation:
  ```
  Use ReqLLM.generate_object/4 with a JSON schema map under :response_schema.
  Expect {:ok, %{object: map(), usage: usage}} or {:error, reason}.
  ```

## Telemetry hook
```elixir
:telemetry.attach(
  "req-llm-usage",
  [:req_llm, :token_usage],
  fn _event, measurements, metadata, _ ->
    Logger.info("req_llm usage", measurements: measurements, metadata: metadata)
  end,
  nil
)
```
Measurements include tokens and cost fields; safe to forward to OTEL/Logger.

## Guardrails
- Keep HTTP/1 Finch pools unless you’ve validated HTTP/2 with your stack.
- Never commit keys; prefer env/direnv/Nix devshell vars.
- Mark the dep optional to avoid pulling LLM libs when unused.
- For CI, skip `mix req_llm.model_sync` unless explicitly needed.

## Validation checklist (when enabled)
- `mix format`
- `mix credo --strict`
- `mix test`
- Optional: `REQ_LLM_FIXTURES_MODE=record mix test` (with keys)
- Optional: `mix dialyzer` (if PLTs available)

## Pointers
- Full doc: `docs/req_llm.md`
- Example module: `templates/llm/req_llm_example.ex`