Provider/model metadata request: Starveri API as a custom OpenAI-compatible endpoint

[Lwoxs]

NadirClaw already supports custom OpenAI-compatible endpoints through NADIRCLAW_API_BASE and openai/... model IDs, so this may be docs/metadata rather than a new transport.

I wanted to ask whether Starveri API would be a useful provider/model metadata entry or setup example for cost-sensitive coding routes.

Public Starveri references:

• Buyer/docs page: https://api.starveri.net/credits
• API docs and pricing table: https://api.starveri.net/docs
• Public model/pricing discovery: https://api.starveri.net/models
• OpenAPI: https://api.starveri.net/openapi.json
• LLM discovery summary: https://api.starveri.net/llms.txt

Possible NadirClaw setup shape:

NADIRCLAW_API_BASE=https://api.starveri.net/v1 \
NADIRCLAW_SIMPLE_MODEL=openai/gpt-5.3-codex-spark \
NADIRCLAW_MID_MODEL=openai/gpt-5.4-mini \
NADIRCLAW_COMPLEX_MODEL=openai/gpt-5.5 \
nadirclaw serve --verbose

For models.local.json / metadata, Starveri's public /models endpoint currently publishes these USD per 1M token prices:

NadirClaw model key	Starveri model	Input	Output
openai/gpt-5.1-codex	gpt-5.1-codex	0.4166667	3.3333333
openai/gpt-5.3-codex-spark	gpt-5.3-codex-spark	0.3333333	0.6666667
openai/gpt-5.3-codex	gpt-5.3-codex	0.1666667	0.3333333
openai/gpt-5.4	gpt-5.4	0.3333333	1.6666667
openai/gpt-5.4-mini	gpt-5.4-mini	0.2500000	1.1666667
openai/gpt-5.5	gpt-5.5	0.8333333	2.5000000

Potential metadata example:

{
  models: {
    openai/gpt-5.3-codex-spark: {
      cost_per_m_input: 0.3333333,
      cost_per_m_output: 0.6666667,
      has_vision: false
    },
    openai/gpt-5.4-mini: {
      cost_per_m_input: 0.25,
      cost_per_m_output: 1.1666667,
      has_vision: false
    },
    openai/gpt-5.5: {
      cost_per_m_input: 0.8333333,
      cost_per_m_output: 2.5,
      has_vision: false
    }
  }
}

Caveats:

• Starveri is an independent OpenAI-compatible gateway, not OpenAI.
• The advertised pricing hook is around 1/3 OpenAI-style pricing, but /models and /docs should remain the source of truth.
• Starveri also publishes cached-input prices and tool prices. NadirClaw's current model metadata shape appears to support cost_per_m_input and cost_per_m_output, so cached input and non-token tool charges probably should be omitted or documented as caveats unless there is a separate representation for them.
• Starveri has a limited text-only demo before purchase, but paid usage is prepaid credits; it should not be represented as a permanent free provider.

Would this be acceptable as a docs example / metadata override example, or would you prefer to keep custom OpenAI-compatible providers user-local only?

[doramirdor]

Thanks for the well-researched writeup — and for asking before opening a PR.

Short answer: yes, a docs example is welcome; per-provider metadata baked into the repo is not. Here's how the existing override surface already covers what you're proposing, and what would be useful to land.

Where Starveri fits cleanly today

1. Transport — already done. NADIRCLAW_API_BASE + openai/<model> IDs route through any OpenAI-compatible gateway via LiteLLM. No code change needed.

2. Pricing & capabilities — already done via models.local.json. User-managed overrides at ~/.nadirclaw/models.local.json merge on top of the generated models.json. Schema is {model_id: {context_window, cost_per_m_input, cost_per_m_output, has_vision, ...}}. Your proposed shape matches it exactly.

So the example would land as a docs page, not as a code change.

What I'd merge

A short doc — say docs/providers/starveri.md or a "custom OpenAI-compatible provider" section in the README — that shows:

• The four env vars (NADIRCLAW_API_BASE + the three NADIRCLAW_*_MODELs).
• A copy-pasteable models.local.json snippet with the current /models prices, with a one-line "verify against https://api.starveri.net/models — prices change" caveat.
• The neutral framing: "example of routing NadirClaw at a third-party OpenAI-compatible gateway. Not an endorsement. Starveri is operated independently from OpenAI."

What I'd leave out

• Built-in metadata entries in the repo. Pricing on third-party gateways drifts faster than our release cadence, and we'd end up shipping stale numbers. models.local.json is the right home for this — users control freshness.
• Cached-input prices and tool-call surcharges. The current schema (cost_per_m_input, cost_per_m_output) doesn't model these. Mention them as a caveat in the docs ("Starveri also bills cached-input and per-tool fees that NadirClaw's cost tracker does not currently account for"), don't try to encode them.

Things to verify in the PR

• Run nadirclaw test against Starveri with the env vars set — if any of the three tiers misbehaves the doc should say so.
• Confirm cost arithmetic looks sane on a real routed request (savings report should pick up the local metadata).

Happy to review if you open a PR with that shape. Thanks again for the diligence on the public-source links — that's exactly the kind of upstream-of-truth referencing that keeps docs maintainable.

🤖 Automated reply via scheduled triage (claude code, daily-check-github-status). A maintainer will follow up if there are additional considerations.