feat: add Cascadia provider for distributed on-prem Intel AI PC inference

[t8]

Description

Adds cascadia as a provider (closes #1146). Cascadia (https://cascadia.to) is a
distributed inference runtime that shards open-weights models (INT4 OpenVINO) across
fleets of Intel AI PCs behind an OpenAI-compatible coordinator, keeping inference
on-premises.

How

• BaseOpenAIProvider subclass following the vLLM keyless pattern, extended to honor
  CASCADIA_API_KEY from the environment when a fleet is keyed (an explicit api_key
  wins; otherwise it falls back to no-key-required so trusted-LAN coordinators work
  keyless). Env-configurable base via CASCADIA_API_BASE (default
  http://localhost:9090/v1); no new dependencies (cascadia = [] extra, spliced
  into all).
• Capability flags scoped to v1: completion, streaming, reasoning, and list-models
  on; responses, embeddings, moderation, image, PDF, and batch off.
• Registered in LLMProvider (src/any_llm/constants.py), the tests/conftest.py
  fixture maps, and LOCAL_PROVIDERS + CI_EXCLUDED_PROVIDERS in
  tests/constants.py (self-hosted backend; CI cannot reach a fleet, mirroring vllm).

Files: src/any_llm/providers/cascadia/{cascadia,__init__}.py,
src/any_llm/constants.py, pyproject.toml, tests/constants.py,
tests/conftest.py, and tests/unit/providers/test_cascadia_provider.py.

Testing

• tests/unit/providers/test_cascadia_provider.py: provider metadata, keyless auth,
  explicit-key passthrough, CASCADIA_API_KEY env resolution, env/default base
  resolution, capability flags, and enum/loader registration. 8 passed, 100%
  line+branch coverage of cascadia.py.
• Full local unit suite green (1419 passed, 64 skipped), no regressions. Developed
  against current main (latest release any-llm-sdk 1.18.0); rebased on the default
  branch, where no cascadia provider previously existed.
• pre-commit run on the change set: ruff, ruff-format, mypy (strict), and codespell
  all pass.
• Manual smoke via acompletion("cascadia:<model>", ...) against a Cascadia
  coordinator implementing the OpenAI-compatible contract: non-streaming and streaming
  both return content and a populated usage object. Production Cascadia runs the same
  contract across a physical Intel AI PC fleet.

Smoke transcript (real coordinator)

$ export CASCADIA_API_BASE=https://<coordinator>/api/v1
$ export CASCADIA_API_KEY=<bearer token>     # keyed fleet; trusted-LAN fleets run keyless
$ python smoke_cascadia.py

models: ['llama-8b-2stage', 'qwen3-8b']
using: cascadia:qwen3-8b

# non-streaming: content + usage object returned
non-stream: '<think> [reasoning trimmed] </think>\n\nCASCADIA-OK'
            usage: CompletionUsage(completion_tokens=1, prompt_tokens=0, total_tokens=1)

# streaming: reassembled deltas
stream:     '<think> [reasoning trimmed] </think>\n\nOne, two, three, four, five.'

qwen3-8b is a reasoning model, so it emits a <think> block before the answer; that
text is trimmed here for readability. Token counts on this hosted demo coordinator are
approximate; the provider faithfully surfaces whatever the coordinator reports in
usage.

PR Type

• 🆕 New Feature

Relevant issues

Closes #1146

Checklist

• I understand the code I am submitting.
• I have added unit tests that prove my fix/feature works
• I have run this code locally and verified it fixes the issue.
• New and existing tests pass locally
• Documentation was updated where necessary
• I have read and followed the contribution guidelines
• AI Usage:
  • No AI was used.
  • AI was used for drafting/refactoring.
  • This is fully AI-generated.

AI Usage Information

• AI Model used: Claude Opus 4.8

• AI Developer Tool used: Claude Code

• Any other info you'd like to share: The provider, tests, and docs were drafted with
  AI assistance under my direction and review. I verified the change locally (full unit
  suite, ruff/mypy-strict/codespell, and a live smoke against a real Cascadia
  coordinator) and will respond to review comments myself.

• I am an AI Agent filling out this form (check box if true)

Summary by CodeRabbit

• New Features
  • Added Cascadia as a new supported language model provider with an OpenAI-compatible coordinator endpoint.
  • Enabled completion with streaming and reasoning-style capabilities, plus model listing.
  • Added flexible API key handling using CASCADIA_API_KEY (with safe non-failing fallback when unset).
• Optional Dependencies
  • Introduced a new cascadia extras option (and included it in all).
• Tests
  • Added unit test coverage for Cascadia provider registration, configuration, capability flags, and API-base/API-key precedence.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4c3478cf-c920-4c8d-8dec-e4da77c5c0f1

📥 Commits

Reviewing files that changed from the base of the PR and between 114b1f1 and 62cda93.

📒 Files selected for processing (3)

• src/any_llm/providers/cascadia/cascadia.py
• tests/conftest.py
• tests/unit/providers/test_cascadia_provider.py

---

Walkthrough

Adds CascadiaProvider, a thin BaseOpenAIProvider subclass targeting an OpenAI-compatible on-premises coordinator endpoint. The change registers a CASCADIA enum value, implements the provider class with capability flags and a keyless API-key fallback, wires the package export, adds test fixtures, and introduces a full unit test suite.

Changes

Cascadia Provider Integration

Layer / File(s)	Summary
Enum registration and package dependency src/any_llm/constants.py, pyproject.toml	LLMProvider.CASCADIA enum member is added and a cascadia = [] optional-dependencies group is introduced, included in the all extra.
CascadiaProvider class and package export src/any_llm/providers/cascadia/cascadia.py, src/any_llm/providers/cascadia/__init__.py	Implements CascadiaProvider with API_BASE, environment variable names, SUPPORTS_* capability flags (completion and streaming enabled; embeddings, moderation, images, batch, rerank, and responses disabled), and a _verify_and_set_api_key override that falls back to a "no-key-required" sentinel. The package __init__ re-exports CascadiaProvider via __all__.
Test fixtures and provider classification tests/conftest.py, tests/constants.py	CASCADIA is added to the reasoning model, small model, and client configuration fixture maps. It is also appended to LOCAL_PROVIDERS and CI_EXCLUDED_PROVIDERS.
Unit tests for CascadiaProvider tests/unit/providers/test_cascadia_provider.py	Unit tests assert provider metadata constants, API-key handling (absent, explicit, and environment variable), API-base resolution and default fallback, all capability flags, and provider registration and discovery.

Possibly related PRs

• mozilla-ai/any-llm#1104: Adds another provider using the same registration and test infrastructure patterns as this PR.

Suggested reviewers

• tbille

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately summarises the main change: adding a Cascadia provider for distributed on-premises Intel AI PC inference.
Description check	✅ Passed	The PR description is comprehensive, addressing all template sections including description, PR type, relevant issues, and completed checklist items with detailed explanation.
Linked Issues check	✅ Passed	All coding requirements from issue #1146 are satisfied: Cascadia provider implemented as BaseOpenAIProvider subclass [#1146], keyless and API-key support added [#1146], environment variables configured [#1146], capability flags scoped to v1 [#1146], 100% unit test coverage achieved [#1146], and provider registered and excluded from CI [#1146].
Out of Scope Changes check	✅ Passed	All changes directly support adding the Cascadia provider: provider implementation, enum registration, test fixtures, unit tests, and dependency configuration. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/any_llm/providers/cascadia/cascadia.py`:
- Around line 37-42: The return type annotation for the _verify_and_set_api_key
method in the Cascadia provider is incorrect. The method always returns a string
value through the chain of `api_key or os.getenv(self.ENV_API_KEY_NAME) or
"no-key-required"`, which guarantees a string is always returned and never None.
Update the return type annotation from `str | None` to `str` to accurately
reflect the method's behavior.

In `@tests/conftest.py`:
- Line 185: The test fixture configuration for LLMProvider.CASCADIA uses the IP
address 127.0.0.1 for the api_base URL, while the provider's API_BASE constant
uses localhost. For consistency and maintainability, replace 127.0.0.1 with
localhost in the api_base value for the LLMProvider.CASCADIA configuration in
the test fixture. Both resolve to the same address, but using the same hostname
across the codebase improves clarity.

In `@tests/unit/providers/test_cascadia_provider.py`:
- Around line 8-68: Add a new test function to verify API key precedence
behavior. Create a test that sets the CASCADIA_API_KEY environment variable to
one value using monkeypatch, then instantiates CascadiaProvider with a different
explicit api_key parameter, and asserts that the _verify_and_set_api_key method
returns the explicit key value, confirming that the explicit key takes
precedence over the environment variable as intended by the api_key or
os.getenv(...) logic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 54b1b496-37ff-4886-a3fb-19cd25c91c03

📥 Commits

Reviewing files that changed from the base of the PR and between f25c461 and 114b1f1.

📒 Files selected for processing (7)

• pyproject.toml
• src/any_llm/constants.py
• src/any_llm/providers/cascadia/__init__.py
• src/any_llm/providers/cascadia/cascadia.py
• tests/conftest.py
• tests/constants.py
• tests/unit/providers/test_cascadia_provider.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/any_llm/constants.py	100.00% <100.00%> (ø)
src/any_llm/providers/cascadia/__init__.py	100.00% <100.00%> (ø)
src/any_llm/providers/cascadia/cascadia.py	100.00% <100.00%> (ø)

... and 38 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tbille]

@t8 nice one, thanks for the contribution. I just approved the workflows to run. Coderabbit left some tiny comments. I'll let you fix them.
I should make a release this week with the new provider.

[t8]

Thanks @tbille! Just addressed. Appreciate the quick reply and support.

[tbille]

super nice @t8
I should make a release during the week, I'll let you know once it's live 🎉 🚀