feat: introduce /admin API for stack administration and operations #4401

cdoern · 2025-12-17T00:50:52Z

What does this PR do?

Add new /admin API (v1alpha) for administrative operations including provider management, health checks, version info, and route listing
Implement using FastAPI routers following batches pattern with proper request/response models
Endpoints: /admin/providers, /admin/providers/{id}, /admin/inspect/routes, /admin/health, /admin/version
Create admin module structure: models.py, api.py, fastapi_routes.py, init.py
Add AdminImpl in llama_stack/core combining provider and inspect functionality
Deprecate standalone /providers and /inspect APIs (remain functional for backward compatibility)
Consolidate duplicate types: ProviderInfo, HealthInfo, RouteInfo, etc. now defined once in admin.models

Test Plan

new admin integration suite, uses generated stainless SDK, and records new tests on this PR.

cdoern · 2025-12-17T00:55:57Z

working through testing issues, some will fail on this PR while others should pass. This is because the tests use an unpublished client to test new API. This client will be published right after the PR merges so then CI will go green on main.

cdoern · 2025-12-17T01:22:17Z

tests work! but they fail due to legitimate resourcing issues with the admin group in the client: https://github.com/llamastack/llama-stack/actions/runs/20288111386/job/58267005772 will dig into this and fix tomorrow. PR should then be set to merge.

tests/integration/ci_matrix.json

mergify · 2025-12-17T16:01:50Z

This pull request has merge conflicts that must be resolved before it can be merged. @cdoern please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

github-actions · 2025-12-17T19:24:52Z

✱ Stainless preview builds

This PR will update the llama-stack-client SDKs with the following commit message.

feat: introduce /admin API for stack administration and operations

⚠️

llama-stack-client-node studio · code

There was a regression in your SDK.
generate ⚠️ → build ✅ → lint ✅ → test ✅
npm install https://pkg.stainless.com/s/llama-stack-client-node/2c9e2ab11a42bb2192370880781e2faee633c17c/dist.tar.gz

⚠️

llama-stack-client-kotlin studio · code

There was a regression in your SDK.
generate ⚠️ → lint ✅ → test ❗

⚠️

llama-stack-client-go studio · code

There was a regression in your SDK.
generate ❗ → lint ❗ → test ❗
go get github.com/stainless-sdks/llama-stack-client-go@236906dda29ae103193096518ede546068d65286

⚠️

llama-stack-client-python studio · conflict

There was a regression in your SDK.

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
Last updated: 2025-12-22 17:18:13 UTC

cdoern · 2025-12-17T22:00:42Z

new /admin API tests pass when using the client generated by this PR, using workflow_dispatch to capture the changes to the various workflows in this PR: https://github.com/llamastack/llama-stack/actions/runs/20318245671/job/58368233361

one note @ashwinb , the tests pass and run but no recordings are generated when using record-if-missing. Any idea why that is? regardless, this looks good to go. @raghotham I can open a PR for just 843b1c6 if you'd prefer, but it also may make sense to merge it with this PR since this PR is the one "testing" these new changes to the workflows in the actions link above. WDYT? I am fine with either!

ashwinb · 2025-12-17T22:14:12Z

CI is red?

.github/actions/run-and-record-tests/action.yml

cdoern · 2025-12-18T01:07:30Z

CI is red?

@ashwinb so on these types of PRs, the replay integration tests will be red. but the action I linked to also runs the integration test using the newly generated client from the Stainless SDK job.

The reason CI is red is because llama_stack_client.alpha.admin doesn't exist in the published client, but it does in the generated client. But, when this PR merges, the new 0.4.0a14 client will be generated and main CI should go back to being green!

Let me know if that makes sense

cdoern · 2025-12-18T01:11:17Z

PR here with workflow changes @ashwinb #4408

raghotham

Approving despite failures. Got clarification from @cdoern in the office hours

cdoern · 2025-12-18T17:38:00Z

once this merges, llama-stack-client0.4.0a14 will be cut, and main should be green. There might be a blip for a second where it's red, but should be transient.

cdoern · 2025-12-18T17:48:10Z

rebased to get the CI changes.

- Add new /admin API (v1alpha) for administrative operations including provider management, health checks, version info, and route listing - Implement using FastAPI routers following batches pattern with proper request/response models - Endpoints: /admin/providers, /admin/providers/{id}, /admin/inspect/routes, /admin/health, /admin/version - Create admin module structure: models.py, api.py, fastapi_routes.py, __init__.py - Add AdminImpl in llama_stack/core combining provider and inspect functionality - Deprecate standalone /providers and /inspect APIs (remain functional for backward compatibility) - Consolidate duplicate types: ProviderInfo, HealthInfo, RouteInfo, etc. now defined once in admin.models - Test new API using Stainless SDK in integration tests Signed-off-by: Charlie Doern <cdoern@redhat.com>

cdoern · 2025-12-18T20:27:20Z

ok, lets see if https://github.com/llamastack/llama-stack/actions/runs/20350287754/job/58472853387?pr=4401 passes

edit: all passed!

ashwinb · 2025-12-19T23:57:30Z

client-sdks/stainless/config.yml

+      admin:
+        methods:
+          list_providers: get /v1alpha/admin/providers
+          inspect_provider: get /v1alpha/admin/providers/{provider_id}


oh this feels odd

I was debating between this or

/v1alpha/admin/providers
/v1alpha/admin/{provider_id}

same for the other "nested" routes, I am unsure how much nesting we want/don't want. Either way it is alpha so we can change it if we want!

We will probably have other resources like attributes for abac in /admin. So, suggest leaving /providers in there. And like @cdoern mentioned, its still alpha, so we can change it later if this doesnt feel right.

…lamastack#4401) - Add new /admin API (v1alpha) for administrative operations including provider management, health checks, version info, and route listing - Implement using FastAPI routers following batches pattern with proper request/response models - Endpoints: /admin/providers, /admin/providers/{id}, /admin/inspect/routes, /admin/health, /admin/version - Create admin module structure: models.py, api.py, fastapi_routes.py, init.py - Add AdminImpl in llama_stack/core combining provider and inspect functionality - Deprecate standalone /providers and /inspect APIs (remain functional for backward compatibility) - Consolidate duplicate types: ProviderInfo, HealthInfo, RouteInfo, etc. now defined once in admin.models new admin integration suite, uses generated stainless SDK, and records new tests on this PR. Signed-off-by: Charlie Doern <cdoern@redhat.com>

…lamastack#4401) # What does this PR do? - Add new /admin API (v1alpha) for administrative operations including provider management, health checks, version info, and route listing - Implement using FastAPI routers following batches pattern with proper request/response models - Endpoints: /admin/providers, /admin/providers/{id}, /admin/inspect/routes, /admin/health, /admin/version - Create admin module structure: models.py, api.py, fastapi_routes.py, init.py - Add AdminImpl in llama_stack/core combining provider and inspect functionality - Deprecate standalone /providers and /inspect APIs (remain functional for backward compatibility) - Consolidate duplicate types: ProviderInfo, HealthInfo, RouteInfo, etc. now defined once in admin.models ## Test Plan new admin integration suite, uses generated stainless SDK, and records new tests on this PR. Signed-off-by: Charlie Doern <cdoern@redhat.com>

cdoern requested review from ashwinb, bbrowning, ehhuang, franciscojavierarceo, leseb, mattf and raghotham as code owners December 17, 2025 00:50

meta-cla bot added the CLA Signed This label is managed by the Meta Open Source bot. label Dec 17, 2025

cdoern changed the title ~~Admin~~ feat: introduce /admin API for stack administration and operations Dec 17, 2025

cdoern mentioned this pull request Dec 17, 2025

feat: introduce /admin API for stack administration and operations #4327

Closed

cdoern force-pushed the admin branch from 58a0d4b to 8fdeca8 Compare December 17, 2025 01:08

raghotham reviewed Dec 17, 2025

View reviewed changes

tests/integration/ci_matrix.json Outdated Show resolved Hide resolved

cdoern mentioned this pull request Dec 17, 2025

feat: migrate Inspect API to FastAPI router #4403

Merged

leseb mentioned this pull request Dec 17, 2025

Convert inspect API to use a FastAPI router #4346

Closed

cdoern force-pushed the admin branch from 8fdeca8 to a4cc3df Compare December 17, 2025 15:27

mergify bot added the needs-rebase label Dec 17, 2025

cdoern force-pushed the admin branch from a4cc3df to 53410ac Compare December 17, 2025 16:59

mergify bot removed the needs-rebase label Dec 17, 2025

cdoern force-pushed the admin branch from 53410ac to 3a4c78c Compare December 17, 2025 19:09

llamastack deleted a comment from github-actions bot Dec 17, 2025

cdoern force-pushed the admin branch from 3a4c78c to 7e7f0ca Compare December 17, 2025 19:23

cdoern force-pushed the admin branch 5 times, most recently from 954dd24 to 843b1c6 Compare December 17, 2025 21:45

ashwinb reviewed Dec 17, 2025

View reviewed changes

.github/actions/run-and-record-tests/action.yml Show resolved Hide resolved

cdoern force-pushed the admin branch from 843b1c6 to 4f8f297 Compare December 18, 2025 01:12

raghotham approved these changes Dec 18, 2025

View reviewed changes

cdoern force-pushed the admin branch from 4f8f297 to 2ab746a Compare December 18, 2025 17:47

cdoern force-pushed the admin branch from 2ab746a to e6256f0 Compare December 18, 2025 18:58

cdoern force-pushed the admin branch from e6256f0 to 90d3028 Compare December 18, 2025 20:24

cdoern requested a review from ashwinb December 19, 2025 23:53

ashwinb approved these changes Dec 19, 2025

View reviewed changes

ashwinb reviewed Dec 19, 2025

View reviewed changes

cdoern merged commit 258c52c into main Dec 22, 2025
38 of 42 checks passed

cdoern deleted the admin branch December 22, 2025 17:11

cdoern linked an issue Dec 22, 2025 that may be closed by this pull request

create /admin API stub #4303

Closed

cdoern removed a link to an issue Dec 22, 2025

create /admin API stub #4303

Closed

cdoern linked an issue Dec 22, 2025 that may be closed by this pull request

create /admin API stub #4303

Closed

feat: introduce /admin API for stack administration and operations #4401

feat: introduce /admin API for stack administration and operations #4401

Uh oh!

Conversation

cdoern commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Test Plan

Uh oh!

cdoern commented Dec 17, 2025

Uh oh!

cdoern commented Dec 17, 2025

Uh oh!

Uh oh!

mergify bot commented Dec 17, 2025

Uh oh!

github-actions bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds

Uh oh!

cdoern commented Dec 17, 2025

Uh oh!

ashwinb commented Dec 17, 2025

Uh oh!

Uh oh!

cdoern commented Dec 18, 2025

Uh oh!

cdoern commented Dec 18, 2025

Uh oh!

raghotham left a comment

Choose a reason for hiding this comment

Uh oh!

cdoern commented Dec 18, 2025

Uh oh!

cdoern commented Dec 18, 2025

Uh oh!

cdoern commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ashwinb Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

cdoern Dec 20, 2025

Choose a reason for hiding this comment

Uh oh!

raghotham Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cdoern commented Dec 17, 2025 •

edited

Loading

github-actions bot commented Dec 17, 2025 •

edited

Loading

cdoern commented Dec 18, 2025 •

edited

Loading