diff --git a/.github/workflows/interactions-spec-canary.yml b/.github/workflows/interactions-spec-canary.yml new file mode 100644 index 00000000000..7ec3defdcb7 --- /dev/null +++ b/.github/workflows/interactions-spec-canary.yml @@ -0,0 +1,91 @@ +name: Interactions spec canary + +on: + schedule: + - cron: "17 7 * * *" + pull_request: + paths: + - .github/workflows/interactions-spec-canary.yml + - tests/unit/interactions/** + - litellm/types/interactions/** + workflow_dispatch: + +permissions: {} + +concurrency: interactions-spec-canary + +jobs: + interactions-spec-canary: + name: interactions-spec-canary + if: github.repository == 'BerriAI/litellm' + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + outputs: + compliance: ${{ steps.compliance.outcome }} + steps: + - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0 + with: + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 + with: + python-version: "3.12" + + - name: Set up uv + uses: ./.github/actions/setup-uv-with-retries + with: + version: "0.10.9" + + - name: Install dependencies + run: .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra proxy --no-install-project + + - name: Run the compliance tests against Google's live spec + id: compliance + run: | + uv run --no-sync pytest tests/unit/interactions/test_openapi_compliance.py \ + --interactions-spec-url=https://ai.google.dev/static/api/interactions.openapi.json \ + --tb=short -vv -p no:rerunfailures -p no:pytest-retry \ + --allow-hosts=127.0.0.1,::1,localhost,ai.google.dev + + tracking-issue: + name: tracking-issue + needs: interactions-spec-canary + if: always() && github.event_name != 'pull_request' && github.ref_name == github.event.repository.default_branch && github.repository == 'BerriAI/litellm' + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + issues: write + steps: + - name: File the tracking issue unless the compliance step passed, close it when it did + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + env: + COMPLIANCE_OUTCOME: ${{ needs.interactions-spec-canary.outputs.compliance }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + with: + script: | + const title = "Interactions spec canary is red"; + const outcome = process.env.COMPLIANCE_OUTCOME; + const runUrl = process.env.RUN_URL; + const query = `repo:${context.repo.owner}/${context.repo.repo} is:issue is:open in:title "${title}"`; + const { data: found } = await github.rest.search.issuesAndPullRequests({ q: query, per_page: 20 }); + const open = found.items.find((issue) => issue.title === title); + if (outcome === "success") { + if (open === undefined) return; + await github.rest.issues.createComment({ ...context.repo, issue_number: open.number, body: `Green again: ${runUrl}` }); + await github.rest.issues.update({ ...context.repo, issue_number: open.number, state: "closed" }); + return; + } + const state = outcome === "failure" ? "red" : `not run (compliance step outcome: ${outcome || "none"})`; + if (open !== undefined) { + await github.rest.issues.createComment({ ...context.repo, issue_number: open.number, body: `Still ${state}: ${runUrl}` }); + return; + } + await github.rest.issues.create({ + ...context.repo, + title, + assignees: ["mateo-berri"], + body: `The scheduled run of tests/unit/interactions/test_openapi_compliance.py against Google's live Interactions spec is ${state}: ${runUrl}\n\nlitellm/types/interactions/README.md says how to refresh the snapshot and regenerate the types.`, + }); diff --git a/.github/workflows/test-unit.yml b/.github/workflows/test-unit.yml index 2276efc4e34..76af64c8ccd 100644 --- a/.github/workflows/test-unit.yml +++ b/.github/workflows/test-unit.yml @@ -425,6 +425,7 @@ jobs: tests/unit/realtime_api tests/unit/rerank_api tests/unit/search + tests/unit/text_completions tests/unit/vector_stores tests/unit/videos python-version: "3.12" diff --git a/Dockerfile b/Dockerfile index 306c455c9de..6bab3d5ad71 100644 --- a/Dockerfile +++ b/Dockerfile @@ -61,6 +61,7 @@ RUN apk add --no-cache \ python-3.13-dev \ rust \ openssl \ + libssl3 \ openssl-dev \ nodejs \ npm \ diff --git a/backend/Dockerfile b/backend/Dockerfile index 772f3d5b351..46d65c432bb 100644 --- a/backend/Dockerfile +++ b/backend/Dockerfile @@ -43,7 +43,7 @@ COPY --from=uvbin /uv /uvx /usr/local/bin/ # instead of nodeenv downloading one whose dynamic deps may not be in Wolfi # (e.g. Node 26.2.0 needs libatomic). Retry for transient apk.cgr.dev flakes. RUN for i in 1 2 3; do \ - apk add --no-cache bash gcc python-3.13 python-3.13-dev openssl openssl-dev libsndfile nodejs npm && break; \ + apk add --no-cache bash gcc python-3.13 python-3.13-dev openssl libssl3 openssl-dev libsndfile nodejs npm && break; \ [ $i = 3 ] && { echo "apk add failed after 3 retries" >&2; exit 1; }; \ sleep 5; \ done diff --git a/docker/Dockerfile.database b/docker/Dockerfile.database index f1fa64be630..69d9c26b2a8 100644 --- a/docker/Dockerfile.database +++ b/docker/Dockerfile.database @@ -59,6 +59,7 @@ RUN apk add --no-cache \ python-3.13 \ python-3.13-dev \ openssl \ + libssl3 \ openssl-dev \ nodejs \ npm \ diff --git a/docker/Dockerfile.non_root b/docker/Dockerfile.non_root index 69da9fe149b..54bf8c807aa 100644 --- a/docker/Dockerfile.non_root +++ b/docker/Dockerfile.non_root @@ -60,6 +60,7 @@ RUN for i in 1 2 3; do \ coreutils \ curl \ openssl \ + libssl3 \ libsndfile \ nodejs \ npm && break || sleep 5; \ diff --git a/docker/build_from_pip/Dockerfile.build_from_pip b/docker/build_from_pip/Dockerfile.build_from_pip index a5733f0e1a0..25a7ed2fa97 100644 --- a/docker/build_from_pip/Dockerfile.build_from_pip +++ b/docker/build_from_pip/Dockerfile.build_from_pip @@ -30,7 +30,7 @@ RUN uv venv --python python && \ "google-cloud-aiplatform==1.133.0" \ "google-genai==1.37.0" \ "anthropic[vertex]==0.84.0" \ - "grpcio==1.78.0" \ + "grpcio==1.84.1" \ "prometheus-client==0.20.0" \ "langfuse==2.59.7" \ "opentelemetry-api==1.28.0" \ diff --git a/gateway/Dockerfile b/gateway/Dockerfile index 6af25df0c5d..390a5f5666f 100644 --- a/gateway/Dockerfile +++ b/gateway/Dockerfile @@ -59,7 +59,7 @@ COPY --from=uvbin /uv /uvx /usr/local/bin/ # instead of nodeenv downloading one whose dynamic deps may not be in Wolfi # (e.g. Node 26.2.0 needs libatomic). Retry for transient apk.cgr.dev flakes. RUN for i in 1 2 3; do \ - apk add --no-cache bash gcc python-3.13 python-3.13-dev openssl openssl-dev libsndfile nodejs npm && break; \ + apk add --no-cache bash gcc python-3.13 python-3.13-dev openssl libssl3 openssl-dev libsndfile nodejs npm && break; \ [ $i = 3 ] && { echo "apk add failed after 3 retries" >&2; exit 1; }; \ sleep 5; \ done diff --git a/litellm/litellm_core_utils/exception_mapping_utils.py b/litellm/litellm_core_utils/exception_mapping_utils.py index 1f49cc2c4bb..e8da59cd33a 100644 --- a/litellm/litellm_core_utils/exception_mapping_utils.py +++ b/litellm/litellm_core_utils/exception_mapping_utils.py @@ -102,6 +102,7 @@ class ExceptionCheckers: "`inputs` tokens + `max_new_tokens` must be", "exceeds the available context size", # llama.cpp/Lemonade "exceeds the maximum number of tokens allowed", # Gemini + '"code": "context_length_exceeded"', ] for substring in known_exception_substrings: if substring in _error_str_lowercase: diff --git a/litellm/llms/anthropic/pass_through/messages/transformation.py b/litellm/llms/anthropic/pass_through/messages/transformation.py index 9f3aa0130d1..dfe0788e50a 100644 --- a/litellm/llms/anthropic/pass_through/messages/transformation.py +++ b/litellm/llms/anthropic/pass_through/messages/transformation.py @@ -75,6 +75,12 @@ def messages_carry_output_config(messages: Sequence[object]) -> bool: _messages_carry_output_config = messages_carry_output_config +def _ensure_stop_sequence(response: AnthropicMessagesResponse) -> AnthropicMessagesResponse: + if "stop_sequence" not in response: + response["stop_sequence"] = None # rebind-ok: normalize the request-owned response in place + return response + + class AnthropicMessagesConfig(BaseAnthropicMessagesConfig): _workload_identity_eligible: ClassVar[bool] = True @@ -715,14 +721,12 @@ class AnthropicMessagesConfig(BaseAnthropicMessagesConfig): raw_response: httpx.Response, logging_obj: LiteLLMLoggingObj, ) -> AnthropicMessagesResponse: - """ - No transformation is needed for Anthropic messages, since we want the response in the Anthropic /v1/messages API spec - """ try: raw_response_json: Final = raw_response.json() except Exception: raise AnthropicError(message=raw_response.text, status_code=raw_response.status_code) - return AnthropicMessagesResponse(**raw_response_json) + response: Final = AnthropicMessagesResponse(**raw_response_json) + return _ensure_stop_sequence(response) def get_async_streaming_response_iterator( self, diff --git a/litellm/main.py b/litellm/main.py index 27700cf9def..32a7c290bb8 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -143,6 +143,7 @@ from litellm.router_utils.reasoning_effort_capability import ( resolve_chat_reasoning, ) from litellm.secret_managers.main import get_secret_bool, get_secret_str +from litellm.text_completions.streaming_iterator import TextCompletionStreamWrapper from litellm.types.completion import ( CompletionDispatchContext, _CompletionDispatchResult, @@ -169,7 +170,6 @@ from litellm.utils import ( ProviderConfigManager, TextChoices, TextCompletionResponse, - TextCompletionStreamWrapper, TranscriptionResponse, Usage, add_provider_specific_params_to_optional_params, diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json index cb9bfa6ffe4..840576e8225 100644 --- a/litellm/model_prices_and_context_window_backup.json +++ b/litellm/model_prices_and_context_window_backup.json @@ -36861,17 +36861,17 @@ }, "gpt-6-luna": { "cache_creation_input_token_cost": 1.25e-07, - "cache_creation_input_token_cost_decisions": 1e-07, + "cache_creation_input_token_cost_decisions": 1.25e-07, "cache_creation_input_token_cost_above_272k_tokens": 2.5e-07, - "cache_creation_input_token_cost_above_272k_tokens_decisions": 2e-07, + "cache_creation_input_token_cost_above_272k_tokens_decisions": 2.5e-07, "cache_creation_input_token_cost_above_272k_tokens_flex": 1.25e-07, "cache_creation_input_token_cost_above_272k_tokens_priority": 5e-07, "cache_creation_input_token_cost_flex": 6.25e-08, "cache_creation_input_token_cost_priority": 2.5e-07, "cache_read_input_token_cost": 1e-08, - "cache_read_input_token_cost_decisions": 1e-07, + "cache_read_input_token_cost_decisions": 1e-08, "cache_read_input_token_cost_above_272k_tokens": 2e-08, - "cache_read_input_token_cost_above_272k_tokens_decisions": 2e-07, + "cache_read_input_token_cost_above_272k_tokens_decisions": 2e-08, "cache_read_input_token_cost_above_272k_tokens_flex": 1e-08, "cache_read_input_token_cost_above_272k_tokens_priority": 4e-08, "cache_read_input_token_cost_batches": 5e-09, @@ -73330,6 +73330,7 @@ ] }, "vertex_ai/veo-2.0-generate-001": { + "deprecation_date": "2026-06-30", "litellm_provider": "vertex_ai-video-models", "max_input_tokens": 1024, "max_tokens": 1024, diff --git a/litellm/proxy/_experimental/out/assets/aria-agent.png b/litellm/proxy/_experimental/out/assets/aria-agent.png new file mode 100644 index 00000000000..870773933e3 Binary files /dev/null and b/litellm/proxy/_experimental/out/assets/aria-agent.png differ diff --git a/litellm/proxy/_experimental/out/assets/logos/claude.svg b/litellm/proxy/_experimental/out/assets/logos/claude.svg new file mode 100644 index 00000000000..ede30652b25 --- /dev/null +++ b/litellm/proxy/_experimental/out/assets/logos/claude.svg @@ -0,0 +1,27 @@ + +Claude diff --git a/litellm/proxy/_lazy_features.py b/litellm/proxy/_lazy_features.py index 0e2eed73364..28c701e0fc2 100644 --- a/litellm/proxy/_lazy_features.py +++ b/litellm/proxy/_lazy_features.py @@ -299,11 +299,6 @@ LAZY_FEATURES: Final[tuple[LazyFeature, ...]] = ( module_path="litellm.proxy.spend_tracking.vantage_endpoints", path_prefixes=("/vantage",), ), - LazyFeature( - name="usage_ai", - module_path="litellm.proxy.management_endpoints.usage_endpoints", - path_prefixes=("/usage/ai",), - ), LazyFeature( name="prompts", module_path="litellm.proxy.prompts.prompt_endpoints", diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json index 4572e59944b..0dd978ee855 100644 --- a/litellm/proxy/_lazy_openapi_snapshot.json +++ b/litellm/proxy/_lazy_openapi_snapshot.json @@ -11407,7 +11407,7 @@ }, "/systemone": { "post": { - "description": "Judge a `state` against 1 to 128 named `questions` and get one calibrated answer per question name.\n\nQuestion types are `noul` (probability the answer is yes), `choice` (one label out of `criteria`, with\n`confidence` and `probabilities`), `score` (an index into the `criteria` levels, with `confidence`,\n`legend` and `probabilities`) and `box` (the image region the `instructions` describe, with `confidence`).\nTypeSafe models also take images in `assets`, each one referenced by its key in `state`. Requests that break\nthese rules are rejected with a 400 before any provider is called. `model` is any decision model in the proxy model list. OpenAI decision models accept this format\ntoo, LiteLLM translates it and keeps the answers keyed by question name. Streaming is not supported.\n\n[Docs](https://docs.litellm.ai/docs/decisions)", + "description": "Judge a `state` against one or more named `questions` and get one calibrated answer per question name.\n\nQuestion types are `noul` (probability the answer is yes), `choice` (one label out of `criteria`, with\n`confidence` and `probabilities`), `score` (an index into the `criteria` levels, with `confidence`,\n`legend` and `probabilities`) and `box` (the image region the `instructions` describe, with `confidence`).\nTypeSafe models also take images in `assets`, each one referenced by its key in `state`. Requests that break\nthese rules are rejected with a 400 before any provider is called. `model` is any decision model in the proxy model list. OpenAI decision models accept this format\ntoo, LiteLLM translates it and keeps the answers keyed by question name. Streaming is not supported.\n\n[Docs](https://docs.litellm.ai/docs/decisions)", "operationId": "systemone_systemone_post", "requestBody": { "content": { @@ -11813,7 +11813,6 @@ ] }, "description": "Named noul, choice and score questions. Each key becomes a key in the answers", - "maxProperties": 128, "minProperties": 1, "propertyNames": { "minLength": 1 @@ -12814,7 +12813,7 @@ }, "/v1/systemone": { "post": { - "description": "Judge a `state` against 1 to 128 named `questions` and get one calibrated answer per question name.\n\nQuestion types are `noul` (probability the answer is yes), `choice` (one label out of `criteria`, with\n`confidence` and `probabilities`), `score` (an index into the `criteria` levels, with `confidence`,\n`legend` and `probabilities`) and `box` (the image region the `instructions` describe, with `confidence`).\nTypeSafe models also take images in `assets`, each one referenced by its key in `state`. Requests that break\nthese rules are rejected with a 400 before any provider is called. `model` is any decision model in the proxy model list. OpenAI decision models accept this format\ntoo, LiteLLM translates it and keeps the answers keyed by question name. Streaming is not supported.\n\n[Docs](https://docs.litellm.ai/docs/decisions)", + "description": "Judge a `state` against one or more named `questions` and get one calibrated answer per question name.\n\nQuestion types are `noul` (probability the answer is yes), `choice` (one label out of `criteria`, with\n`confidence` and `probabilities`), `score` (an index into the `criteria` levels, with `confidence`,\n`legend` and `probabilities`) and `box` (the image region the `instructions` describe, with `confidence`).\nTypeSafe models also take images in `assets`, each one referenced by its key in `state`. Requests that break\nthese rules are rejected with a 400 before any provider is called. `model` is any decision model in the proxy model list. OpenAI decision models accept this format\ntoo, LiteLLM translates it and keeps the answers keyed by question name. Streaming is not supported.\n\n[Docs](https://docs.litellm.ai/docs/decisions)", "operationId": "systemone_v1_systemone_post", "requestBody": { "content": { @@ -13220,7 +13219,6 @@ ] }, "description": "Named noul, choice and score questions. Each key becomes a key in the answers", - "maxProperties": 128, "minProperties": 1, "propertyNames": { "minLength": 1 @@ -57900,163 +57898,6 @@ } } }, - "usage_ai": { - "components": { - "schemas": { - "ChatMessage": { - "properties": { - "content": { - "title": "Content", - "type": "string" - }, - "role": { - "enum": [ - "user", - "assistant" - ], - "title": "Role", - "type": "string" - } - }, - "required": [ - "role", - "content" - ], - "title": "ChatMessage", - "type": "object" - }, - "HTTPValidationError": { - "properties": { - "detail": { - "items": { - "$ref": "#/components/schemas/ValidationError" - }, - "title": "Detail", - "type": "array" - } - }, - "title": "HTTPValidationError", - "type": "object" - }, - "UsageAIChatRequest": { - "properties": { - "messages": { - "description": "Chat messages (user/assistant history)", - "items": { - "$ref": "#/components/schemas/ChatMessage" - }, - "title": "Messages", - "type": "array" - }, - "model": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Model to use for AI chat", - "title": "Model" - } - }, - "required": [ - "messages" - ], - "title": "UsageAIChatRequest", - "type": "object" - }, - "ValidationError": { - "properties": { - "ctx": { - "title": "Context", - "type": "object" - }, - "input": { - "title": "Input" - }, - "loc": { - "items": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ] - }, - "title": "Location", - "type": "array" - }, - "msg": { - "title": "Message", - "type": "string" - }, - "type": { - "title": "Error Type", - "type": "string" - } - }, - "required": [ - "loc", - "msg", - "type" - ], - "title": "ValidationError", - "type": "object" - } - } - }, - "paths": { - "/usage/ai/chat": { - "post": { - "description": "AI chat about usage data. Streams SSE events with the AI response.\nThe AI agent has access to tools that query aggregated daily activity data.", - "operationId": "usage_ai_chat_usage_ai_chat_post", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UsageAIChatRequest" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": {} - } - }, - "description": "Successful Response" - }, - "422": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - }, - "description": "Validation Error" - } - }, - "security": [ - { - "APIKeyHeader": [] - } - ], - "summary": "Usage Ai Chat", - "tags": [ - "usage_ai" - ] - } - } - } - }, "vantage": { "components": { "schemas": { diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 54acf59ef80..28d3c08bb31 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -2717,6 +2717,13 @@ class ConfigGeneralSettings(LiteLLMPydanticObjectBase): "hidden model can still be called." ), ) + return_wildcard_routes: bool | None = Field( + None, + description=( + "When true, `/v1/models` lists wildcard routes like `openai/*` unless the request passes " + "`return_wildcard_routes=false`." + ), + ) alerting: list | None = Field( None, description="List of alerting integrations - e.g. `alerting: ['slack', 'webhook', 'email']`. 'slack' posts Slack-format messages to any Slack-compatible webhook (Slack, Rocket.Chat, Mattermost); 'webhook' posts structured JSON budget alerts to WEBHOOK_URL", diff --git a/litellm/proxy/decisions_endpoints/endpoints.py b/litellm/proxy/decisions_endpoints/endpoints.py index 366842d23a6..a8684dd9757 100644 --- a/litellm/proxy/decisions_endpoints/endpoints.py +++ b/litellm/proxy/decisions_endpoints/endpoints.py @@ -228,7 +228,7 @@ async def systemone( user_api_key_dict: Annotated[UserAPIKeyAuth, Depends(user_api_key_auth)], ): """ - Judge a `state` against 1 to 128 named `questions` and get one calibrated answer per question name. + Judge a `state` against one or more named `questions` and get one calibrated answer per question name. Question types are `noul` (probability the answer is yes), `choice` (one label out of `criteria`, with `confidence` and `probabilities`), `score` (an index into the `criteria` levels, with `confidence`, diff --git a/litellm/proxy/management_endpoints/usage_endpoints/__init__.py b/litellm/proxy/management_endpoints/usage_endpoints/__init__.py deleted file mode 100644 index 6e68dcd2a2e..00000000000 --- a/litellm/proxy/management_endpoints/usage_endpoints/__init__.py +++ /dev/null @@ -1,9 +0,0 @@ -""" -Usage endpoints package. - -Re-exports the router from endpoints module. -""" - -from litellm.proxy.management_endpoints.usage_endpoints.endpoints import ( # noqa: F401 - router, -) diff --git a/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py b/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py deleted file mode 100644 index 7a45d0438de..00000000000 --- a/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py +++ /dev/null @@ -1,627 +0,0 @@ -""" -AI Usage Chat - uses LLM tool calling to answer questions about -usage/spend data by querying the aggregated daily activity endpoints. -""" - -import json -from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Mapping, Sequence -from datetime import date -from typing import Final, Literal, NamedTuple, Protocol, cast, overload - -from fastapi import HTTPException -from typing_extensions import ReadOnly, TypedDict - -import litellm -from litellm._logging import verbose_proxy_logger -from litellm.constants import DEFAULT_COMPETITOR_DISCOVERY_MODEL -from litellm.proxy._types import CommonProxyErrors -from litellm.types.proxy.management_endpoints.common_daily_activity import ( - SpendAnalyticsPaginatedResponse, -) -from litellm.types.utils import ChatCompletionMessageToolCall - -# --------------------------------------------------------------------------- -# Constants -# --------------------------------------------------------------------------- - -USAGE_AI_TEMPERATURE: Final = 0.2 - -TABLE_DAILY_USER_SPEND: Final = "litellm_dailyuserspend" -TABLE_DAILY_TEAM_SPEND: Final = "litellm_dailyteamspend" -TABLE_DAILY_TAG_SPEND: Final = "litellm_dailytagspend" - -ENTITY_FIELD_USER: Final = "user_id" -ENTITY_FIELD_TEAM: Final = "team_id" -ENTITY_FIELD_TAG: Final = "tag" - -PAGINATED_PAGE_SIZE: Final = 200 -MAX_CHAT_MESSAGES: Final = 20 -TOP_N_MODELS: Final = 15 -TOP_N_PROVIDERS: Final = 10 -TOP_N_KEYS: Final = 10 - -# --------------------------------------------------------------------------- -# Types -# --------------------------------------------------------------------------- - - -class SSEStatusEvent(TypedDict): - type: Literal["status"] - message: str - - -class SSEToolCallEvent(TypedDict, total=False): - type: Literal["tool_call"] - tool_name: str - tool_label: str - arguments: dict[str, str] - status: Literal["running", "complete", "error"] - error: str - - -class SSEChunkEvent(TypedDict): - type: Literal["chunk"] - content: str - - -class SSEDoneEvent(TypedDict): - type: Literal["done"] - - -class SSEErrorEvent(TypedDict): - type: Literal["error"] - message: str - - -SSEEvent = SSEStatusEvent | SSEToolCallEvent | SSEChunkEvent | SSEDoneEvent | SSEErrorEvent - - -class _EntityEntry(TypedDict, total=False): - metrics: ReadOnly[Mapping[str, float]] - metadata: ReadOnly[Mapping[str, str]] - - -class _DayDump(TypedDict, total=False): - breakdown: ReadOnly[Mapping[str, Mapping[str, _EntityEntry]]] - - -class _EntityTotal(NamedTuple): - """Running per-entity totals accumulated while summarising a usage dump.""" - - alias: str - spend: float - requests: float - tokens: float - - -class _UsageDump(Protocol): - @overload - def get(self, key: Literal["metadata"], default: Mapping[str, float], /) -> Mapping[str, float]: ... - @overload - def get(self, key: Literal["results"], default: Sequence[_DayDump], /) -> Sequence[_DayDump]: ... - - -class _ToolFunctionDef(TypedDict): - name: ReadOnly[str] - description: ReadOnly[str] - parameters: ReadOnly[Mapping[str, object]] - - -class _ToolDef(TypedDict): - type: ReadOnly[str] - function: ReadOnly[_ToolFunctionDef] - - -class ToolHandler(TypedDict): - fetch: Callable[..., Awaitable[_UsageDump]] - summarise: Callable[[_UsageDump], str] - label: str - - -# --------------------------------------------------------------------------- -# Tool definitions (OpenAI function-calling schema) -# --------------------------------------------------------------------------- - -_DATE_PARAMS: Final = { - "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, - "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, -} - -_TOOL_USAGE: Final[_ToolDef] = { - "type": "function", - "function": { - "name": "get_usage_data", - "description": ( - "Fetch aggregated global usage/spend data. Returns daily spend, " - "token counts, request counts, and breakdowns by model, provider, " - "and API key. Use for overall spend, top models, top providers." - ), - "parameters": { - "type": "object", - "properties": { - **_DATE_PARAMS, - "user_id": { - "type": "string", - "description": "Optional user ID filter. Omit for global view.", - }, - }, - "required": ["start_date", "end_date"], - }, - }, -} - -_TOOL_TEAM: Final[_ToolDef] = { - "type": "function", - "function": { - "name": "get_team_usage_data", - "description": ( - "Fetch usage/spend data broken down by team. Use for questions " - "like 'which team spends the most' or 'show me team X usage'." - ), - "parameters": { - "type": "object", - "properties": { - **_DATE_PARAMS, - "team_ids": { - "type": "string", - "description": "Optional comma-separated team IDs. Omit for all teams.", - }, - }, - "required": ["start_date", "end_date"], - }, - }, -} - -_TOOL_TAG: Final[_ToolDef] = { - "type": "function", - "function": { - "name": "get_tag_usage_data", - "description": ( - "Fetch usage/spend data broken down by tag. Tags are labels " - "attached to requests (features, environments, credentials)." - ), - "parameters": { - "type": "object", - "properties": { - **_DATE_PARAMS, - "tags": { - "type": "string", - "description": "Optional comma-separated tag names. Omit for all tags.", - }, - }, - "required": ["start_date", "end_date"], - }, - }, -} - -TOOLS_BASE: Final = [_TOOL_USAGE] -TOOLS_ADMIN: Final = [_TOOL_USAGE, _TOOL_TEAM, _TOOL_TAG] - - -def get_tools_for_role(is_admin: bool) -> list[_ToolDef]: - """Return the tool list appropriate for the user's role.""" - return TOOLS_ADMIN if is_admin else TOOLS_BASE - - -_SYSTEM_PROMPT_BASE: Final = ( - "You are an AI assistant embedded in the LiteLLM Usage dashboard. " - "You help users understand their LLM API spend and usage data.\n\n" - "ALWAYS call the appropriate tool(s) first to fetch data before answering. " - "You may call multiple tools if the question spans different dimensions.\n\n" - "Guidelines:\n" - "- Be concise and specific. Use exact numbers from the data.\n" - "- Format costs as dollar amounts (e.g. $12.34).\n" - "- When comparing entities, show a ranked list.\n" - "- If data is empty or no results found, say so clearly.\n" - "- Do not hallucinate data — only use what the tools return.\n" - "- Today's date will be provided below. Use it to interpret relative dates " - "like 'this week', 'this month', 'last 7 days', etc." -) - -_TOOL_DESCRIPTIONS_ADMIN: Final = ( - "You have access to these tools:\n" - "- `get_usage_data`: Global/user-level usage (spend, models, providers, API keys)\n" - "- `get_team_usage_data`: Team-level usage breakdown\n" - "- `get_tag_usage_data`: Tag-level usage breakdown\n\n" -) - -_TOOL_DESCRIPTIONS_BASE: Final = ( - "You have access to this tool:\n- `get_usage_data`: Your usage data (spend, models, providers, API keys)\n\n" -) - - -def _build_system_prompt(is_admin: bool) -> str: - """Build role-appropriate system prompt with today's date.""" - tool_desc: Final = _TOOL_DESCRIPTIONS_ADMIN if is_admin else _TOOL_DESCRIPTIONS_BASE - return f"{_SYSTEM_PROMPT_BASE}\n\n{tool_desc}Today's date: {date.today().isoformat()}" - - -# keep a public reference for test assertions -SYSTEM_PROMPT: Final = _SYSTEM_PROMPT_BASE - -# --------------------------------------------------------------------------- -# Data fetchers -# --------------------------------------------------------------------------- - - -def _parse_csv_ids(raw: str | None) -> list[str] | None: - if not raw: - return None - return [t.strip() for t in raw.split(",") if t.strip()] - - -async def _query_activity( - table_name: str, - entity_id_field: str, - entity_id: str | list[str] | None, - start_date: str, - end_date: str, - *, - use_aggregated: bool = False, -) -> SpendAnalyticsPaginatedResponse: - """Shared helper that calls the daily activity query layer.""" - from litellm.proxy.management_endpoints.common_daily_activity import ( - daily_activity_repository, - daily_activity_scope, - get_daily_activity, - get_daily_activity_aggregated, - ) - from litellm.proxy.proxy_server import prisma_client - - if use_aggregated: - if prisma_client is None: - raise HTTPException( - status_code=500, - detail={"error": CommonProxyErrors.db_not_connected_error.value}, - ) - repository: Final = daily_activity_repository(prisma_client) - scope: Final = daily_activity_scope( - table_name, - entity_id_field, - entity_id, - None, - None, - start_date, - end_date, - None, - None, - ) - return await get_daily_activity_aggregated( - repository, - scope, - ) - return await get_daily_activity( - prisma_client=prisma_client, - table_name=table_name, - entity_id_field=entity_id_field, - entity_id=entity_id, - entity_metadata_field=None, - start_date=start_date, - end_date=end_date, - model=None, - api_key=None, - page=1, - page_size=PAGINATED_PAGE_SIZE, - ) - - -async def _fetch_usage_data(start_date: str, end_date: str, user_id: str | None = None) -> _UsageDump: - resp: Final = await _query_activity( - TABLE_DAILY_USER_SPEND, - ENTITY_FIELD_USER, - user_id, - start_date, - end_date, - use_aggregated=True, - ) - return resp.model_dump(mode="json") - - -async def _fetch_team_usage_data(start_date: str, end_date: str, team_ids: str | None = None) -> _UsageDump: - resp: Final = await _query_activity( - TABLE_DAILY_TEAM_SPEND, - ENTITY_FIELD_TEAM, - _parse_csv_ids(team_ids), - start_date, - end_date, - ) - return resp.model_dump(mode="json") - - -async def _fetch_tag_usage_data(start_date: str, end_date: str, tags: str | None = None) -> _UsageDump: - resp: Final = await _query_activity( - TABLE_DAILY_TAG_SPEND, - ENTITY_FIELD_TAG, - _parse_csv_ids(tags), - start_date, - end_date, - ) - return resp.model_dump(mode="json") - - -# --------------------------------------------------------------------------- -# Summarisers — convert raw JSON to concise text the LLM can reason over -# --------------------------------------------------------------------------- - - -def _accumulate_breakdown( - results: Sequence[_DayDump], dimension: str, fields: Sequence[str] -) -> dict[str, dict[str, float]]: - """Aggregate a single breakdown dimension across days.""" - totals: Final[dict[str, dict[str, float]]] = {} - for day in results: - for key, entry in day.get("breakdown", {}).get(dimension, {}).items(): - if key not in totals: - totals[key] = {f: 0.0 for f in fields} - m = entry.get("metrics", {}) - for f in fields: - totals[key][f] += m.get(f, 0) - return totals - - -def _ranked_lines( - totals: dict[str, dict[str, float]], - fmt: Callable[[str, dict[str, float]], str], - limit: int, -) -> list[str]: - """Sort by spend descending, format each entry, and truncate.""" - return [fmt(name, vals) for name, vals in sorted(totals.items(), key=lambda x: -x[1].get("spend", 0))[:limit]] - - -def _summarise_usage_data(data: _UsageDump) -> str: - meta: Final = data.get("metadata", {}) - results: Final = data.get("results", []) - - header: Final = ( - f"Total Spend: ${meta.get('total_spend', 0):.4f}\n" - f"Total Requests: {meta.get('total_api_requests', 0)}\n" - f"Successful: {meta.get('total_successful_requests', 0)} | " - f"Failed: {meta.get('total_failed_requests', 0)}\n" - f"Total Tokens: {meta.get('total_tokens', 0)}" - ) - - models: Final = _accumulate_breakdown(results, "models", ["spend", "api_requests", "total_tokens"]) - providers: Final = _accumulate_breakdown(results, "providers", ["spend", "api_requests"]) - - model_lines: Final = _ranked_lines( - models, - lambda n, d: f" - {n}: ${d['spend']:.4f} ({int(d['api_requests'])} reqs, {int(d['total_tokens'])} tokens)", - TOP_N_MODELS, - ) - provider_lines: Final = _ranked_lines( - providers, - lambda n, d: f" - {n}: ${d['spend']:.4f} ({int(d['api_requests'])} reqs)", - TOP_N_PROVIDERS, - ) - - sections = [header, ""] - sections += ["Top Models by Spend:"] + (model_lines or [" (no data)"]) + [""] - sections += ["Top Providers by Spend:"] + (provider_lines or [" (no data)"]) - return "\n".join(sections) - - -def _summarise_entity_data(data: _UsageDump, entity_label: str) -> str: - """Summarise team/tag entity usage data.""" - results: Final = data.get("results", []) - if not results: - return f"No {entity_label} usage data found for the given date range." - - totals: Final[dict[str, _EntityTotal]] = {} - for day in results: - for eid, entry in day.get("breakdown", {}).get("entities", {}).items(): - previous = totals.get(eid) - m = entry.get("metrics", {}) - totals[eid] = _EntityTotal( - alias=previous.alias if previous is not None else entry.get("metadata", {}).get("alias", eid), - spend=(previous.spend if previous is not None else 0.0) + m.get("spend", 0), - requests=(previous.requests if previous is not None else 0) + m.get("api_requests", 0), - tokens=(previous.tokens if previous is not None else 0) + m.get("total_tokens", 0), - ) - - lines: Final = [f"{entity_label} Usage ({len(totals)} {entity_label.lower()}s):", ""] - for eid, d in sorted(totals.items(), key=lambda x: -x[1].spend): - label = d.alias if d.alias != eid else eid - lines.append(f"- {label} (ID: {eid}): ${d.spend:.4f} | {int(d.requests)} reqs | {int(d.tokens)} tokens") - return "\n".join(lines) - - -# --------------------------------------------------------------------------- -# Tool dispatch registry -# --------------------------------------------------------------------------- - -TOOL_HANDLERS: Final[dict[str, ToolHandler]] = { - "get_usage_data": ToolHandler( - fetch=_fetch_usage_data, - summarise=_summarise_usage_data, - label="global usage data", - ), - "get_team_usage_data": ToolHandler( - fetch=_fetch_team_usage_data, - summarise=lambda data: _summarise_entity_data(data, "Team"), - label="team usage data", - ), - "get_tag_usage_data": ToolHandler( - fetch=_fetch_tag_usage_data, - summarise=lambda data: _summarise_entity_data(data, "Tag"), - label="tag usage data", - ), -} - - -# --------------------------------------------------------------------------- -# SSE streaming -# --------------------------------------------------------------------------- - - -def _sse(event: SSEEvent) -> str: - return f"data: {json.dumps(event)}\n\n" - - -def _resolve_fetch_kwargs( - fn_name: str, - fn_args: Mapping[str, str], - user_id: str | None, - is_admin: bool, -) -> dict[str, str]: - """Build keyword arguments for a tool's fetch function.""" - start_date: Final = fn_args.get("start_date", "") - end_date: Final = fn_args.get("end_date", "") - if not start_date or not end_date: - raise ValueError("Missing required start_date or end_date from tool arguments") - kwargs: Final[dict[str, str]] = {"start_date": start_date, "end_date": end_date} - if fn_name == "get_usage_data": - if not is_admin: - if user_id is None: - # Defense-in-depth: the endpoint guard in usage_endpoints/endpoints.py - # should have already rejected this. If we ever reach here it means - # a future caller invoked the helper without scoping — fail loudly - # rather than issuing an unfiltered global query. - raise ValueError( - "Non-admin caller has user_id=None; refusing to issue an " - "unscoped query. Endpoint-level guard missing." - ) - kwargs["user_id"] = user_id - elif fn_args.get("user_id"): - kwargs["user_id"] = fn_args["user_id"] - elif fn_name == "get_team_usage_data" and fn_args.get("team_ids"): - kwargs["team_ids"] = fn_args["team_ids"] - elif fn_name == "get_tag_usage_data" and fn_args.get("tags"): - kwargs["tags"] = fn_args["tags"] - return kwargs - - -async def _execute_tool_call( - handler: ToolHandler, - fn_name: str, - fn_args: Mapping[str, str], - user_id: str | None, - is_admin: bool, -) -> str: - """Run a single tool and return the summarised result text, or the reason the query - layer rejected its dates so the model can correct them.""" - kwargs: Final = _resolve_fetch_kwargs(fn_name, fn_args, user_id, is_admin) - try: - raw_data: Final = await handler["fetch"](**kwargs) - except HTTPException as e: - reason: Final = _invalid_date_reason(e) - if reason is None: - raise - return f"Invalid date range: {reason}" - return handler["summarise"](raw_data) - - -def _invalid_date_reason(error: HTTPException) -> str | None: - """The reason in the daily activity query layer's 400 for invalid or reversed dates.""" - detail: Final = cast(object, error.detail) # cast-ok: starlette types detail as str; the query layer passes a dict - match detail: - case {"error": str() as reason} if error.status_code == 400: - return reason - case _: - return None - - -async def _process_tool_call( - tc: ChatCompletionMessageToolCall, - chat_messages: list[Mapping[str, object]], - user_id: str | None, - is_admin: bool, -) -> AsyncIterator[str]: - """Execute a single tool call, yielding SSE events for status.""" - fn_name: Final = tc.function.name - fn_args: Final[Mapping[str, str]] = json.loads(tc.function.arguments) - - allowed_names: Final = {t["function"]["name"] for t in get_tools_for_role(is_admin)} - handler: Final = TOOL_HANDLERS.get(fn_name) if fn_name is not None else None - - if fn_name is None or fn_name not in allowed_names or not handler: - chat_messages.append( - { - "role": "tool", - "tool_call_id": tc.id, - "content": f"Tool not available: {fn_name}", - } - ) - return - - tool_event_base: Final = { - "type": "tool_call", - "tool_name": fn_name, - "tool_label": handler["label"], - "arguments": fn_args, - } - yield _sse(cast(SSEToolCallEvent, {**tool_event_base, "status": "running"})) - - try: - tool_result = await _execute_tool_call(handler, fn_name, fn_args, user_id, is_admin) - yield _sse(cast(SSEToolCallEvent, {**tool_event_base, "status": "complete"})) - except Exception as e: - verbose_proxy_logger.error("Tool %s failed: %s", fn_name, e) - tool_result = f"Error fetching {handler['label']}. Please try again." - yield _sse(cast(SSEToolCallEvent, {**tool_event_base, "status": "error"})) - - chat_messages.append({"role": "tool", "tool_call_id": tc.id, "content": tool_result}) - - -async def _stream_final_response(model: str, chat_messages: list[Mapping[str, object]]) -> AsyncIterator[str]: - """Stream the final LLM response after tool results are appended.""" - yield _sse({"type": "status", "message": "Analyzing results..."}) - - response: Final = await litellm.acompletion( - model=model, - messages=chat_messages, - stream=True, - temperature=USAGE_AI_TEMPERATURE, - ) - async for chunk in response: - delta = chunk.choices[0].delta.content - if delta: - yield _sse({"type": "chunk", "content": delta}) - - -async def stream_usage_ai_chat( - messages: list[dict[str, str]], - model: str | None = None, - user_id: str | None = None, - is_admin: bool = False, -) -> AsyncGenerator[str, None]: - """Stream SSE events: status → tool_call → chunk → done.""" - resolved_model: Final = (model or "").strip() or DEFAULT_COMPETITOR_DISCOVERY_MODEL - truncated: Final = messages[-MAX_CHAT_MESSAGES:] if len(messages) > MAX_CHAT_MESSAGES else messages - chat_messages: Final[list[Mapping[str, object]]] = [ - {"role": "system", "content": _build_system_prompt(is_admin)}, - *truncated, - ] - - try: - yield _sse({"type": "status", "message": "Thinking..."}) - tools: Final = get_tools_for_role(is_admin) - response: Final = await litellm.acompletion( - model=resolved_model, - messages=chat_messages, - tools=tools, - temperature=USAGE_AI_TEMPERATURE, - ) - choice: Final = response.choices[0] - - if not choice.message.tool_calls: - if choice.message.content: - yield _sse({"type": "chunk", "content": choice.message.content}) - yield _sse({"type": "done"}) - return - - chat_messages.append(choice.message.model_dump()) - for tc in choice.message.tool_calls: - async for event in _process_tool_call(tc, chat_messages, user_id, is_admin): - yield event - async for event in _stream_final_response(resolved_model, chat_messages): - yield event - yield _sse({"type": "done"}) - - except Exception as e: - verbose_proxy_logger.error("AI usage chat failed: %s", e) - yield _sse( - { - "type": "error", - "message": "An internal error occurred. Please try again.", - } - ) diff --git a/litellm/proxy/management_endpoints/usage_endpoints/endpoints.py b/litellm/proxy/management_endpoints/usage_endpoints/endpoints.py deleted file mode 100644 index cff5bef05a0..00000000000 --- a/litellm/proxy/management_endpoints/usage_endpoints/endpoints.py +++ /dev/null @@ -1,77 +0,0 @@ -""" -USAGE AI CHAT ENDPOINTS - -/usage/ai/chat - Stream AI chat responses about usage data -""" - -from typing import Final, Literal - -from fastapi import APIRouter, Depends, Request -from fastapi.responses import StreamingResponse -from pydantic import Field - -import litellm -from litellm.proxy._types import UserAPIKeyAuth -from litellm.proxy.auth.user_api_key_auth import user_api_key_auth -from litellm.proxy.common_utils.sse_keepalive import ( - SSE_COMMENT_PING, - wrap_sse_stream_with_keepalive_pings, -) -from litellm.types.llms.base import LiteLLMBaseModel - -router: Final = APIRouter() - - -class ChatMessage(LiteLLMBaseModel): - role: Literal["user", "assistant"] - content: str - - -class UsageAIChatRequest(LiteLLMBaseModel): - messages: list[ChatMessage] = Field(..., description="Chat messages (user/assistant history)") - model: str | None = Field(default=None, description="Model to use for AI chat") - - -@router.post( - "/usage/ai/chat", - tags=["Budget & Spend Tracking"], - dependencies=[Depends(user_api_key_auth)], -) -async def usage_ai_chat( - data: UsageAIChatRequest, - request: Request, - user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), -): - """ - AI chat about usage data. Streams SSE events with the AI response. - The AI agent has access to tools that query aggregated daily activity data. - """ - from litellm.proxy.management_endpoints.common_utils import ( - require_caller_user_id_for_non_admin, - user_api_key_has_admin_view, - ) - from litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat import ( - stream_usage_ai_chat, - ) - - is_admin: Final = user_api_key_has_admin_view(user_api_key_dict) - if is_admin: - user_id = user_api_key_dict.user_id - else: - user_id = require_caller_user_id_for_non_admin(user_api_key_dict) - messages: Final = [{"role": m.role, "content": m.content} for m in data.messages] - - return StreamingResponse( - wrap_sse_stream_with_keepalive_pings( - stream_usage_ai_chat( - messages=messages, - model=data.model, - user_id=user_id, - is_admin=is_admin, - ), - ping_interval_seconds=litellm.sse_keepalive_ping_interval_seconds, - ping_chunk=SSE_COMMENT_PING, - ), - media_type="text/event-stream", - headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}, - ) diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index f632317d9a8..ade719ae0ed 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -12210,7 +12210,7 @@ async def _deployment_hidden_by_listing_callbacks(deployment: Deployment, user_a async def model_list( request: Request = None, # pyright: ignore[reportArgumentType] # FastAPI always injects the Request; the None default only serves direct in-process callers user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), - return_wildcard_routes: bool | None = False, + return_wildcard_routes: bool | None = None, team_id: str | None = None, include_model_access_groups: bool | None = False, only_model_access_groups: bool | None = False, @@ -12226,6 +12226,9 @@ async def model_list( This is just for compatibility with openai projects like aider. Query Parameters: + - return_wildcard_routes: When true, also list wildcard routes such as `openai/*`. + Defaults to `general_settings.return_wildcard_routes`, and an explicit + value on the request wins over it - client_version: Sent by Codex CLI (`?client_version=0.159.3`) when it fetches a provider's model catalog. When present, the response is Codex's own catalog shape (`{"models": [...]}`) built from the same listing, with @@ -12254,6 +12257,9 @@ async def model_list( global llm_model_list, general_settings, llm_router, prisma_client, user_api_key_cache, proxy_logging_obj settings: Final = cast(dict[str, object], general_settings) # any-ok: legacy settings + include_wildcard_routes: Final = ( + return_wildcard_routes if return_wildcard_routes is not None else settings.get("return_wildcard_routes") is True + ) from litellm.llms.anthropic.common_utils import ( create_anthropic_model_list_response, @@ -12343,7 +12349,7 @@ async def model_list( proxy_model_list=proxy_model_list, user_model=None, infer_model_from_keys=False, - return_wildcard_routes=return_wildcard_routes or False, + return_wildcard_routes=include_wildcard_routes, llm_router=llm_router, model_access_groups=model_access_groups, include_model_access_groups=include_model_access_groups or False, @@ -12411,7 +12417,7 @@ async def model_list( team_id=team_id, include_model_access_groups=include_model_access_groups or False, only_model_access_groups=only_model_access_groups or False, - return_wildcard_routes=return_wildcard_routes or False, + return_wildcard_routes=include_wildcard_routes, user_api_key_cache=user_api_key_cache, ) @@ -19657,6 +19663,7 @@ _GENERAL_SETTINGS_CONFIG_LIST_FIELD_TYPES: Final[Mapping[str, str]] = MappingPro "proxy_config_reload_interval_seconds": "Integer", "pass_through_endpoints": "PydanticModel", "store_model_in_db": "Boolean", + "return_wildcard_routes": "Boolean", "store_prompts_in_spend_logs": "Boolean", "disable_requester_ip_address_logging": "Boolean", "disable_fallbacks_on_per_model_rate_limits": "Boolean", diff --git a/litellm/proxy/ui_crud_endpoints/latest_release_endpoints.py b/litellm/proxy/ui_crud_endpoints/latest_release_endpoints.py index 7411f1b4947..14d75633100 100644 --- a/litellm/proxy/ui_crud_endpoints/latest_release_endpoints.py +++ b/litellm/proxy/ui_crud_endpoints/latest_release_endpoints.py @@ -1,5 +1,7 @@ import asyncio +import os import re +import xml.etree.ElementTree as ET from collections import Counter from collections.abc import Awaitable, Mapping from dataclasses import dataclass @@ -17,7 +19,8 @@ from litellm.types.llms.base import LiteLLMBaseModel router: Final = APIRouter() -LATEST_RELEASE_URL: Final = "https://api.github.com/repos/BerriAI/litellm/releases/latest" +CHANGELOG_URL: Final = "https://docs.litellm.ai/release_notes/" +CHANGELOG_FEED_URL: Final = f"{CHANGELOG_URL}rss.xml" RELEASE_BY_TAG_URL: Final = "https://api.github.com/repos/BerriAI/litellm/releases/tags/{tag}" LATEST_RELEASE_FETCH_TIMEOUT_SECONDS: Final = 5 LATEST_RELEASE_CACHE_TTL_SECONDS: Final = 60 * 60 @@ -26,7 +29,7 @@ LATEST_RELEASE_CACHE_KEY: Final = "latest_release_info" _RELEASE_BULLET_PATTERN: Final = re.compile(r"^\*\s+(?:([A-Za-z]+)(?:\([^)]*\))?!?:\s)?\S") _NEW_CONTRIBUTOR_PATTERN: Final = re.compile(r"^\*\s+@\S+ made their first contribution\b") -_STABLE_TAG_PATTERN: Final = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)$") +_CHANGELOG_PAGE_PATTERN: Final = re.compile(rf"{re.escape(CHANGELOG_URL)}v(\d+)\.(\d+)\.(\d+)/") _Bucket: TypeAlias = Literal["new_features", "bug_fixes", "other_updates"] _PREFIX_BUCKETS: Final[Mapping[str, _Bucket]] = MappingProxyType({"feat": "new_features", "fix": "bug_fixes"}) @@ -45,6 +48,16 @@ class LatestReleaseUnavailable: reason: str +@dataclass(frozen=True, slots=True) +class ChangelogEntry: + version: tuple[int, int, int] + url: str + + @property + def tag(self) -> str: + return "v" + ".".join(str(part) for part in self.version) + + class _GitHubRelease(LiteLLMBaseModel): tag_name: str html_url: str @@ -76,6 +89,10 @@ def _default_fetch_lock() -> asyncio.Lock: return _latest_release_fetch_lock +def _default_release_check_enabled() -> bool: + return os.getenv("LITELLM_DISABLE_LATEST_RELEASE_CHECK", "").strip().lower() != "true" + + def _bucket_for(line: str) -> _Bucket | None: if _NEW_CONTRIBUTOR_PATTERN.match(line) is not None: return None @@ -91,9 +108,18 @@ def count_release_bullets(body: str) -> Mapping[_Bucket, int]: return MappingProxyType(Counter(bucket for line in body.splitlines() if (bucket := _bucket_for(line)) is not None)) -def _stable_version(tag_name: str) -> tuple[int, int, int] | None: - match: Final = _STABLE_TAG_PATTERN.match(tag_name) - return None if match is None else (int(match.group(1)), int(match.group(2)), int(match.group(3))) +def _changelog_entry(link: str) -> ChangelogEntry | None: + match: Final = _CHANGELOG_PAGE_PATTERN.match(link) + if match is None: + return None + return ChangelogEntry(version=(int(match.group(1)), int(match.group(2)), int(match.group(3))), url=link) + + +def latest_changelog_entry(feed: bytes) -> ChangelogEntry | None: + """The highest stable release with a page in the changelog feed. Release candidate pages don't count.""" + links: Final = (link.text or "" for link in ET.fromstring(feed).iterfind("channel/item/link")) + entries: Final = (entry for link in links if (entry := _changelog_entry(link)) is not None) + return max(entries, key=lambda entry: entry.version, default=None) def earlier_patch_tags(version: tuple[int, int, int]) -> tuple[str, ...]: @@ -102,7 +128,9 @@ def earlier_patch_tags(version: tuple[int, int, int]) -> tuple[str, ...]: return tuple(f"v{major}.{minor}.{earlier}" for earlier in range(patch)) -def summarize_release_line(latest: _GitHubRelease, earlier: tuple[_GitHubRelease, ...]) -> LatestReleaseInfo: +def summarize_release_line( + entry: ChangelogEntry, latest: _GitHubRelease, earlier: tuple[_GitHubRelease, ...] +) -> LatestReleaseInfo: """A patch release's notes only list its backports, so count the whole minor line it belongs to.""" counts: Final = sum( (Counter[_Bucket](count_release_bullets(release.body or "")) for release in (latest, *earlier)), @@ -113,7 +141,7 @@ def summarize_release_line(latest: _GitHubRelease, earlier: tuple[_GitHubRelease new_features=counts.get("new_features", 0), bug_fixes=counts.get("bug_fixes", 0), other_updates=counts.get("other_updates", 0), - release_url=latest.html_url, + release_url=entry.url, ) @@ -137,25 +165,38 @@ async def _fetch_earlier_release(client: _AsyncGetClient, tag: str) -> _GitHubRe return release +async def _fetch_changelog_entry(client: _AsyncGetClient) -> ChangelogEntry | LatestReleaseUnavailable: + response: Final = await client.get(CHANGELOG_FEED_URL, timeout=LATEST_RELEASE_FETCH_TIMEOUT_SECONDS) + if response.status_code != 200: + return LatestReleaseUnavailable(reason=f"Changelog feed responded with status {response.status_code}") + try: + entry: Final = latest_changelog_entry(response.content) + except ET.ParseError as e: + return LatestReleaseUnavailable(reason=f"Changelog feed was not valid XML: {e}") + return LatestReleaseUnavailable(reason="Changelog feed lists no stable release") if entry is None else entry + + async def fetch_latest_release(client: _AsyncGetClient) -> LatestReleaseInfo | LatestReleaseUnavailable: try: + entry: Final = await _fetch_changelog_entry(client) + if isinstance(entry, LatestReleaseUnavailable): + return entry latest: Final = parse_github_release( - await client.get(LATEST_RELEASE_URL, timeout=LATEST_RELEASE_FETCH_TIMEOUT_SECONDS) + await client.get(RELEASE_BY_TAG_URL.format(tag=entry.tag), timeout=LATEST_RELEASE_FETCH_TIMEOUT_SECONDS) ) if isinstance(latest, LatestReleaseUnavailable): return latest - version: Final = _stable_version(latest.tag_name) - if version is None: - return summarize_release_line(latest, ()) earlier: Final = await asyncio.gather( - *(_fetch_earlier_release(client, tag) for tag in earlier_patch_tags(version)) + *(_fetch_earlier_release(client, tag) for tag in earlier_patch_tags(entry.version)) ) except httpx.HTTPError as e: return LatestReleaseUnavailable(reason=f"{type(e).__name__}: {e}") unavailable: Final = next((release for release in earlier if isinstance(release, LatestReleaseUnavailable)), None) if unavailable is not None: return unavailable - return summarize_release_line(latest, tuple(release for release in earlier if isinstance(release, _GitHubRelease))) + return summarize_release_line( + entry, latest, tuple(release for release in earlier if isinstance(release, _GitHubRelease)) + ) async def get_latest_release_info( @@ -188,12 +229,16 @@ async def latest_release_info( client: Annotated[_AsyncGetClient, Depends(_default_client)], cache: Annotated[InMemoryCache, Depends(_default_cache)], fetch_lock: Annotated[asyncio.Lock, Depends(_default_fetch_lock)], + release_check_enabled: Annotated[bool, Depends(_default_release_check_enabled)], ) -> LatestReleaseInfo | None: """ - Latest stable LiteLLM GitHub release with the PR count of its whole minor line (e.g. v1.105.0 + v1.105.1) - split into new features, bug fixes and other updates. - Returns null when GitHub can't be reached so the dashboard upgrade banner simply doesn't render. + Newest stable release on the LiteLLM changelog, linked to its changelog page, with the PR count of its whole + minor line (e.g. v1.105.0 + v1.105.1) from GitHub split into new features, bug fixes and other updates. + Returns null when the changelog or GitHub can't be reached so the dashboard upgrade banner simply doesn't render. + Set LITELLM_DISABLE_LATEST_RELEASE_CHECK=true to return null without making any outbound request. """ + if not release_check_enabled: + return None result: Final = await get_latest_release_info(client=client, cache=cache, fetch_lock=fetch_lock) if isinstance(result, LatestReleaseUnavailable): verbose_proxy_logger.warning("LiteLLM: latest release info unavailable: %s", result.reason) diff --git a/litellm/text_completions/__init__.py b/litellm/text_completions/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/litellm/text_completions/streaming_iterator.py b/litellm/text_completions/streaming_iterator.py new file mode 100644 index 00000000000..ec1b96fd432 --- /dev/null +++ b/litellm/text_completions/streaming_iterator.py @@ -0,0 +1,88 @@ +from typing import Final + +from litellm.types.utils import Choices, ModelResponse, TextChoices, TextCompletionResponse + + +class TextCompletionStreamWrapper: + def __init__( + self, + completion_stream, + model, + stream_options: dict | None = None, + custom_llm_provider: str | None = None, + ): + self.completion_stream = completion_stream + self.model = model + self.stream_options = stream_options + self.custom_llm_provider = custom_llm_provider + + def __iter__(self): + return self + + def __aiter__(self): + return self + + def convert_to_text_completion_object(self, chunk: ModelResponse): + try: + response: Final = TextCompletionResponse() + response["id"] = chunk.get("id", None) + response["object"] = "text_completion" + response["created"] = chunk.get("created", None) + response["model"] = chunk.get("model", None) + text_choices: Final = TextChoices() + if isinstance(chunk, Choices): # chunk should always be of type StreamingChoices + raise Exception + + if chunk["choices"]: + delta: Final = chunk["choices"][0]["delta"] + text_choices["text"] = delta["content"] + text_choices["reasoning_content"] = delta.get("reasoning_content") + text_choices["index"] = chunk["choices"][0]["index"] + text_choices["finish_reason"] = chunk["choices"][0]["finish_reason"] + response["choices"] = [text_choices] + else: + response["choices"] = [] + + # only pass usage when stream_options["include_usage"] is True + if self.stream_options and self.stream_options.get("include_usage", False) is True: + response.usage = chunk.get("usage", None) + else: + response.usage = None + + return response + except Exception as e: + raise Exception(f"Error occurred converting to text completion object - chunk: {chunk}; Error: {e}") + + def __next__(self): + # model_response = ModelResponse(stream=True, model=self.model) + TextCompletionResponse() + try: + for chunk in self.completion_stream: + if chunk == "None" or chunk is None: + raise Exception + processed_chunk = self.convert_to_text_completion_object(chunk=chunk) + return processed_chunk + raise StopIteration + except StopIteration: + raise StopIteration + except Exception as e: + from litellm.litellm_core_utils.exception_mapping_utils import exception_type + + raise exception_type( + model=self.model, + custom_llm_provider=self.custom_llm_provider or "", + original_exception=e, + completion_kwargs={}, + extra_kwargs={}, + ) + + async def __anext__(self): + try: + async for chunk in self.completion_stream: + if chunk == "None" or chunk is None: + raise Exception + processed_chunk = self.convert_to_text_completion_object(chunk=chunk) + return processed_chunk + raise StopIteration + except StopIteration: + raise StopAsyncIteration diff --git a/litellm/types/decisions.py b/litellm/types/decisions.py index a1d48f730c0..5ad6e45e6d2 100644 --- a/litellm/types/decisions.py +++ b/litellm/types/decisions.py @@ -73,7 +73,7 @@ DecisionQuestion: TypeAlias = Annotated[ DecisionQuestionMap: TypeAlias = Annotated[ Mapping[Annotated[str, Field(min_length=1)], DecisionQuestion], - Field(min_length=1, max_length=MAX_DECISION_QUESTIONS), + Field(min_length=1), ] diff --git a/litellm/types/interactions/README.md b/litellm/types/interactions/README.md index d890991d99d..45783d604db 100644 --- a/litellm/types/interactions/README.md +++ b/litellm/types/interactions/README.md @@ -9,16 +9,38 @@ https://ai.google.dev/static/api/interactions.openapi.json ### How to Regenerate -When the API spec changes, regenerate the types with: +The compliance tests in `tests/unit/interactions/test_openapi_compliance.py` read the snapshot at +`tests/unit/interactions/interactions.openapi.json`, so a PR never depends on Google's live spec. The scheduled +`interactions-spec-canary` workflow runs those tests against the live spec once a day (`--interactions-spec-url`), +files the issue "Interactions spec canary is red" on a red run and closes it once a run is green again. A red run +means the spec moved in a way these types no longer cover + +When the red run names one new status, the small fix is a hand edit adding that member to the enum the failing +schema's model carries, the way `queued` was added in #34135. When the spec moved further than that, refresh the +snapshot and regenerate the types from it: ```bash -uv tool run --from datamodel-code-generator datamodel-codegen \ - --url "https://ai.google.dev/static/api/interactions.openapi.json" \ +curl -fsSL https://ai.google.dev/static/api/interactions.openapi.json \ + -o tests/unit/interactions/interactions.openapi.json +uv tool run --from datamodel-code-generator==0.66.0 datamodel-codegen \ + --input tests/unit/interactions/interactions.openapi.json \ + --input-file-type openapi \ --output litellm/types/interactions/generated.py \ --output-model-type pydantic_v2.BaseModel \ - --target-python-version 3.9 + --target-python-version 3.10 \ + --base-class litellm.types.llms.base.LiteLLMBaseModel ``` +The pin is the same `datamodel-code-generator` version `scripts/generate_trace_types.py` uses. The generator names +inline enums by order of appearance (`Status`, `Status1`, `Status2`, ...), so a regeneration can rename them. The +compliance tests resolve each status enum through its model's `status` field, but +`tests/unit/interactions/test_background_cost_polling.py` and +`tests/unit/proxy/hooks/test_proxy_track_cost_callback.py` import `Status1` by name and need the new name, and +`litellm/types/interactions/__init__.py` exports the interaction status enum as `InteractionStatus`, which has to +point at the enum the regenerated `Interaction.status` carries (a compliance test checks their members match). The +spec has grown a lot since the 2025-12-16 generation (agents, triggers, credentials, environments), so a +regeneration today is a review-sized change rather than a refresh + Then add the LiteLLM-specific types at the bottom of the generated file: - `InteractionsAPIResponse` - `InteractionsAPIStreamingResponse` diff --git a/litellm/utils.py b/litellm/utils.py index 7de7ce6188d..73057f140a8 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -218,6 +218,7 @@ def _get_cached_audio_utils(): return _audio_utils_module +from litellm.text_completions.streaming_iterator import TextCompletionStreamWrapper as _TextCompletionStreamWrapper from litellm.types.llms.openai import ( AllMessageValues, AllPromptValues, @@ -262,13 +263,17 @@ from litellm.types.utils import ( SearchProviders, SelectTokenizerResponse, StreamingChoices, - TextChoices, - TextCompletionResponse, TranscriptionResponse, Usage, credential_api_key_secret_reference, is_litellm_owned_kwarg, ) +from litellm.types.utils import ( + TextChoices as _TextChoices, +) +from litellm.types.utils import ( + TextCompletionResponse as _TextCompletionResponse, +) _CALL_TYPE_ENUM_MAP: Final[dict] = {ct.value: ct for ct in CallTypes} _BACKFILL_MODES: Final = frozenset({"chat", "responses"}) @@ -299,10 +304,14 @@ except (ImportError, AttributeError, TypeError): claude_json_str = json.dumps(json_data) import importlib.metadata from collections.abc import AsyncIterator, Callable, Collection, Iterable, Iterator, Mapping, Sequence -from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeVar, cast, runtime_checkable +from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeAlias, TypeVar, cast, runtime_checkable from typing_extensions import assert_never +TextChoices: TypeAlias = _TextChoices +TextCompletionResponse: TypeAlias = _TextCompletionResponse +TextCompletionStreamWrapper: TypeAlias = _TextCompletionStreamWrapper + from litellm import utils as litellm_utils # These are lazy loaded via __getattr__ @@ -340,7 +349,8 @@ if TYPE_CHECKING: # Type stubs for lazy-loaded functions to help mypy understand their types # These imports allow mypy to understand the types when these are accessed via __getattr__ - from litellm.litellm_core_utils.exception_mapping_utils import exception_type + exception_type: Callable[..., Exception] + from litellm.litellm_core_utils.get_litellm_params import ( get_base_model_from_litellm_call_metadata, get_litellm_params, @@ -7945,88 +7955,6 @@ def register_prompt_template( return litellm.custom_prompt_dict -class TextCompletionStreamWrapper: - def __init__( - self, - completion_stream, - model, - stream_options: dict | None = None, - custom_llm_provider: str | None = None, - ): - self.completion_stream = completion_stream - self.model = model - self.stream_options = stream_options - self.custom_llm_provider = custom_llm_provider - - def __iter__(self): - return self - - def __aiter__(self): - return self - - def convert_to_text_completion_object(self, chunk: ModelResponse): - try: - response: Final = TextCompletionResponse() - response["id"] = chunk.get("id", None) - response["object"] = "text_completion" - response["created"] = chunk.get("created", None) - response["model"] = chunk.get("model", None) - text_choices: Final = TextChoices() - if isinstance(chunk, Choices): # chunk should always be of type StreamingChoices - raise Exception - - if chunk["choices"]: - delta: Final = chunk["choices"][0]["delta"] - text_choices["text"] = delta["content"] - text_choices["reasoning_content"] = delta.get("reasoning_content") - text_choices["index"] = chunk["choices"][0]["index"] - text_choices["finish_reason"] = chunk["choices"][0]["finish_reason"] - response["choices"] = [text_choices] - else: - response["choices"] = [] - - # only pass usage when stream_options["include_usage"] is True - if self.stream_options and self.stream_options.get("include_usage", False) is True: - response["usage"] = chunk.get("usage", None) - - return response - except Exception as e: - raise Exception(f"Error occurred converting to text completion object - chunk: {chunk}; Error: {e}") - - def __next__(self): - # model_response = ModelResponse(stream=True, model=self.model) - TextCompletionResponse() - try: - for chunk in self.completion_stream: - if chunk == "None" or chunk is None: - raise Exception - processed_chunk = self.convert_to_text_completion_object(chunk=chunk) - return processed_chunk - raise StopIteration - except StopIteration: - raise StopIteration - except Exception as e: - exception_type: Final = litellm_utils.exception_type - raise exception_type( - model=self.model, - custom_llm_provider=self.custom_llm_provider or "", - original_exception=e, - completion_kwargs={}, - extra_kwargs={}, - ) - - async def __anext__(self): - try: - async for chunk in self.completion_stream: - if chunk == "None" or chunk is None: - raise Exception - processed_chunk = self.convert_to_text_completion_object(chunk=chunk) - return processed_chunk - raise StopIteration - except StopIteration: - raise StopAsyncIteration - - def mock_stream_usage_chunk(model_response: ModelResponseStream, model: str, prompt_tokens: int) -> ModelResponseStream: return ModelResponseStream( id=model_response.id, diff --git a/migrations/Dockerfile b/migrations/Dockerfile index 55f100d9e02..84ea67fcc5f 100644 --- a/migrations/Dockerfile +++ b/migrations/Dockerfile @@ -61,7 +61,7 @@ COPY --from=uvbin /uv /uvx /usr/local/bin/ # instead of nodeenv downloading one whose dynamic deps may not be in Wolfi # (e.g. Node 26.2.0 needs libatomic). Retry for transient apk.cgr.dev flakes. RUN for i in 1 2 3; do \ - apk add --no-cache bash gcc python-3.13 python-3.13-dev openssl openssl-dev libsndfile nodejs npm && break; \ + apk add --no-cache bash gcc python-3.13 python-3.13-dev openssl libssl3 openssl-dev libsndfile nodejs npm && break; \ [ $i = 3 ] && { echo "apk add failed after 3 retries" >&2; exit 1; }; \ sleep 5; \ done diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json index cb9bfa6ffe4..840576e8225 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -36861,17 +36861,17 @@ }, "gpt-6-luna": { "cache_creation_input_token_cost": 1.25e-07, - "cache_creation_input_token_cost_decisions": 1e-07, + "cache_creation_input_token_cost_decisions": 1.25e-07, "cache_creation_input_token_cost_above_272k_tokens": 2.5e-07, - "cache_creation_input_token_cost_above_272k_tokens_decisions": 2e-07, + "cache_creation_input_token_cost_above_272k_tokens_decisions": 2.5e-07, "cache_creation_input_token_cost_above_272k_tokens_flex": 1.25e-07, "cache_creation_input_token_cost_above_272k_tokens_priority": 5e-07, "cache_creation_input_token_cost_flex": 6.25e-08, "cache_creation_input_token_cost_priority": 2.5e-07, "cache_read_input_token_cost": 1e-08, - "cache_read_input_token_cost_decisions": 1e-07, + "cache_read_input_token_cost_decisions": 1e-08, "cache_read_input_token_cost_above_272k_tokens": 2e-08, - "cache_read_input_token_cost_above_272k_tokens_decisions": 2e-07, + "cache_read_input_token_cost_above_272k_tokens_decisions": 2e-08, "cache_read_input_token_cost_above_272k_tokens_flex": 1e-08, "cache_read_input_token_cost_above_272k_tokens_priority": 4e-08, "cache_read_input_token_cost_batches": 5e-09, @@ -73330,6 +73330,7 @@ ] }, "vertex_ai/veo-2.0-generate-001": { + "deprecation_date": "2026-06-30", "litellm_provider": "vertex_ai-video-models", "max_input_tokens": 1024, "max_tokens": 1024, diff --git a/pyproject.toml b/pyproject.toml index 3aefd911937..b43f0b254fd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,7 +35,7 @@ dependencies = [ "pydantic>=2.12.0,<3.0.0; python_version >= '3.14'", "pydantic-settings>=2.14.1,<3.0", "jsonschema>=4.0.0,<5.0", - "boto3>=1.43.1,<2.0", + "boto3>=1.43.117,<2.0", "certifi>=2026.10.19", "typing-extensions>=4.13.0,<5.0", ] @@ -73,7 +73,7 @@ proxy = [ "cryptography>=49.0.0,<51.0", "pynacl>=1.6.2,<2.0", "websockets>=15.0.1,<16.0", - "boto3>=1.43.1,<2.0", + "boto3>=1.43.117,<2.0", "azure-identity>=1.25.2,<2.0", "azure-storage-blob>=12.28.0,<13.0", "mcp>=2.3.0,<3", @@ -139,8 +139,8 @@ semantic-router = [ ] mlflow = ["mlflow>=3.11.1,<4.0"] grpc = [ - # Newest non-yanked release older than the 30-day cutoff. - "grpcio==1.78.0", + # First release whose bundled roots.pem drops the compromised eMudhra roots, ahead of the 30-day cutoff + "grpcio==1.84.1", ] stt-vertex-chirp = [ # Google Cloud Speech-to-Text v2 streaming (gRPC) for Chirp models on @@ -174,7 +174,7 @@ proxy-runtime = [ "google-cloud-speech>=2.40.0,<3.0", "google-genai>=1.37.0,<2.0", "anthropic[vertex]>=0.84.0,<1.0", - "grpcio==1.78.0", + "grpcio==1.84.1", "prometheus-client>=0.20.0,<1.0", "langfuse>=4.7,<5.0", "opentelemetry-api==1.33.1", @@ -371,7 +371,9 @@ default-groups = ["dev"] required-version = ">=0.10.9" exclude-newer = "3 days" # TODO: ryan, remove after 2026-10-23, once certifi 2026.10.19 (drops the compromised eMudhra root) clears the 3-day window -exclude-newer-package = { certifi = "2026-10-20T03:00:00Z" } +# TODO(shrey): remove after 2026-10-25, once grpcio 1.84.1 (drops the compromised eMudhra roots from roots.pem) clears the 3-day window +# TODO(shrey): remove after 2026-10-24, once boto3/botocore 1.43.117 (drops the compromised eMudhra roots from cacert.pem) clear the 3-day window +exclude-newer-package = { certifi = "2026-10-20T03:00:00Z", grpcio = "2026-10-22T15:00:00Z", boto3 = "2026-10-21T19:31:00Z", botocore = "2026-10-21T19:31:00Z" } [tool.uv.sources] litellm-proxy-extras = { workspace = true } diff --git a/tests/integration/compatibility/test_status_code_followups_usage_chat.py b/tests/integration/compatibility/test_status_code_followups_usage_chat.py deleted file mode 100644 index de9ec16cf30..00000000000 --- a/tests/integration/compatibility/test_status_code_followups_usage_chat.py +++ /dev/null @@ -1,125 +0,0 @@ -"""The /usage/ai/chat tools hand the model the reason the daily activity query rejected its dates, the same check -the daily activity routes answer 400 with, instead of a generic fetch error.""" - -from __future__ import annotations - -import json -import uuid -from collections.abc import Iterator -from dataclasses import dataclass -from typing import Final - -import pytest -from integration._support.client import JSON_OBJECT, Gateway, object_value -from integration._support.upstream import delete_scenario, register_scenario -from integration.compatibility._status_code_audit import Upstream, json_response, owned_gateway -from pydantic import JsonValue - -pytestmark: Final = pytest.mark.timeout(180) - -_TOOLS: Final = ("get_usage_data", "get_team_usage_data", "get_tag_usage_data") - - -@dataclass(frozen=True, slots=True) -class _UsageChat: - gateway: Gateway - identity: str - - -@pytest.fixture(scope="module") -def usage_chat(tmp_path_factory: pytest.TempPathFactory) -> Iterator[_UsageChat]: - """A proxy whose usage chat model (`openai/...`, called straight through litellm) is the scripted upstream.""" - identity: Final = f"audit-usage-chat-{uuid.uuid4().hex}" - handle: Final = register_scenario(identity, json_response({})) - try: - with owned_gateway( - tmp_path_factory.mktemp("audit-usage-chat"), - {"model_list": [], "router_settings": {"num_retries": 0}}, - environment={"OPENAI_API_BASE": handle.api_base(), "OPENAI_API_KEY": identity}, - ) as owned: - yield _UsageChat(owned, identity) - finally: - delete_scenario(handle) - - -def _tool_calls(start_date: str, end_date: str) -> dict[str, JsonValue]: - arguments: Final = json.dumps({"start_date": start_date, "end_date": end_date}) - return { - "id": "chatcmpl-usage", - "object": "chat.completion", - "created": 1, - "model": "gpt-4o-mini", - "choices": [ - { - "index": 0, - "message": { - "role": "assistant", - "content": None, - "tool_calls": [ - {"id": f"call-{tool}", "type": "function", "function": {"name": tool, "arguments": arguments}} - for tool in _TOOLS - ], - }, - "finish_reason": "tool_calls", - } - ], - "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}, - } - - -def _tool_results(usage_chat: _UsageChat, start_date: str, end_date: str) -> tuple[dict[str, str], tuple[str, ...]]: - """Runs one chat turn whose model calls every tool with these dates; returns the tool messages the follow-up - model call carried, keyed by tool, and the tool statuses the SSE stream reported.""" - register_scenario(usage_chat.identity, json_response(_tool_calls(start_date, end_date))) - Upstream(usage_chat.gateway.upstream_url).reset() - with usage_chat.gateway.client.stream( - "POST", - "/usage/ai/chat", - json={"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "How much did we spend?"}]}, - headers={"Authorization": f"Bearer {usage_chat.gateway.key}"}, - timeout=60, - ) as response: - assert response.status_code == 200 - events: Final = tuple( - object_value(JSON_OBJECT.validate_json(line.removeprefix("data: "))) - for line in response.iter_lines() - if line.startswith("data: ") - ) - calls: Final = Upstream(usage_chat.gateway.upstream_url).calls(usage_chat.identity) - assert len(calls) == 2, calls - messages: Final = object_value(calls[1]["body"]).get("messages") - assert isinstance(messages, list), calls[1] - tool_messages: Final = { - str(message["tool_call_id"]).removeprefix("call-"): str(message["content"]) - for message in messages - if isinstance(message, dict) and message.get("role") == "tool" - } - statuses: Final = tuple(str(event.get("status")) for event in events if event.get("type") == "tool_call") - return tool_messages, statuses - - -_REVERSED: Final = "Invalid date range: end_date must be on or after start_date" -_NOT_CANONICAL: Final = "Invalid date range: start_date and end_date must be valid YYYY-MM-DD dates" -_NO_TEAM_DATA: Final = "No Team usage data found for the given date range." -_NO_TAG_DATA: Final = "No Tag usage data found for the given date range." - - -@pytest.mark.parametrize( - ("start_date", "end_date", "team_message", "tag_message"), - ( - pytest.param("2026-10-09", "2026-10-01", _REVERSED, _REVERSED, id="reversed"), - pytest.param("2026-13-01", "2026-10-09", _NOT_CANONICAL, _NOT_CANONICAL, id="invalid-month"), - pytest.param("2001/01/01", "2001-01-09", _NOT_CANONICAL, _NOT_CANONICAL, id="slashes"), - pytest.param("2001-01-01", "2001-01-09", _NO_TEAM_DATA, _NO_TAG_DATA, id="valid"), - ), -) -def test_usage_chat_tools_answer_with_the_query_layers_date_check( - usage_chat: _UsageChat, start_date: str, end_date: str, team_message: str, tag_message: str -) -> None: - """The team and tag tools give the model the daily activity routes' 400 reason; the global tool, whose query - takes these dates without that check, still answers with its usage summary.""" - tool_messages, statuses = _tool_results(usage_chat, start_date, end_date) - assert tool_messages["get_usage_data"].startswith("Total Spend: $"), tool_messages - assert tool_messages["get_team_usage_data"] == team_message, tool_messages - assert tool_messages["get_tag_usage_data"] == tag_message, tool_messages - assert statuses == ("running", "complete") * len(_TOOLS), statuses diff --git a/tests/integration/spend/test_daily_activity_key_metadata_query_timeout.py b/tests/integration/spend/test_daily_activity_key_metadata_query_timeout.py index 780ee43fb3f..0c18f2a4b6f 100644 --- a/tests/integration/spend/test_daily_activity_key_metadata_query_timeout.py +++ b/tests/integration/spend/test_daily_activity_key_metadata_query_timeout.py @@ -99,16 +99,9 @@ class _Activity(BaseModel): results: tuple[_Day, ...] -class _UpstreamMessage(BaseModel): - model_config = ConfigDict(frozen=True) - role: str | None = None - - class _UpstreamRequest(BaseModel): model_config = ConfigDict(frozen=True) stream: bool | None = None - tools: tuple[JsonValue, ...] | None = None - messages: tuple[_UpstreamMessage, ...] = () @dataclass(frozen=True, slots=True) @@ -171,17 +164,6 @@ def _stream_frames() -> tuple[bytes, ...]: return (*(f"data: {json.dumps({**envelope, **frame})}\n\n".encode() for frame in frames), b"data: [DONE]\n\n") -def _usage_tool_call() -> Mapping[str, JsonValue]: - arguments: Final = json.dumps({"start_date": _day(-1), "end_date": _day(1)}) - return { - "role": "assistant", - "content": None, - "tool_calls": [ - {"id": "call_usage", "type": "function", "function": {"name": "get_usage_data", "arguments": arguments}} - ], - } - - def _response_object() -> bytes: return json.dumps( { @@ -216,9 +198,6 @@ def _respond(request: Request) -> Reply: body: Final = _UpstreamRequest.model_validate_json(request.body or b"{}") if body.stream: return Reply(content_type="text/event-stream", chunks=_stream_frames()) - roles: Final = frozenset(message.role for message in body.messages) - if body.tools and "tool" not in roles: - return Reply(body=_completion(_usage_tool_call(), "tool_calls")) return Reply(body=_completion({"role": "assistant", "content": REPLY_TEXT}, "stop")) @@ -459,12 +438,6 @@ def _restore(database_url: str, digest: str) -> None: ) -def _events(response: httpx.Response) -> tuple[Mapping[str, JsonValue], ...]: - return tuple( - json.loads(line.removeprefix("data: ")) for line in response.text.splitlines() if line.startswith("data: ") - ) - - @dataclass(frozen=True, slots=True) class Tenant: label: str @@ -714,39 +687,19 @@ def _rig(gateway: Gateway, directory: Path) -> Generator[tuple[Gateway, str]]: @pytest.mark.timeout(360) -def test_usage_ai_chat_timeout_then_second_timeout_still_recovers_key_alias_after_database_frees( +def test_usage_page_timeout_then_second_timeout_still_recovers_key_alias_after_database_frees( gateway: Gateway, tmp_path: Path ) -> None: with _rig(gateway, tmp_path) as (proxy, database_url): - spender: Final = _spender(proxy, database_url, "ai-chat") + spender: Final = _spender(proxy, database_url, "repeated-timeout") with _pinned(proxy) as pinned: with _locked_spend_logs(database_url): - with _recording(database_url) as during_chat: - chat: Final = pinned.request( - "POST", - "/usage/ai/chat", - body={ - "messages": [{"role": "user", "content": "What did we spend?"}], - "model": "openai/gpt-4o-mini", - }, - ) - assert chat.status_code == 200, chat.text - assert chat.elapsed >= FAILED_LOOKUP_FLOOR, chat.elapsed - tool_call: Final = { - "type": "tool_call", - "tool_name": "get_usage_data", - "tool_label": "global usage data", - "arguments": {"start_date": _day(-1), "end_date": _day(1)}, - } - assert _events(chat) == ( - {"type": "status", "message": "Thinking..."}, - {**tool_call, "status": "running"}, - {**tool_call, "status": "complete"}, - {"type": "status", "message": "Analyzing results..."}, - {"type": "chunk", "content": REPLY_TEXT}, - {"type": "done"}, - ), chat.text - assert len(_lookups(during_chat)) == 1 + with _recording(database_url) as during_timeout: + timed_out: Final = _read(pinned, spender.digest) + assert timed_out.status_code == 200, timed_out.text + assert timed_out.elapsed >= FAILED_LOOKUP_FLOOR, timed_out.elapsed + assert _aliases(timed_out, spender.digest) == (None,), timed_out.text + assert len(_lookups(during_timeout)) == 1 cached_miss: Final = _read(pinned, spender.digest) assert cached_miss.elapsed < FAILED_LOOKUP_FLOOR, cached_miss.elapsed assert _aliases(cached_miss, spender.digest) == (None,), cached_miss.text @@ -1087,44 +1040,3 @@ def test_usage_page_rejects_bad_key_filters_and_unrelated_routes_ignore_a_locked assert gateway_activity == 200, gateway_activity chat: Final = proxy.chat(MODEL, text=f"locked {uuid.uuid4().hex}") assert object_value(chat["usage"]) == dict(USAGE), chat - - -@pytest.mark.timeout(300) -def test_usage_ai_chat_survives_a_dropped_database_connection_during_alias_recovery( - gateway: Gateway, tmp_path: Path -) -> None: - with ( - scratch_database() as database_url, - database_relay(database_url, b"AS " + LOOKUP_MARKER.encode()) as (relay, relayed_url), - wire_server(_respond) as wire, - _proxy(gateway, tmp_path, relayed_url, wire.url) as proxy, - ): - spender: Final = _spender(proxy, database_url, "dropped-ai-chat") - with _pinned(proxy) as pinned: - relay.arm() - chat: Final = pinned.request( - "POST", - "/usage/ai/chat", - body={ - "messages": [{"role": "user", "content": "What did we spend?"}], - "model": "openai/gpt-4o-mini", - }, - ) - assert chat.status_code == 200, chat.text - assert relay.tripped.is_set(), chat.text - tool_call: Final = { - "type": "tool_call", - "tool_name": "get_usage_data", - "tool_label": "global usage data", - "arguments": {"start_date": _day(-1), "end_date": _day(1)}, - } - assert _events(chat) == ( - {"type": "status", "message": "Thinking..."}, - {**tool_call, "status": "running"}, - {**tool_call, "status": "complete"}, - {"type": "status", "message": "Analyzing results..."}, - {"type": "chunk", "content": REPLY_TEXT}, - {"type": "done"}, - ), chat.text - recovered: Final = _named_once_reconnected(pinned, spender) - assert _metadata(recovered, spender.digest) == _full_metadata(spender), recovered.text diff --git a/tests/integration/spend/test_daily_activity_key_owner_traffic.py b/tests/integration/spend/test_daily_activity_key_owner_traffic.py index b8f113aca49..5284ad631de 100644 --- a/tests/integration/spend/test_daily_activity_key_owner_traffic.py +++ b/tests/integration/spend/test_daily_activity_key_owner_traffic.py @@ -6,7 +6,6 @@ from collections.abc import Iterable from concurrent.futures import ThreadPoolExecutor from datetime import UTC, datetime, timedelta from hashlib import sha256 -from pathlib import Path from queue import SimpleQueue from typing import Final @@ -31,8 +30,7 @@ from integration._support.daily_activity import ( user_row, user_with_an_email, ) -from integration._support.database import read_rows, scratch_database -from integration._support.process import owned_proxy +from integration._support.database import read_rows from integration._support.wire import Reply, Request, wire_server from pydantic import JsonValue @@ -51,22 +49,6 @@ UNIFIED_ENDPOINTS: Final = ("/v1/chat/completions", "/v1/messages", "/v1/respons REQUESTS_OF_A_BURST: Final = 21 READS_DURING_A_BURST: Final = 30 TOKEN_LIMIT_DISCOVERY: Final = ("GET", "/v1/models") -TOOL_CALL: Final = "call_integration_usage" -ANSWER: Final = "One request cost $0.25" -SUMMARY_OF_ONE_SEEDED_ROW: Final = "\n".join( - ( - "Total Spend: $0.2500", - "Total Requests: 1", - "Successful: 1 | Failed: 0", - "Total Tokens: 15", - "", - "Top Models by Spend:", - " - gpt-4o-mini: $0.2500 (1 reqs, 15 tokens)", - "", - "Top Providers by Spend:", - " - openai: $0.2500 (1 reqs)", - ) -) def _chat_completion() -> dict[str, JsonValue]: @@ -105,55 +87,6 @@ def _provider(request: Request) -> Reply: return Reply(body=json.dumps(body).encode()) -def _usage_tool_call() -> dict[str, JsonValue]: - call: Final[dict[str, JsonValue]] = { - "id": TOOL_CALL, - "type": "function", - "function": { - "name": "get_usage_data", - "arguments": json.dumps({"start_date": DAY, "end_date": DAY}), - }, - } - return { - "id": f"chatcmpl-{uuid.uuid4().hex}", - "object": "chat.completion", - "created": 1, - "model": "gpt-4o-mini", - "choices": [ - { - "index": 0, - "message": {"role": "assistant", "content": None, "tool_calls": [call]}, - "finish_reason": "tool_calls", - } - ], - "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}, - } - - -def _streamed_chunk(delta: dict[str, JsonValue], finish_reason: str | None) -> bytes: - chunk: Final = { - "id": "chatcmpl-integration-usage", - "object": "chat.completion.chunk", - "created": 1, - "model": "gpt-4o-mini", - "choices": [{"index": 0, "delta": delta, "finish_reason": finish_reason}], - } - return f"data: {json.dumps(chunk)}\n\n".encode() - - -def _usage_analyst(request: Request) -> Reply: - if json.loads(request.body).get("stream"): - return Reply( - chunks=( - _streamed_chunk({"role": "assistant", "content": ANSWER}, None), - _streamed_chunk({}, "stop"), - b"data: [DONE]\n\n", - ), - content_type="text/event-stream", - ) - return Reply(body=json.dumps(_usage_tool_call()).encode()) - - def _sent_for_callers(requests: Iterable[Request]) -> tuple[Request, ...]: return tuple(request for request in requests if (request.method, request.target) != TOKEN_LIMIT_DISCOVERY) @@ -322,65 +255,6 @@ def test_cli_session_spend_is_reported_with_the_user_and_team_of_the_session( ) -@pytest.mark.timeout(300) -def test_usage_ai_chat_hands_the_model_the_usage_summary_without_any_key_owner( - gateway: Gateway, tmp_path: Path -) -> None: - question: Final = f"what did we spend {uuid.uuid4().hex}" - owner: Final = f"integration-{uuid.uuid4().hex}" - ownerless_key: Final = f"integration-ownerless-{uuid.uuid4().hex}" - with ( - scratch_database() as scratch_url, - wire_server(_usage_analyst) as wire, - owned_proxy( - gateway, - tmp_path, - { - "DATABASE_URL": scratch_url, - "OPENAI_API_BASE": f"{wire.url}/v1", - "OPENAI_BASE_URL": f"{wire.url}/v1", - "OPENAI_API_KEY": "integration-provider-key", - }, - remove_environment=("DATABASE_URL_READ_REPLICA",), - ) as candidate, - ): - candidate.post("/user/new", {"user_id": owner, "user_email": f"{owner}@example.com", "auto_create_key": False}) - with daily_rows((user_row(owner, ownerless_key, DAY),), database_url=scratch_url): - answer: Final = candidate.request( - "POST", - "/usage/ai/chat", - {"messages": [{"role": "user", "content": question}], "model": "openai/gpt-4o-mini"}, - ) - assert answer.status_code == 200, answer.text - tool_call: Final = { - "type": "tool_call", - "tool_name": "get_usage_data", - "tool_label": "global usage data", - "arguments": {"start_date": DAY, "end_date": DAY}, - } - events: Final = [ - json.loads(line.removeprefix("data: ")) for line in answer.text.splitlines() if line.startswith("data: ") - ] - assert events == [ - {"type": "status", "message": "Thinking..."}, - {**tool_call, "status": "running"}, - {**tool_call, "status": "complete"}, - {"type": "status", "message": "Analyzing results..."}, - {"type": "chunk", "content": ANSWER}, - {"type": "done"}, - ], answer.text - asked, analysed = wire.drain() - assert [asked.target, analysed.target] == ["/v1/chat/completions", "/v1/chat/completions"] - assert json.loads(asked.body)["messages"][-1] == {"role": "user", "content": question} - assert json.loads(analysed.body)["messages"][-1] == { - "role": "tool", - "tool_call_id": TOOL_CALL, - "content": SUMMARY_OF_ONE_SEEDED_ROW, - } - assert owner not in analysed.body.decode() - assert ownerless_key not in analysed.body.decode() - - @pytest.mark.timeout(300) def test_owner_is_reported_on_every_route_while_a_burst_of_requests_waits_on_the_provider(gateway: Gateway) -> None: released: Final = threading.Event() diff --git a/tests/unit/AGENTS.md b/tests/unit/AGENTS.md index 9ce6c58cff7..ca717e8efb0 100644 --- a/tests/unit/AGENTS.md +++ b/tests/unit/AGENTS.md @@ -1,6 +1,9 @@ # tests/unit -In-process. No network or subprocess +In-process. No network or subprocess. `interactions/test_openapi_compliance.py` reads the spec snapshot beside it, +and only the `interactions-spec-canary` workflow passes `--interactions-spec-url` (registered in +`interactions/conftest.py`, so name that file or directory on the command line) with `ai.google.dev` allowed, to run +the same tests against Google's live spec Unit tests must not depend on the current time or execution speed. Use fixed timestamps for fixtures and controlled clocks for time-dependent behavior. Incidental clock reads inside production code are allowed diff --git a/tests/unit/interactions/conftest.py b/tests/unit/interactions/conftest.py new file mode 100644 index 00000000000..b53763c7036 --- /dev/null +++ b/tests/unit/interactions/conftest.py @@ -0,0 +1,9 @@ +import pytest + + +def pytest_addoption(parser: pytest.Parser) -> None: + parser.addoption( + "--interactions-spec-url", + default=None, + help="Run the Interactions OpenAPI compliance tests against this live spec instead of the vendored snapshot", + ) diff --git a/tests/unit/interactions/interactions.openapi.json b/tests/unit/interactions/interactions.openapi.json new file mode 100644 index 00000000000..3830f5093cb --- /dev/null +++ b/tests/unit/interactions/interactions.openapi.json @@ -0,0 +1,10024 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "Gemini API", + "description": "The Gemini Interactions API allows developers to build generative AI applications using Gemini models. Gemini is our most capable model, built from the ground up to be multimodal. It can generalize and seamlessly understand, operate across, and combine different types of information including language, images, audio, video, and code. You can use the Gemini API for use cases like reasoning across text and images, content generation, dialogue agents, summarization and classification systems, and more.", + "version": "v1beta", + "x-google-revision": "0" + }, + "servers": [ + { + "url": "https://generativelanguage.googleapis.com", + "description": "Global Endpoint" + } + ], + "paths": { + "/upload/{api_version}/environments/{environment}/files/{path}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + }, + { + "name": "environment", + "in": "path", + "description": "The ID of the environment that owns the destination file.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "path", + "in": "path", + "description": "The relative destination path inside the environment workspace.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "put": { + "operationId": "StartEnvironmentFileUpload", + "description": "Starts a resumable upload session for a file in an environment workspace.\nUpload the file bytes to the URL returned in the `X-Goog-Upload-URL`\nresponse header, using the resumable upload protocol.\n", + "parameters": [ + { + "$ref": "#/components/parameters/EnvironmentFileExtract" + }, + { + "$ref": "#/components/parameters/EnvironmentFileOverwrite" + }, + { + "$ref": "#/components/parameters/EnvironmentFileUploadCommand" + }, + { + "$ref": "#/components/parameters/EnvironmentFileUploadContentLength" + }, + { + "$ref": "#/components/parameters/EnvironmentFileUploadContentType" + }, + { + "$ref": "#/components/parameters/EnvironmentFileUploadProtocol" + } + ], + "responses": { + "200": { + "description": "Upload session created successfully. Send the file bytes to the returned upload URL.", + "headers": { + "X-Goog-Upload-URL": { + "$ref": "#/components/headers/EnvironmentFileUploadUrl" + } + } + }, + "4XX": { + "description": "The upload session request failed with a client error." + }, + "5XX": { + "description": "The upload session request failed with a server error." + } + }, + "summary": "Start an environment file upload", + "x-codeSamples": [ + { + "label": "start_upload", + "lang": "sh", + "source": "curl -i -X PUT \\\n 'https://generativelanguage.googleapis.com/upload/v1beta/environments/env_abc123/files/main.py?overwrite=true' \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H 'X-Goog-Upload-Protocol: resumable' \\\n -H 'X-Goog-Upload-Command: start' \\\n -H \"X-Goog-Upload-Header-Content-Length: $(wc -c < main.py)\" \\\n -H 'X-Goog-Upload-Header-Content-Type: text/x-python'\n" + } + ] + } + }, + "/{api_version}/agents": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListAgents", + "description": "Lists all Agents.", + "parameters": [ + { + "name": "page_size", + "in": "query", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "parent", + "in": "query", + "description": "Required. The parent resource to list agents from.\nFormat: `projects/{project}/locations/{location}`", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "examples": { + "list": { + "summary": "List Agents", + "value": { + "agents": [ + { + "description": "A helpful research assistant.", + "base_agent": "antigravity-preview-05-2026", + "id": "research-assistant-abc123", + "system_instruction": "You are a helpful research assistant.", + "tools": [ + { + "type": "google_search" + } + ] + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/ListAgentsResponse" + } + } + } + } + }, + "tags": [ + "agents" + ], + "x-codeSamples": [ + { + "label": "list", + "lang": "sh", + "source": "curl -X GET https://generativelanguage.googleapis.com/v1beta/agents \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "list", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.agents.list()\nfor agent in response.agents or []:\n print(agent.id)\n" + }, + { + "label": "list", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst agents = await ai.agents.list();\nfor (const agent of agents.agents ?? []) {\n console.log(agent.id);\n}\n" + }, + { + "label": "list", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.gaos.models.agents.AgentListResponse;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.ListAgentsResponse;\n\nClient client = new Client();\nListAgentsResponse response = client.agents.list().call();\nList agents =\n response.agentListResponse().flatMap(AgentListResponse::agents).orElse(List.of());\nfor (Agent agent : agents) {\n agent.id().ifPresent(System.out::println);\n}\n" + }, + { + "label": "list", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n res, err := client.Agents.List(ctx, operations.ListAgentsRequest{})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.AgentListResponse != nil {\n for _, agent := range res.AgentListResponse.Agents {\n if agent.ID != nil {\n fmt.Println(*agent.ID)\n }\n }\n }\n}\n" + } + ] + }, + "post": { + "operationId": "CreateAgent", + "description": "Creates a new Agent (Typed version for SDK).", + "parameters": [ + { + "name": "parent", + "in": "query", + "description": "Required. The parent resource where this agent will be created.\nFormat: `projects/{project}/locations/{location}`", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Required. The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Agent" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "examples": { + "create": { + "summary": "Create Agent", + "value": { + "description": "A helpful research assistant.", + "base_agent": "antigravity-preview-05-2026", + "base_environment": "remote", + "id": "research-assistant-abc123", + "system_instruction": "You are a helpful research assistant.", + "tools": [ + { + "type": "google_search" + } + ] + } + }, + "fork_from_env": { + "summary": "Agent Forked from Environment", + "value": { + "base_agent": "antigravity-preview-05-2026", + "base_environment": "env_abc123", + "id": "my-data-analyst-abc123", + "system_instruction": "You are a data analyst. Use the template at /workspace/template.py for all reports." + } + }, + "with_sources": { + "summary": "Agent with Sources", + "value": { + "base_agent": "antigravity-preview-05-2026", + "base_environment": { + "type": "remote", + "sources": [ + { + "type": "inline", + "content": "Always use matplotlib for charts. Include a summary table in every report.", + "target": ".agents/AGENTS.md" + }, + { + "type": "repository", + "source": "https://github.com/my-org/analysis-templates", + "target": "/workspace/templates" + } + ] + }, + "id": "data-analyst-abc123", + "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF." + } + } + }, + "schema": { + "$ref": "#/components/schemas/Agent" + } + } + } + } + }, + "tags": [ + "agents" + ], + "x-codeSamples": [ + { + "label": "create", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/agents \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"research-assistant-abc123\",\n \"base_agent\": \"antigravity-preview-05-2026\",\n \"description\": \"A helpful research assistant.\",\n \"system_instruction\": \"You are a helpful research assistant.\",\n \"base_environment\": \"remote\",\n \"tools\": [{\"type\": \"google_search\"}]\n }'\n" + }, + { + "label": "with_sources", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/agents \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"data-analyst-abc123\",\n \"base_agent\": \"antigravity-preview-05-2026\",\n \"system_instruction\": \"You are a data analyst. Always include visualizations and export results as PDF.\",\n \"base_environment\": {\n \"type\": \"remote\",\n \"sources\": [\n {\n \"type\": \"inline\",\n \"target\": \".agents/AGENTS.md\",\n \"content\": \"Always use matplotlib for charts. Include a summary table in every report.\"\n },\n {\n \"type\": \"repository\",\n \"source\": \"https://github.com/my-org/analysis-templates\",\n \"target\": \"/workspace/templates\"\n }\n ]\n }\n }'\n" + }, + { + "label": "fork_from_env", + "lang": "sh", + "source": "# Step 1: Set up the environment interactively\nRESPONSE=$(curl -s -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agent\": \"antigravity-preview-05-2026\",\n \"input\": \"Write a basic Hello World template to /workspace/template.py.\",\n \"environment\": \"remote\"\n }')\nENV_ID=$(echo \"$RESPONSE\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['environment_id'])\")\n\n# Step 2: Fork that environment into a named agent\ncurl -X POST https://generativelanguage.googleapis.com/v1beta/agents \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"id\\\": \\\"my-data-analyst\\\",\n \\\"base_agent\\\": \\\"antigravity-preview-05-2026\\\",\n \\\"system_instruction\\\": \\\"You are a data analyst. Use the template at /workspace/template.py for all reports.\\\",\n \\\"base_environment\\\": \\\"$ENV_ID\\\"\n }\"\n" + }, + { + "label": "create", + "lang": "python", + "source": "import uuid\nfrom google import genai\n\nclient = genai.Client()\nagent = client.agents.create(\n id=f\"research-assistant-{uuid.uuid4().hex[:8]}\",\n base_agent=\"antigravity-preview-05-2026\",\n description=\"A helpful research assistant.\",\n system_instruction=\"You are a helpful research assistant.\",\n base_environment=\"remote\",\n tools=[{\"type\": \"google_search\"}],\n)\nprint(agent.id)\n" + }, + { + "label": "with_sources", + "lang": "python", + "source": "import uuid\nfrom google import genai\n\nclient = genai.Client()\nagent = client.agents.create(\n id=f\"data-analyst-{uuid.uuid4().hex[:8]}\",\n base_agent=\"antigravity-preview-05-2026\",\n system_instruction=(\n \"You are a data analyst. Always include visualizations and export\"\n \" results as PDF.\"\n ),\n base_environment={\n \"type\": \"remote\",\n \"sources\": [\n {\n \"type\": \"inline\",\n \"target\": \".agents/AGENTS.md\",\n \"content\": (\n \"Always use matplotlib for charts. Include a summary\"\n \" table in every report.\"\n ),\n },\n {\n \"type\": \"repository\",\n \"source\": \"https://github.com/my-org/analysis-templates\",\n \"target\": \"/workspace/templates\",\n },\n ],\n },\n)\nprint(f\"Created agent: {agent.id}\")\n" + }, + { + "label": "fork_from_env", + "lang": "python", + "source": "import uuid\nfrom google import genai\n\nclient = genai.Client()\n\n# Step 1: Set up the environment interactively.\ninteraction = client.interactions.create(\n agent=\"antigravity-preview-05-2026\",\n input=\"Write a basic Hello World template to /workspace/template.py.\",\n environment=\"remote\",\n)\n\n# Step 2: Fork that environment into a named agent.\nagent_id = f\"my-data-analyst-{uuid.uuid4().hex[:8]}\"\nagent = client.agents.create(\n id=agent_id,\n base_agent=\"antigravity-preview-05-2026\",\n system_instruction=(\n \"You are a data analyst. Use the template at /workspace/template.py\"\n \" for all reports.\"\n ),\n base_environment=interaction.environment_id,\n)\nprint(f\"Forked agent: {agent.id}\")\n" + }, + { + "label": "create", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst agentId = `research-assistant-${crypto.randomUUID().slice(0, 8)}`;\nconst agent = await ai.agents.create({\n id: agentId,\n base_agent: 'antigravity-preview-05-2026',\n description: 'A helpful research assistant.',\n system_instruction: 'You are a helpful research assistant.',\n base_environment: 'remote',\n tools: [{type: 'google_search'}],\n});\nif (!agent.id) {\n throw new Error('Agent creation failed: ID is undefined');\n}\nconsole.log(agent.id);\n" + }, + { + "label": "with_sources", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst agentId = `data-analyst-${crypto.randomUUID().slice(0, 8)}`;\nconst agent = await ai.agents.create({\n id: agentId,\n base_agent: 'antigravity-preview-05-2026',\n system_instruction:\n 'You are a data analyst. Always include visualizations and export results as PDF.',\n base_environment: {\n type: 'remote',\n sources: [\n {\n type: 'inline',\n target: '.agents/AGENTS.md',\n content:\n 'Always use matplotlib for charts. Include a summary table in every report.',\n },\n {\n type: 'repository',\n source: 'https://github.com/my-org/analysis-templates',\n target: '/workspace/templates',\n },\n ],\n },\n});\nconsole.log(`Created agent: ${agent.id}`);\n" + }, + { + "label": "fork_from_env", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n// Step 1: Set up the environment interactively.\nconst interaction = await ai.interactions.create({\n agent: 'antigravity-preview-05-2026',\n input: 'Write a basic Hello World template to /workspace/template.py.',\n environment: 'remote',\n});\n\n// Step 2: Fork that environment into a named agent.\nconst agentId = `my-data-analyst-${crypto.randomUUID().slice(0, 8)}`;\nconst agent = await ai.agents.create({\n id: agentId,\n base_agent: 'antigravity-preview-05-2026',\n system_instruction:\n 'You are a data analyst. Use the template at /workspace/template.py for all reports.',\n base_environment: interaction.environment_id,\n});\nconsole.log(`Forked agent: ${agent.id}`);\n" + }, + { + "label": "create", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.gaos.models.agents.BaseEnvironment;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateAgentResponse;\nimport com.google.genai.gaos.models.interactions.GoogleSearch;\n\nClient client = new Client();\nString agentId = \"research-assistant-\" + UUID.randomUUID().toString().substring(0, 8);\nAgent agent =\n Agent.builder()\n .id(agentId)\n .baseAgent(\"antigravity-preview-05-2026\")\n .description(\"A helpful research assistant.\")\n .systemInstruction(\"You are a helpful research assistant.\")\n .baseEnvironment(BaseEnvironment.of(\"remote\"))\n .tools(List.of(new GoogleSearch()))\n .build();\nCreateAgentResponse response = client.agents.create(agent);\nSystem.out.println(response.agent().flatMap(Agent::id).orElse(\"\"));\n" + }, + { + "label": "with_sources", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.gaos.models.agents.BaseEnvironment;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateAgentResponse;\nimport com.google.genai.gaos.models.environments.Environment;\nimport com.google.genai.gaos.models.interactions.Source;\nimport com.google.genai.gaos.models.interactions.SourceType;\n\nClient client = new Client();\nString agentId = \"data-analyst-\" + UUID.randomUUID().toString().substring(0, 8);\ncom.google.genai.gaos.models.interactions.Environment env =\n com.google.genai.gaos.models.interactions.Environment.builder()\n .sources(\n List.of(\n Source.builder()\n .type(SourceType.INLINE)\n .target(\".agents/AGENTS.md\")\n .content(\n \"Always use matplotlib for charts. Include a summary table in every\"\n + \" report.\")\n .build(),\n Source.builder()\n .type(SourceType.REPOSITORY)\n .source(\"https://github.com/my-org/analysis-templates\")\n .target(\"/workspace/templates\")\n .build()))\n .build();\nAgent agent =\n Agent.builder()\n .id(agentId)\n .baseAgent(\"antigravity-preview-05-2026\")\n .systemInstruction(\n \"You are a data analyst. Always include visualizations and export results as PDF.\")\n .baseEnvironment(BaseEnvironment.of(env))\n .build();\nCreateAgentResponse response = client.agents.create(agent);\nSystem.out.println(\"Created agent: \" + response.agent().flatMap(Agent::id).orElse(\"\"));\n" + }, + { + "label": "fork_from_env", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.gaos.models.agents.BaseEnvironment;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;\nimport com.google.genai.gaos.models.operations.CreateAgentResponse;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.Step;\n\nClient client = new Client();\n\n// Step 1: Set up the environment interactively.\nCreateAgentInteraction params =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"antigravity-preview-05-2026\"))\n .input(\n InteractionsInput.of(\n \"Write a basic Hello World template to /workspace/template.py.\"))\n .environment(CreateAgentInteractionEnvironment.of(\"remote\"))\n .build();\nCreateInteractionResponse interactionResponse =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n interactionResponse\n .interaction()\n .orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\n\n// Step 2: Fork that environment into a named agent.\nString agentId = \"my-data-analyst-\" + UUID.randomUUID().toString().substring(0, 8);\nAgent agent =\n Agent.builder()\n .id(agentId)\n .baseAgent(\"antigravity-preview-05-2026\")\n .systemInstruction(\n \"You are a data analyst. Use the template at /workspace/template.py for all\"\n + \" reports.\")\n .baseEnvironment(BaseEnvironment.of(interaction.environmentId().orElse(\"\")))\n .build();\nCreateAgentResponse agentResponse = client.agents.create(agent);\nSystem.out.println(\"Forked agent: \" + agentResponse.agent().flatMap(Agent::id).orElse(\"\"));\n" + }, + { + "label": "create", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\n \"google.golang.org/genai\"\n gaos_agents \"google.golang.org/genai/interactions/models/agents\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n agentID := fmt.Sprintf(\"research-assistant-%d\", time.Now().UnixNano())\n req := operations.CreateAgentRequest{\n Body: gaos_agents.Agent{\n ID: genai.Ptr(agentID),\n BaseAgent: genai.Ptr(\"antigravity-preview-05-2026\"),\n Description: genai.Ptr(\"A helpful research assistant.\"),\n SystemInstruction: genai.Ptr(\"You are a helpful research assistant.\"),\n BaseEnvironment: genai.Ptr(gaos_agents.NewBaseEnvironment(\"remote\")),\n Tools: []gaos_agents.AgentTool{\n gaos_agents.NewAgentTool(gaos_interactions.GoogleSearch{}),\n },\n },\n }\n\n res, err := client.Agents.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Agent != nil && res.Agent.ID != nil {\n fmt.Println(*res.Agent.ID)\n }\n}\n" + }, + { + "label": "with_sources", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\n \"google.golang.org/genai\"\n gaos_agents \"google.golang.org/genai/interactions/models/agents\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n agentID := fmt.Sprintf(\"data-analyst-%d\", time.Now().UnixNano())\n env := gaos_interactions.Environment{\n Sources: []gaos_interactions.Source{\n {\n Type: genai.Ptr(gaos_interactions.SourceTypeInline),\n Target: genai.Ptr(\".agents/AGENTS.md\"),\n Content: genai.Ptr(\"Always use matplotlib for charts. Include a summary table in every report.\"),\n },\n {\n Type: genai.Ptr(gaos_interactions.SourceTypeRepository),\n Source: genai.Ptr(\"https://github.com/my-org/analysis-templates\"),\n Target: genai.Ptr(\"/workspace/templates\"),\n },\n },\n }\n\n req := operations.CreateAgentRequest{\n Body: gaos_agents.Agent{\n ID: genai.Ptr(agentID),\n BaseAgent: genai.Ptr(\"antigravity-preview-05-2026\"),\n SystemInstruction: genai.Ptr(\"You are a data analyst. Always include visualizations and export results as PDF.\"),\n BaseEnvironment: genai.Ptr(gaos_agents.NewBaseEnvironment(env)),\n },\n }\n\n res, err := client.Agents.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Agent != nil && res.Agent.ID != nil {\n fmt.Printf(\"Created agent: %s\\n\", *res.Agent.ID)\n }\n}\n" + }, + { + "label": "fork_from_env", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\n \"google.golang.org/genai\"\n gaos_agents \"google.golang.org/genai/interactions/models/agents\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n // Step 1: Set up the environment interactively.\n interactionReq := operations.CreateInteractionRequest{\n Body: operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(\"antigravity-preview-05-2026\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Write a basic Hello World template to /workspace/template.py.\")),\n Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(\"remote\")),\n }),\n }\n interactionRes, err := client.Interactions.Create(ctx, interactionReq)\n if err != nil {\n log.Fatal(err)\n }\n envID := \"\"\n if interactionRes.Interaction != nil && interactionRes.Interaction.EnvironmentID != nil {\n envID = *interactionRes.Interaction.EnvironmentID\n }\n\n // Step 2: Fork that environment into a named agent.\n agentID := fmt.Sprintf(\"my-data-analyst-%d\", time.Now().UnixNano())\n req := operations.CreateAgentRequest{\n Body: gaos_agents.Agent{\n ID: genai.Ptr(agentID),\n BaseAgent: genai.Ptr(\"antigravity-preview-05-2026\"),\n SystemInstruction: genai.Ptr(\"You are a data analyst. Use the template at /workspace/template.py for all reports.\"),\n BaseEnvironment: genai.Ptr(gaos_agents.NewBaseEnvironment(envID)),\n },\n }\n res, err := client.Agents.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n if res.Agent != nil && res.Agent.ID != nil {\n fmt.Printf(\"Forked agent: %s\\n\", *res.Agent.ID)\n }\n}\n" + } + ] + } + }, + "/{api_version}/agents/{agentsId}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "delete": { + "operationId": "DeleteAgent", + "description": "Deletes an Agent.", + "parameters": [ + { + "name": "agentsId", + "in": "path", + "description": "Required. The name of the agent to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "examples": { + "delete": { + "summary": "Delete Agent", + "value": {} + } + }, + "schema": { + "$ref": "#/components/schemas/Empty" + } + } + } + } + }, + "tags": [ + "agents" + ], + "x-codeSamples": [ + { + "label": "delete", + "lang": "sh", + "source": "curl -X DELETE https://generativelanguage.googleapis.com/v1beta/agents/ag_abc123 \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "delete", + "lang": "python", + "source": "import uuid\nfrom google import genai\n\nclient = genai.Client()\n\n\nclient.agents.delete(agent_id)\nprint(\"Agent deleted successfully.\")\n" + }, + { + "label": "delete", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nawait ai.agents.delete(agentId);\nconsole.log('Agent deleted successfully.');\n" + }, + { + "label": "delete", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.Client;\n\nClient client = new Client();\n\n\nclient.agents.delete(agentId);\nSystem.out.println(\"Agent deleted successfully.\");\n" + }, + { + "label": "delete", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n\n _, err = client.Agents.Delete(ctx, operations.DeleteAgentRequest{ID: agentID})\n if err != nil {\n log.Fatal(err)\n }\n fmt.Println(\"Agent deleted successfully.\")\n}\n" + } + ] + }, + "get": { + "operationId": "GetAgent", + "description": "Gets a specific Agent.", + "parameters": [ + { + "name": "agentsId", + "in": "path", + "description": "Required. The name of the agent to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "examples": { + "get": { + "summary": "Get Agent", + "value": { + "created": "2025-11-26T12:25:15Z", + "display_name": "My Research Agent", + "id": "ag_abc123", + "object": "agent", + "system_instruction": "You are a helpful research assistant.", + "tools": [ + { + "type": "google_search" + } + ], + "updated": "2025-11-26T12:25:15Z" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Agent" + } + } + } + } + }, + "tags": [ + "agents" + ], + "x-codeSamples": [ + { + "label": "get", + "lang": "sh", + "source": "curl -X GET https://generativelanguage.googleapis.com/v1beta/agents/ag_abc123 \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "get", + "lang": "python", + "source": "import uuid\nfrom google import genai\n\nclient = genai.Client()\n\n\nagent = client.agents.get(agent_id)\nprint(agent.id)\n" + }, + { + "label": "get", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nconst agent = await ai.agents.get(agentId);\nif (!agent.id) {\n throw new Error('Agent retrieval failed: ID is undefined');\n}\nconsole.log(agent.id);\n" + }, + { + "label": "get", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.GetAgentResponse;\n\nClient client = new Client();\n\n\nGetAgentResponse response = client.agents.get(agentId);\nAgent agent = response.agent().orElseThrow(() -> new RuntimeException(\"No agent returned\"));\nSystem.out.println(agent.id().orElse(\"\"));\n" + }, + { + "label": "get", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n\n res, err := client.Agents.Get(ctx, operations.GetAgentRequest{ID: agentID})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Agent != nil && res.Agent.ID != nil {\n fmt.Println(*res.Agent.ID)\n }\n}\n" + } + ] + } + }, + "/{api_version}/credentials": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListCredentials", + "description": "Lists credentials.", + "parameters": [ + { + "name": "page_size", + "in": "query", + "description": "Optional. Maximum number of credentials to return.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "Optional. Pagination token.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListCredentialsResponse" + } + } + } + } + }, + "tags": [ + "credentials" + ] + }, + "post": { + "operationId": "CreateCredential", + "description": "Creates a new credential.", + "parameters": [], + "requestBody": { + "description": "Required. The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CredentialCreateParams" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Credential" + } + } + } + } + }, + "tags": [ + "credentials" + ] + } + }, + "/{api_version}/credentials/{id}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "delete": { + "operationId": "DeleteCredential", + "description": "Deletes a credential.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource ID segment making up resource `name`. It identifies the resource\nwithin its parent collection as described in https://google.aip.dev/122.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Empty" + } + } + } + } + }, + "tags": [ + "credentials" + ] + }, + "get": { + "operationId": "GetCredential", + "description": "Gets a credential by ID.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource ID segment making up resource `name`. It identifies the resource\nwithin its parent collection as described in https://google.aip.dev/122.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Credential" + } + } + } + } + }, + "tags": [ + "credentials" + ] + }, + "patch": { + "operationId": "UpdateCredential", + "description": "Updates a credential.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource ID segment making up resource `name`. It identifies the resource\nwithin its parent collection as described in https://google.aip.dev/122.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "update_mask", + "in": "query", + "description": "Optional. The list of fields to update.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Required. The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CredentialUpdateParams" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Credential" + } + } + } + } + }, + "tags": [ + "credentials" + ] + } + }, + "/{api_version}/environments": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListEnvironments", + "description": "Lists environments.", + "parameters": [ + { + "name": "page_size", + "in": "query", + "description": "Optional. Maximum number of environments to return.\nIf unspecified, defaults to 50. Maximum is 1000.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "Optional. Pagination token.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEnvironmentsResponse" + } + } + } + } + }, + "tags": [ + "environments" + ], + "x-codeSamples": [ + { + "label": "list", + "lang": "sh", + "source": "curl -X GET https://generativelanguage.googleapis.com/v1beta/environments \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "list", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.environments.list()\nfor environment in response.environments or []:\n print(environment.id)\n" + }, + { + "label": "list", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst response = await ai.environments.list();\nfor (const env of response.environments ?? []) {\n console.log(env.id);\n}\n" + }, + { + "label": "list", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.Environment;\nimport com.google.genai.gaos.models.operations.ListEnvironmentsResponse;\n\nClient client = new Client();\nListEnvironmentsResponse response = client.environments.listEnvironmentsDirect();\nfor (com.google.genai.gaos.models.environments.Environment env :\n response.listEnvironmentsResponse().flatMap(res -> res.environments()).orElse(List.of())) {\n System.out.println(env.id().orElse(\"\"));\n}\n" + }, + { + "label": "list", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n res, err := client.Environments.ListEnvironments(ctx, operations.ListEnvironmentsRequest{})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.ListEnvironmentsResponse != nil {\n for _, env := range res.ListEnvironmentsResponse.Environments {\n if env.ID != \"\" {\n fmt.Println(env.ID)\n }\n }\n }\n}\n" + } + ] + }, + "post": { + "operationId": "CreateEnvironment", + "description": "Creates an environment.", + "parameters": [], + "requestBody": { + "description": "Required. The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEnvironmentRequest" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Environment" + } + } + } + } + }, + "tags": [ + "environments" + ], + "x-codeSamples": [ + { + "label": "create", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/environments \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sources\": [{\n \"type\": \"inline\",\n \"target\": \"main.py\",\n \"content\": \"print(\\\"Hello, World!\\\")\"\n }]\n }'\n" + }, + { + "label": "copy", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/environments \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"from_environment\": \"environments/env_abc123\"\n }'\n" + }, + { + "label": "create", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nenvironment = client.environments.create(\n sources=[{\n \"type\": \"inline\",\n \"target\": \"main.py\",\n \"content\": \"print('Hello, World!')\",\n }]\n)\nprint(environment.id)\n" + }, + { + "label": "copy", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\nenvironment = client.environments.create(\n from_environment=source_env.id,\n)\nprint(environment.id)\n" + }, + { + "label": "create", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst environment = await ai.environments.create({\n sources: [\n {\n type: 'inline',\n target: 'main.py',\n content: \"print('Hello, World!')\",\n },\n ],\n});\nif (!environment.id) {\n throw new Error('Environment creation failed: ID is undefined');\n}\nconsole.log(environment.id);\n" + }, + { + "label": "copy", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nconst environment = await ai.environments.create({\n from_environment: sourceEnv.id,\n});\nif (!environment.id) {\n throw new Error('Environment creation failed: ID is undefined');\n}\nconsole.log(environment.id);\n" + }, + { + "label": "create", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.CreateEnvironmentRequest;\nimport com.google.genai.gaos.models.environments.Environment;\nimport com.google.genai.gaos.models.interactions.Source;\nimport com.google.genai.gaos.models.interactions.SourceType;\n\nClient client = new Client();\nCreateEnvironmentRequest request =\n CreateEnvironmentRequest.builder()\n .sources(\n List.of(\n Source.builder()\n .type(SourceType.INLINE)\n .target(\"main.py\")\n .content(\"print('Hello, World!')\")\n .build()))\n .build();\ncom.google.genai.gaos.models.environments.Environment environment =\n client.environments.createEnvironment(request).environment().orElseThrow();\nSystem.out.println(environment.id().orElse(\"\"));\n" + }, + { + "label": "copy", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.CreateEnvironmentRequest;\nimport com.google.genai.gaos.models.environments.Environment;\n\nClient client = new Client();\n\n\nCreateEnvironmentRequest request =\n CreateEnvironmentRequest.builder().fromEnvironment(sourceEnvId).build();\ncom.google.genai.gaos.models.environments.Environment environment =\n client.environments.createEnvironment(request).environment().orElseThrow();\nSystem.out.println(environment.id().orElse(\"\"));\n" + }, + { + "label": "create", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_environments \"google.golang.org/genai/interactions/models/environments\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n req := operations.CreateEnvironmentRequest{\n Body: gaos_environments.CreateEnvironmentRequest{\n Sources: []gaos_interactions.Source{\n {\n Type: genai.Ptr(gaos_interactions.SourceTypeInline),\n Target: genai.Ptr(\"main.py\"),\n Content: genai.Ptr(\"print('Hello, World!')\"),\n },\n },\n },\n }\n\n res, err := client.Environments.CreateEnvironment(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Environment != nil && res.Environment.ID != \"\" {\n fmt.Println(res.Environment.ID)\n\n }\n}\n" + }, + { + "label": "copy", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_environments \"google.golang.org/genai/interactions/models/environments\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n\n res, err := client.Environments.CreateEnvironment(ctx, operations.CreateEnvironmentRequest{\n Body: gaos_environments.CreateEnvironmentRequest{\n FromEnvironment: genai.Ptr(sourceEnvID),\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Environment != nil && res.Environment.ID != \"\" {\n fmt.Println(res.Environment.ID)\n\n }\n}\n" + } + ] + } + }, + "/{api_version}/environments/{environment}/files/{path}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + }, + { + "name": "environment", + "in": "path", + "description": "The ID of the environment whose snapshot to read.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "path", + "in": "path", + "description": "Path of the file or directory inside the environment workspace, relative to its root (e.g. src).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "get": { + "operationId": "GetEnvironmentFiles", + "description": "Retrieves file metadata or directory contents from an environment's snapshot. To download file content, use the download URL returned in the response.", + "parameters": [ + { + "name": "page_size", + "in": "query", + "description": "Optional. Maximum number of entries to return per page (for directory listing).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "Optional. Pagination token for directory listing.", + "schema": { + "type": "string" + } + }, + { + "name": "recursive", + "in": "query", + "description": "Optional. If true and the path is a directory, recursively lists all files.", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetEnvironmentFilesResponse" + } + } + } + } + }, + "tags": [ + "environments.files" + ], + "x-codeSamples": [ + { + "label": "list_files", + "lang": "sh", + "source": "curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/src' \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "get_file", + "lang": "sh", + "source": "curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/main.py' \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "download_file", + "lang": "sh", + "source": "curl -X GET 'https://generativelanguage.googleapis.com/v1beta/environments/env_abc123/files/src/main.py?alt=media' \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n --output main.py\n" + }, + { + "label": "list_files", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\nresponse = client.environments.files.list(\n environment=created.id,\n path=\"src\",\n)\nfor file in response.files or []:\n print(file.name, file.type, file.size_bytes)\n" + }, + { + "label": "get_file", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\nresponse = client.environments.files.get(\n environment=created.id,\n path=\"main.py\",\n)\nfor file in response.files or []:\n print(file.name, file.size_bytes)\n" + }, + { + "label": "download_file", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\ncontent = client.environments.files.download(\n environment=created.id,\n path=\"src/main.py\",\n)\nprint(content.decode(\"utf-8\"))\n" + }, + { + "label": "list_files", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nconst response = await ai.environments.files.list({\n environment: created.id,\n path: 'src',\n});\nfor (const file of response.files ?? []) {\n console.log(file.name, file.type, file.size_bytes);\n}\n" + }, + { + "label": "get_file", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nconst response = await ai.environments.files.list({\n environment: created.id,\n path: 'main.py',\n});\nfor (const file of response.files ?? []) {\n console.log(file.name, file.size_bytes);\n}\n" + }, + { + "label": "list_files", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.EnvironmentFile;\nimport com.google.genai.gaos.models.operations.GetEnvironmentFilesRequest;\nimport com.google.genai.gaos.models.environments.GetEnvironmentFilesResponse;\n\nClient client = new Client();\n\n\ncom.google.genai.gaos.models.operations.GetEnvironmentFilesResponse response =\n client\n .environments\n .files()\n .list(GetEnvironmentFilesRequest.builder().environment(envId).path(\"src\").build());\nGetEnvironmentFilesResponse filesResponse =\n response.getEnvironmentFilesResponse().orElseThrow();\nfor (EnvironmentFile file : filesResponse.files().orElse(List.of())) {\n System.out.println(\n file.name().orElse(\"\")\n + \" \"\n + file.type().map(Object::toString).orElse(\"\")\n + \" \"\n + file.sizeBytes().orElse(\"\"));\n}\n" + }, + { + "label": "get_file", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.EnvironmentFile;\nimport com.google.genai.gaos.models.operations.GetEnvironmentFilesRequest;\nimport com.google.genai.gaos.models.environments.GetEnvironmentFilesResponse;\n\nClient client = new Client();\n\n\ncom.google.genai.gaos.models.operations.GetEnvironmentFilesResponse response =\n client\n .environments\n .files()\n .list(GetEnvironmentFilesRequest.builder().environment(envId).path(\"main.py\").build());\nGetEnvironmentFilesResponse filesResponse =\n response.getEnvironmentFilesResponse().orElseThrow();\nfor (EnvironmentFile file : filesResponse.files().orElse(List.of())) {\n System.out.println(file.name().orElse(\"\") + \" \" + file.sizeBytes().orElse(\"\"));\n}\n" + }, + { + "label": "list_files", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n\n res, err := client.Environments.Files.List(ctx, operations.GetEnvironmentFilesRequest{\n Environment: envID,\n Path: \"src\",\n })\n if err != nil {\n log.Fatal(err)\n }\n\n if res.GetEnvironmentFilesResponse != nil {\n for _, file := range res.GetEnvironmentFilesResponse.Files {\n name := \"\"\n if file.Name != nil {\n name = *file.Name\n }\n fileType := \"\"\n if file.Type != nil {\n fileType = string(*file.Type)\n }\n var size int64\n if file.SizeBytes != nil {\n size = *file.SizeBytes\n }\n fmt.Println(name, fileType, size)\n }\n }\n}\n" + }, + { + "label": "get_file", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n\n res, err := client.Environments.Files.List(ctx, operations.GetEnvironmentFilesRequest{\n Environment: envID,\n Path: \"main.py\",\n })\n if err != nil {\n log.Fatal(err)\n }\n\n if res.GetEnvironmentFilesResponse != nil {\n for _, file := range res.GetEnvironmentFilesResponse.Files {\n name := \"\"\n if file.Name != nil {\n name = *file.Name\n }\n var size int64\n if file.SizeBytes != nil {\n size = *file.SizeBytes\n }\n fmt.Println(name, size)\n }\n }\n}\n" + } + ] + } + }, + "/{api_version}/environments/{id}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "delete": { + "operationId": "DeleteEnvironment", + "description": "Deletes an environment.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource ID segment making up resource `name`. It identifies the resource\nwithin its parent collection as described in https://google.aip.dev/122.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Empty" + } + } + } + } + }, + "tags": [ + "environments" + ], + "x-codeSamples": [ + { + "label": "delete", + "lang": "sh", + "source": "curl -X DELETE https://generativelanguage.googleapis.com/v1beta/environments/env_abc123 \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "delete", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\nclient.environments.delete(id=created.id)\nprint(\"Environment deleted successfully.\")\n" + }, + { + "label": "delete", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nawait ai.environments.delete(created.id);\nconsole.log('Environment deleted successfully.');\n" + }, + { + "label": "delete", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.Environment;\n\nClient client = new Client();\n\n\nclient.environments.deleteEnvironment(envId);\nSystem.out.println(\n \"com.google.genai.gaos.models.environments.Environment deleted successfully.\");\n" + }, + { + "label": "delete", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n\n _, err = client.Environments.DeleteEnvironment(ctx, operations.DeleteEnvironmentRequest{\n ID: envID,\n })\n if err != nil {\n log.Fatal(err)\n }\n fmt.Println(\"Environment deleted successfully.\")\n}\n" + } + ] + }, + "get": { + "operationId": "GetEnvironment", + "description": "Gets an environment.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource ID segment making up resource `name`. It identifies the resource\nwithin its parent collection as described in https://google.aip.dev/122.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Environment" + } + } + } + } + }, + "tags": [ + "environments" + ], + "x-codeSamples": [ + { + "label": "get", + "lang": "sh", + "source": "curl -X GET https://generativelanguage.googleapis.com/v1beta/environments/env_abc123 \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "get", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\nenvironment = client.environments.get(id=created.id)\nprint(environment.id)\n" + }, + { + "label": "get", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nconst environment = await ai.environments.get(created.id);\nconsole.log(environment.id);\n" + }, + { + "label": "get", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.environments.Environment;\n\nClient client = new Client();\n\n\ncom.google.genai.gaos.models.environments.Environment environment =\n client.environments.getEnvironment(envId).environment().orElseThrow();\nSystem.out.println(environment.id().orElse(\"\"));\n" + }, + { + "label": "get", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := interactions.New()\n\n\n res, err := client.Environments.GetEnvironment(ctx, operations.GetEnvironmentRequest{\n ID: envID,\n })\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Environment != nil && res.Environment.ID != \"\" {\n fmt.Println(res.Environment.ID)\n }\n}\n" + } + ] + } + }, + "/{api_version}/interactions": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "post": { + "operationId": "CreateInteraction", + "description": "Creates a new interaction.", + "requestBody": { + "description": "The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreateAgentInteractionParams" + }, + { + "$ref": "#/components/schemas/CreateModelInteractionParams" + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "Successful operation", + "content": { + "application/json": { + "examples": { + "antigravity": { + "summary": "Antigravity Agent", + "value": { + "agent": "antigravity-preview-05-2026", + "created": "2025-11-26T12:22:47Z", + "environment_id": "env_abc123", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "I've summarized the top 5 Hacker News stories and saved the results to /workspace/summary.md." + } + ] + } + ], + "updated": "2025-11-26T12:22:47Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 50 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 50, + "total_output_tokens": 500, + "total_thought_tokens": 200, + "total_tokens": 750, + "total_tool_use_tokens": 0 + } + } + }, + "deep_research": { + "summary": "Deep Research", + "value": { + "agent": "deep-research-pro-preview-12-2025", + "created": "2025-11-26T12:22:47Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "Here is a comprehensive research report on the current state of cancer research..." + } + ] + } + ], + "updated": "2025-11-26T12:22:47Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 20 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 20, + "total_output_tokens": 1000, + "total_thought_tokens": 500, + "total_tokens": 1520, + "total_tool_use_tokens": 0 + } + } + }, + "function_calling": { + "summary": "Function Calling", + "value": { + "created": "2025-11-26T12:22:47Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "requires_action", + "steps": [ + { + "name": "get_weather", + "type": "function_call", + "arguments": { + "location": "Boston, MA" + }, + "id": "gth23981" + } + ], + "updated": "2025-11-26T12:22:47Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 100 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 100, + "total_output_tokens": 25, + "total_thought_tokens": 0, + "total_tokens": 125, + "total_tool_use_tokens": 50 + } + } + }, + "multi_turn": { + "summary": "Multi-turn", + "value": { + "created": "2025-11-26T12:22:47Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "The capital of France is Paris." + } + ] + } + ], + "updated": "2025-11-26T12:22:47Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 50 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 50, + "total_output_tokens": 10, + "total_thought_tokens": 0, + "total_tokens": 60, + "total_tool_use_tokens": 0 + } + } + }, + "multimodal_image": { + "summary": "Image Input", + "value": { + "created": "2025-11-26T12:22:47Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "A white humanoid robot with glowing blue eyes stands holding a red skateboard." + } + ] + } + ], + "updated": "2025-11-26T12:22:47Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 10 + }, + { + "modality": "image", + "tokens": 258 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 268, + "total_output_tokens": 20, + "total_thought_tokens": 0, + "total_tokens": 288, + "total_tool_use_tokens": 0 + } + } + }, + "reuse_env": { + "summary": "Reuse Environment", + "value": { + "agent": "antigravity-preview-05-2026", + "created": "2025-11-26T12:23:00Z", + "environment_id": "env_abc123", + "id": "v1_Chd2ZTJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODkwMTIzNDU2Nzg", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "I've updated /workspace/hello.py to accept a name argument and greet the user." + } + ] + } + ], + "updated": "2025-11-26T12:23:00Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 80 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 80, + "total_output_tokens": 200, + "total_thought_tokens": 100, + "total_tokens": 380, + "total_tool_use_tokens": 0 + } + } + }, + "simple": { + "summary": "Simple Request", + "value": { + "created": "2025-11-26T12:25:15Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "Hello! I'm functioning perfectly and ready to assist you.\n\nHow are you doing today?" + } + ] + } + ], + "updated": "2025-11-26T12:25:15Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 7 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 7, + "total_output_tokens": 20, + "total_thought_tokens": 22, + "total_tokens": 49, + "total_tool_use_tokens": 0 + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/Interaction" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/InteractionSseStreamEvent" + }, + "x-speakeasy-sse-sentinel": "[DONE]" + } + } + }, + "4XX": { + "description": "Error creating interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + }, + "5XX": { + "description": "Error creating interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + } + }, + "summary": "Creating an interaction", + "x-speakeasy-exports": [ + { + "name": "InteractionCreateParams", + "group": "interactions", + "representation": "input" + } + ], + "x-speakeasy-group": "interactions", + "x-speakeasy-name-override": "create", + "x-codeSamples": [ + { + "label": "simple", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"input\": \"Hello, how are you?\"\n }'\n" + }, + { + "label": "multi_turn", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"input\": [\n { \"type\": \"user_input\", \"content\": [{ \"type\": \"text\", \"text\": \"Hello!\" }] },\n { \"type\": \"model_output\", \"content\": [{ \"type\": \"text\", \"text\": \"Hi there! How can I help you today?\" }] },\n { \"type\": \"user_input\", \"content\": [{ \"type\": \"text\", \"text\": \"What is the capital of France?\" }] }\n ]\n }'\n" + }, + { + "label": "multimodal_image", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"input\": [\n {\n \"type\": \"text\",\n \"text\": \"What is in this picture?\"\n },\n {\n \"type\": \"image\",\n \"data\": \"BASE64_ENCODED_IMAGE\",\n \"mime_type\": \"image/png\"\n }\n ]\n }'\n" + }, + { + "label": "function_calling", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"get_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\"\n }\n },\n \"required\": [\n \"location\"\n ]\n }\n }\n ],\n \"input\": \"What is the weather like in Boston, MA?\"\n }'\n" + }, + { + "label": "deep_research", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agent\": \"deep-research-pro-preview-12-2025\",\n \"input\": \"Find a cure to cancer\",\n \"background\": true\n }'\n" + }, + { + "label": "antigravity", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agent\": \"antigravity-preview-05-2026\",\n \"input\": \"Read Hacker News, summarize the top 5 stories, and save results as a markdown file.\",\n \"environment\": \"remote\"\n }'\n" + }, + { + "label": "reuse_env", + "lang": "sh", + "source": "# Step 1: Create an interaction with a fresh remote environment.\nRESPONSE=$(curl -s -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Api-Revision: 2026-05-20\" \\\n -d '{\n \"agent\": \"antigravity-preview-05-2026\",\n \"input\": \"Write a hello world script at /workspace/hello.py.\",\n \"environment\": \"remote\"\n }')\nINTERACTION_ID=$(echo \"$RESPONSE\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['id'])\")\nENV_ID=$(echo \"$RESPONSE\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['environment_id'])\")\n\n# Step 2: Reuse the same environment in a follow-up interaction.\ncurl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"agent\\\": \\\"antigravity-preview-05-2026\\\",\n \\\"input\\\": \\\"Modify the script to accept a name argument and greet the user.\\\",\n \\\"environment\\\": \\\"$ENV_ID\\\",\n \\\"previous_interaction_id\\\": \\\"$INTERACTION_ID\\\"\n }\"\n" + }, + { + "label": "with_sources", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agent\": \"antigravity-preview-05-2026\",\n \"input\": \"List all files under /workspace and summarize what you find.\",\n \"environment\": {\n \"type\": \"remote\",\n \"sources\": [\n {\n \"type\": \"repository\",\n \"source\": \"https://github.com/octocat/Spoon-Knife\",\n \"target\": \"/workspace/repo\"\n },\n {\n \"type\": \"inline\",\n \"content\": \"Focus on Python files only.\",\n \"target\": \"/workspace/notes.txt\"\n }\n ]\n }\n }'\n" + }, + { + "label": "custom_agent", + "lang": "sh", + "source": "# Step 1: Create a custom agent.\ncurl -X POST https://generativelanguage.googleapis.com/v1beta/agents \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"code-reviewer\",\n \"base_agent\": \"antigravity-preview-05-2026\",\n \"system_instruction\": \"You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.\",\n \"base_environment\": {\n \"type\": \"remote\",\n \"sources\": [{\n \"type\": \"repository\",\n \"source\": \"https://github.com/octocat/Spoon-Knife\",\n \"target\": \"/workspace/repo\"\n }]\n }\n }'\n\n# Step 2: Use the custom agent.\ncurl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agent\": \"code-reviewer\",\n \"input\": \"Review the latest changes in /workspace/repo/src and file a summary.\",\n \"environment\": \"remote\"\n }'\n" + }, + { + "label": "simple", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\ninteraction = client.interactions.create(\n model=\"gemini-flash-latest\",\n input=\"Hello, how are you?\",\n)\nprint(interaction.output_text)\n" + }, + { + "label": "multi_turn", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n input=[\n {\n \"type\": \"user_input\",\n \"content\": [{\"type\": \"text\", \"text\": \"Hello!\"}],\n },\n {\n \"type\": \"model_output\",\n \"content\": [{\n \"type\": \"text\",\n \"text\": \"Hi there! How can I help you today?\",\n }],\n },\n {\n \"type\": \"user_input\",\n \"content\": [\n {\"type\": \"text\", \"text\": \"What is the capital of France?\"}\n ],\n },\n ],\n)\nprint(response.output_text)\n" + }, + { + "label": "multimodal_image", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n input=[\n {\"type\": \"text\", \"text\": \"What is in this picture?\"},\n {\n \"type\": \"image\",\n \"data\": \"BASE64_ENCODED_IMAGE\",\n \"mime_type\": \"image/png\",\n },\n ],\n)\nprint(response.output_text)\n" + }, + { + "label": "function_calling", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[{\n \"type\": \"function\",\n \"name\": \"get_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": (\n \"The city and state, e.g. San Francisco, CA\"\n ),\n }\n },\n \"required\": [\"location\"],\n },\n }],\n input=\"What is the weather like in Boston, MA?\",\n)\nprint(response.steps[-1])\n" + }, + { + "label": "deep_research", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\ninteraction = client.interactions.create(\n agent=\"deep-research-pro-preview-12-2025\",\n input=\"find a cure to cancer\",\n background=True,\n)\nprint(interaction.status)\n" + }, + { + "label": "antigravity", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\ninteraction = client.interactions.create(\n agent=\"antigravity-preview-05-2026\",\n input=(\n \"Read Hacker News, summarize the top 5 stories, and save results as\"\n \" a markdown file.\"\n ),\n environment=\"remote\",\n)\nprint(interaction.output_text)\n" + }, + { + "label": "reuse_env", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n# Step 1: Create an interaction with a fresh remote environment.\ninteraction = client.interactions.create(\n agent=\"antigravity-preview-05-2026\",\n input=\"Write a hello world script at /workspace/hello.py.\",\n environment=\"remote\",\n)\nprint(f\"Environment ID: {interaction.environment_id}\")\n\n# Step 2: Reuse the same environment in a follow-up interaction.\ninteraction_2 = client.interactions.create(\n agent=\"antigravity-preview-05-2026\",\n input=\"Modify the script to accept a name argument and greet the user.\",\n environment=interaction.environment_id,\n previous_interaction_id=interaction.id,\n)\nprint(interaction_2.output_text)\n" + }, + { + "label": "with_sources", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\ninteraction = client.interactions.create(\n agent=\"antigravity-preview-05-2026\",\n input=\"List all files under /workspace and summarize what you find.\",\n environment={\n \"type\": \"remote\",\n \"sources\": [\n {\n \"type\": \"repository\",\n \"source\": \"https://github.com/octocat/Spoon-Knife\",\n \"target\": \"/workspace/repo\",\n },\n {\n \"type\": \"inline\",\n \"content\": \"Focus on Python files only.\",\n \"target\": \"/workspace/notes.txt\",\n },\n ],\n },\n)\nprint(interaction.output_text)\n" + }, + { + "label": "custom_agent", + "lang": "python", + "source": "import uuid\nfrom google import genai\n\nclient = genai.Client()\n\n# Step 1: Create a custom agent.\nagent_id = f\"code-reviewer-{uuid.uuid4().hex[:8]}\"\nclient.agents.create(\n id=agent_id,\n base_agent=\"antigravity-preview-05-2026\",\n system_instruction=(\n \"You are a senior code reviewer. Check every file for bugs, style\"\n \" issues, and security vulnerabilities.\"\n ),\n base_environment={\n \"type\": \"remote\",\n \"sources\": [{\n \"type\": \"repository\",\n \"source\": \"https://github.com/octocat/Spoon-Knife\",\n \"target\": \"/workspace/repo\",\n }],\n },\n)\n\n# Step 2: Use the custom agent.\nresult = client.interactions.create(\n agent=agent_id,\n input=(\n \"Review the latest changes in /workspace/repo/src and file a\"\n \" summary.\"\n ),\n environment=\"remote\",\n)\nprint(result.output_text)\n" + }, + { + "label": "simple", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n input: 'Hello, how are you?',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "multi_turn", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n input: [\n {type: 'user_input', content: [{type: 'text', text: 'Hello'}]},\n {\n type: 'model_output',\n content: [\n {type: 'text', text: 'Hi there! How can I help you today?'},\n ],\n },\n {\n type: 'user_input',\n content: [{type: 'text', text: 'What is the capital of France?'}],\n },\n ],\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "multimodal_image", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n input: [\n {type: 'text', text: 'What is in this picture?'},\n {type: 'image', data: 'BASE64_ENCODED_IMAGE', mime_type: 'image/png'},\n ],\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "function_calling", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [\n {\n type: 'function',\n name: 'get_weather',\n description: 'Get the current weather in a given location',\n parameters: {\n type: 'object',\n properties: {\n location: {\n type: 'string',\n description: 'The city and state, e.g. San Francisco, CA',\n },\n },\n required: ['location'],\n },\n },\n ],\n input: 'What is the weather like in Boston, MA?',\n});\nconsole.log(interaction.steps.at(-1));\n" + }, + { + "label": "deep_research", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n agent: 'deep-research-pro-preview-12-2025',\n input: 'find a cure to cancer',\n background: true,\n});\nconsole.log(interaction.status);\n" + }, + { + "label": "antigravity", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n agent: 'antigravity-preview-05-2026',\n input:\n 'Read Hacker News, summarize the top 5 stories, and save results as a markdown file.',\n environment: 'remote',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "reuse_env", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n// Step 1: Create an interaction with a fresh remote environment.\nconst interaction = await ai.interactions.create({\n agent: 'antigravity-preview-05-2026',\n input: 'Write a hello world script at /workspace/hello.py.',\n environment: 'remote',\n});\nconsole.log(`Environment ID: ${interaction.environment_id}`);\n\n// Step 2: Reuse the same environment in a follow-up interaction.\nconst interaction2 = await ai.interactions.create({\n agent: 'antigravity-preview-05-2026',\n input: 'Modify the script to accept a name argument and greet the user.',\n environment: interaction.environment_id,\n previous_interaction_id: interaction.id,\n});\nconsole.log(interaction2.output_text);\n" + }, + { + "label": "with_sources", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n agent: 'antigravity-preview-05-2026',\n input: 'List all files under /workspace and summarize what you find.',\n environment: {\n type: 'remote',\n sources: [\n {\n type: 'repository',\n source: 'https://github.com/octocat/Spoon-Knife',\n target: '/workspace/repo',\n },\n {\n type: 'inline',\n content: 'Focus on Python files only.',\n target: '/workspace/notes.txt',\n },\n ],\n },\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "custom_agent", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n// Step 1: Create a custom agent.\nconst agentId = `code-reviewer-${crypto.randomUUID().slice(0, 8)}`;\nawait ai.agents.create({\n id: agentId,\n base_agent: 'antigravity-preview-05-2026',\n system_instruction:\n 'You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.',\n base_environment: {\n type: 'remote',\n sources: [\n {\n type: 'repository',\n source: 'https://github.com/octocat/Spoon-Knife',\n target: '/workspace/repo',\n },\n ],\n },\n});\n\n// Step 2: Use the custom agent.\nconst result = await ai.interactions.create({\n agent: agentId,\n input:\n 'Review the latest changes in /workspace/repo/src and file a summary.',\n environment: 'remote',\n});\nconsole.log(result.output_text);\n" + }, + { + "label": "simple", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .input(InteractionsInput.of(\"Hello, how are you?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "multi_turn", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.ModelOutputStep;\nimport com.google.genai.gaos.models.interactions.Step;\nimport com.google.genai.gaos.models.interactions.TextContent;\nimport com.google.genai.gaos.models.interactions.UserInputStep;\n\nClient client = new Client();\nList conversation =\n List.of(\n UserInputStep.builder()\n .content(List.of(TextContent.builder().text(\"Hello!\").build()))\n .build(),\n ModelOutputStep.builder()\n .content(\n List.of(\n TextContent.builder().text(\"Hi there! How can I help you today?\").build()))\n .build(),\n UserInputStep.builder()\n .content(\n List.of(TextContent.builder().text(\"What is the capital of France?\").build()))\n .build());\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .input(InteractionsInput.ofStep(conversation))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "multimodal_image", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.Content;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.ImageContent;\nimport com.google.genai.gaos.models.interactions.ImageContentMimeType;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.TextContent;\n\nClient client = new Client();\nList content =\n List.of(\n TextContent.builder().text(\"What is in this picture?\").build(),\n ImageContent.builder()\n .data(\"BASE64_ENCODED_IMAGE\")\n .mimeType(ImageContentMimeType.IMAGE_PNG)\n .build());\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .input(InteractionsInput.ofContent(content))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "function_calling", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Function;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.Step;\n\nClient client = new Client();\nMap parameters =\n Map.of(\n \"type\", \"object\",\n \"properties\",\n Map.of(\n \"location\",\n Map.of(\n \"type\", \"string\",\n \"description\", \"The city and state, e.g. San Francisco, CA\")),\n \"required\", List.of(\"location\"));\nFunction functionTool =\n Function.builder()\n .name(\"get_weather\")\n .description(\"Get the current weather in a given location\")\n .parameters(parameters)\n .build();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(functionTool))\n .input(InteractionsInput.of(\"What is the weather like in Boston, MA?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nList steps = interaction.steps().orElse(List.of());\nif (!steps.isEmpty()) {\n System.out.println(steps.get(steps.size() - 1));\n}\n" + }, + { + "label": "deep_research", + "lang": "java", + "source": "import com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionStatus;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nCreateAgentInteraction params =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"deep-research-pro-preview-12-2025\"))\n .input(InteractionsInput.of(\"find a cure to cancer\"))\n .background(true)\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.status().map(InteractionStatus::value).orElse(\"\"));\n" + }, + { + "label": "antigravity", + "lang": "java", + "source": "import com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nCreateAgentInteraction params =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"antigravity-preview-05-2026\"))\n .input(\n InteractionsInput.of(\n \"Read Hacker News, summarize the top 5 stories, and save results as a markdown\"\n + \" file.\"))\n .environment(CreateAgentInteractionEnvironment.of(\"remote\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "reuse_env", + "lang": "java", + "source": "import com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.environments.Environment;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.Step;\n\nClient client = new Client();\n\n// Step 1: Create an interaction with a fresh remote environment.\nCreateAgentInteraction params1 =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"antigravity-preview-05-2026\"))\n .input(InteractionsInput.of(\"Write a hello world script at /workspace/hello.py.\"))\n .environment(CreateAgentInteractionEnvironment.of(\"remote\"))\n .build();\nCreateInteractionResponse response1 =\n client.interactions.create(CreateInteractionRequestBody.of(params1));\nInteraction interaction1 =\n response1.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(\"Environment ID: \" + interaction1.environmentId().orElse(\"\"));\n\n// Step 2: Reuse the same environment in a follow-up interaction.\nCreateAgentInteraction params2 =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"antigravity-preview-05-2026\"))\n .input(\n InteractionsInput.of(\n \"Modify the script to accept a name argument and greet the user.\"))\n .environment(\n CreateAgentInteractionEnvironment.of(interaction1.environmentId().orElse(\"\")))\n .previousInteractionId(interaction1.id().orElse(null))\n .build();\nCreateInteractionResponse response2 =\n client.interactions.create(CreateInteractionRequestBody.of(params2));\nInteraction interaction2 =\n response2.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction2.outputText().orElse(\"\"));\n" + }, + { + "label": "with_sources", + "lang": "java", + "source": "import com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.environments.Environment;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.Source;\nimport com.google.genai.gaos.models.interactions.SourceType;\n\nClient client = new Client();\ncom.google.genai.gaos.models.interactions.Environment env =\n com.google.genai.gaos.models.interactions.Environment.builder()\n .sources(\n List.of(\n Source.builder()\n .type(SourceType.REPOSITORY)\n .source(\"https://github.com/octocat/Spoon-Knife\")\n .target(\"/workspace/repo\")\n .build(),\n Source.builder()\n .type(SourceType.INLINE)\n .content(\"Focus on Python files only.\")\n .target(\"/workspace/notes.txt\")\n .build()))\n .build();\nCreateAgentInteraction params =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"antigravity-preview-05-2026\"))\n .input(\n InteractionsInput.of(\n \"List all files under /workspace and summarize what you find.\"))\n .environment(CreateAgentInteractionEnvironment.of(env))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "custom_agent", + "lang": "java", + "source": "import com.google.genai.gaos.models.agents.Agent;\nimport com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.gaos.models.agents.BaseEnvironment;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.environments.Environment;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.Source;\nimport com.google.genai.gaos.models.interactions.SourceType;\nimport com.google.genai.gaos.models.interactions.Step;\n\nClient client = new Client();\n\n// Step 1: Create a custom agent.\nString agentId = \"code-reviewer-\" + UUID.randomUUID().toString().substring(0, 8);\ncom.google.genai.gaos.models.interactions.Environment baseEnv =\n com.google.genai.gaos.models.interactions.Environment.builder()\n .sources(\n List.of(\n Source.builder()\n .type(SourceType.REPOSITORY)\n .source(\"https://github.com/octocat/Spoon-Knife\")\n .target(\"/workspace/repo\")\n .build()))\n .build();\nAgent customAgent =\n Agent.builder()\n .id(agentId)\n .baseAgent(\"antigravity-preview-05-2026\")\n .systemInstruction(\n \"You are a senior code reviewer. Check every file for bugs, style issues, and\"\n + \" security vulnerabilities.\")\n .baseEnvironment(BaseEnvironment.of(baseEnv))\n .build();\nclient.agents.create(customAgent);\n\n// Step 2: Use the custom agent.\nCreateAgentInteraction params =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(agentId))\n .input(\n InteractionsInput.of(\n \"Review the latest changes in /workspace/repo/src and file a summary.\"))\n .environment(CreateAgentInteractionEnvironment.of(\"remote\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "simple", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Hello, how are you?\")),\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + }, + { + "label": "multi_turn", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n history := []gaos_interactions.Step{\n gaos_interactions.NewStep(gaos_interactions.UserInputStep{\n Content: []gaos_interactions.Content{\n gaos_interactions.NewContent(gaos_interactions.TextContent{\n Text: \"Hello!\",\n }),\n },\n }),\n gaos_interactions.NewStep(gaos_interactions.ModelOutputStep{\n Content: []gaos_interactions.Content{\n gaos_interactions.NewContent(gaos_interactions.TextContent{\n Text: \"Hi there! How can I help you today?\",\n }),\n },\n }),\n gaos_interactions.NewStep(gaos_interactions.UserInputStep{\n Content: []gaos_interactions.Content{\n gaos_interactions.NewContent(gaos_interactions.TextContent{\n Text: \"What is the capital of France?\",\n }),\n },\n }),\n }\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(history)),\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + }, + { + "label": "multimodal_image", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n contents := []gaos_interactions.Content{\n gaos_interactions.NewContent(gaos_interactions.TextContent{\n Text: \"What is in this picture?\",\n }),\n gaos_interactions.NewContent(gaos_interactions.ImageContent{\n Data: genai.Ptr(\"BASE64_ENCODED_IMAGE\"),\n MimeType: gaos_interactions.ImageContentMimeTypeImagePng.ToPointer(),\n }),\n }\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(contents)),\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + }, + { + "label": "function_calling", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n function := gaos_interactions.Function{\n Name: genai.Ptr(\"get_weather\"),\n Description: genai.Ptr(\"Get the current weather in a given location\"),\n Parameters: map[string]any{\n \"type\": \"object\",\n \"properties\": map[string]any{\n \"location\": map[string]any{\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\",\n },\n },\n \"required\": []string{\"location\"},\n },\n }\n\n tool := gaos_interactions.NewTool(function)\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"What is the weather like in Boston, MA?\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil {\n for _, step := range res.Interaction.Steps {\n if step.FunctionCallStep != nil {\n fmt.Println(\"Function Call:\", step.FunctionCallStep.Name)\n fmt.Println(\"Arguments:\", step.FunctionCallStep.Arguments)\n }\n }\n }\n}\n" + }, + { + "label": "deep_research", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(\"deep-research-pro-preview-12-2025\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"find a cure to cancer\")),\n Background: genai.Ptr(true),\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil {\n fmt.Println(res.Interaction.Status)\n }\n}\n" + }, + { + "label": "antigravity", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(\"antigravity-preview-05-2026\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Read Hacker News, summarize the top 5 stories, and save results as a markdown file.\")),\n Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(\"remote\")),\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + }, + { + "label": "reuse_env", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n // Step 1: Create an interaction with a fresh remote environment.\n body1 := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(\"antigravity-preview-05-2026\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Write a hello world script at /workspace/hello.py.\")),\n Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(\"remote\")),\n })\n\n res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body1})\n if err != nil {\n log.Fatal(err)\n }\n\n if res1.Interaction == nil || res1.Interaction.EnvironmentID == nil {\n log.Fatal(\"No environment ID returned\")\n }\n fmt.Printf(\"Environment ID: %s\\n\", *res1.Interaction.EnvironmentID)\n\n // Step 2: Reuse the same environment in a follow-up interaction.\n body2 := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(\"antigravity-preview-05-2026\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Modify the script to accept a name argument and greet the user.\")),\n Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(*res1.Interaction.EnvironmentID)),\n PreviousInteractionID: res1.Interaction.ID,\n })\n\n res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body2})\n if err != nil {\n log.Fatal(err)\n }\n\n if res2.Interaction != nil && res2.Interaction.OutputText != nil {\n fmt.Println(*res2.Interaction.OutputText)\n }\n}\n" + }, + { + "label": "with_sources", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n env := gaos_interactions.Environment{\n Sources: []gaos_interactions.Source{\n {\n Type: genai.Ptr(gaos_interactions.SourceTypeRepository),\n Source: genai.Ptr(\"https://github.com/octocat/Spoon-Knife\"),\n Target: genai.Ptr(\"/workspace/repo\"),\n },\n {\n Type: genai.Ptr(gaos_interactions.SourceTypeInline),\n Content: genai.Ptr(\"Focus on Python files only.\"),\n Target: genai.Ptr(\"/workspace/notes.txt\"),\n },\n },\n }\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(\"antigravity-preview-05-2026\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"List all files under /workspace and summarize what you find.\")),\n Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(env)),\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + }, + { + "label": "custom_agent", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\n \"google.golang.org/genai\"\n gaos_agents \"google.golang.org/genai/interactions/models/agents\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n // Step 1: Create a custom agent.\n agentID := fmt.Sprintf(\"code-reviewer-%d\", time.Now().UnixNano())\n baseEnv := gaos_interactions.Environment{\n Sources: []gaos_interactions.Source{\n {\n Type: genai.Ptr(gaos_interactions.SourceTypeRepository),\n Source: genai.Ptr(\"https://github.com/octocat/Spoon-Knife\"),\n Target: genai.Ptr(\"/workspace/repo\"),\n },\n },\n }\n\n _, err = client.Agents.Create(ctx, operations.CreateAgentRequest{\n Body: gaos_agents.Agent{\n ID: genai.Ptr(agentID),\n BaseAgent: genai.Ptr(\"antigravity-preview-05-2026\"),\n SystemInstruction: genai.Ptr(\"You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.\"),\n BaseEnvironment: genai.Ptr(gaos_agents.NewBaseEnvironment(baseEnv)),\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n\n // Step 2: Use the custom agent.\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateAgentInteraction{\n Agent: gaos_interactions.AgentOption(agentID),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Review the latest changes in /workspace/repo/src and file a summary.\")),\n Environment: genai.Ptr(gaos_interactions.NewCreateAgentInteractionEnvironment(\"remote\")),\n })\n\n res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{Body: body})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + } + }, + "/{api_version}/interactions/{id}": { + "delete": { + "operationId": "deleteInteraction", + "description": "Deletes the interaction by id.", + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + }, + { + "name": "id", + "in": "path", + "description": "The unique identifier of the interaction to delete.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "interactionsId", + "in": "path", + "description": "Required. The name of the interaction to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successful deletion of the interaction." + }, + "4XX": { + "description": "Error deleting interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + }, + "5XX": { + "description": "Error deleting interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + } + }, + "summary": "Deleting an interaction", + "x-speakeasy-exports": [ + { + "name": "InteractionDeleteParams", + "group": "interactions", + "representation": "input" + } + ], + "x-speakeasy-group": "interactions", + "x-speakeasy-name-override": "delete", + "x-codeSamples": [ + { + "label": "delete", + "lang": "sh", + "source": "curl -X DELETE \"https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "delete", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\nclient.interactions.delete(id=created.id)\nprint(\"Interaction deleted successfully.\")\n" + }, + { + "label": "delete", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nawait ai.interactions.delete(created.id);\nconsole.log('Interaction deleted successfully.');\n" + }, + { + "label": "delete", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.Interaction;\n\nClient client = new Client();\n\n\nclient.interactions.delete(interactionId);\nSystem.out.println(\"Interaction deleted successfully.\");\n" + }, + { + "label": "delete", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n\n req := operations.DeleteInteractionRequest{\n ID: interactionID,\n }\n\n _, err = client.Interactions.Delete(\n ctx,\n req,\n )\n if err != nil {\n log.Fatal(err)\n }\n\n fmt.Println(\"Interaction deleted successfully.\")\n}\n" + } + ] + }, + "get": { + "operationId": "getInteractionById", + "description": "Retrieves the full details of a single interaction based on its `Interaction.id`.", + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + }, + { + "name": "id", + "in": "path", + "description": "The unique identifier of the interaction to retrieve.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "last_event_id", + "in": "query", + "description": "Optional. If set, resumes the interaction stream from the next chunk after the event marked by the event id. Can only be used if `stream` is true.", + "schema": { + "type": "string" + } + }, + { + "name": "stream", + "in": "query", + "description": "If set to true, the generated content will be streamed incrementally.", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "Successful retrieval of the interaction.", + "content": { + "application/json": { + "examples": { + "get": { + "summary": "Get Interaction", + "value": { + "created": "2025-11-26T12:25:15Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "I'm doing great, thank you for asking! How can I help you today?" + } + ] + } + ], + "updated": "2025-11-26T12:25:15Z" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Interaction" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/InteractionSseStreamEvent" + }, + "x-speakeasy-sse-sentinel": "[DONE]" + } + } + }, + "4XX": { + "description": "Error getting interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + }, + "5XX": { + "description": "Error getting interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + } + }, + "summary": "Retrieving an interaction", + "x-speakeasy-exports": [ + { + "name": "InteractionGetParams", + "group": "interactions", + "representation": "input" + } + ], + "x-speakeasy-group": "interactions", + "x-speakeasy-name-override": "get", + "x-speakeasy-sse-overload": true, + "x-codeSamples": [ + { + "label": "get", + "lang": "sh", + "source": "curl -X GET \"https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Api-Revision: 2026-05-20\"\n" + }, + { + "label": "get", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n\ninteraction = client.interactions.get(id=created.id)\nprint(interaction.status)\n" + }, + { + "label": "get", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n\nconst interaction = await ai.interactions.get(created.id);\nconsole.log(interaction.status);\n" + }, + { + "label": "get", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.GetInteractionByIdRequest;\nimport com.google.genai.gaos.models.operations.GetInteractionByIdResponse;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionStatus;\n\nClient client = new Client();\n\n\nGetInteractionByIdResponse getResponse =\n client.interactions.get(new GetInteractionByIdRequest(interactionId));\nInteraction interaction =\n getResponse\n .interaction()\n .orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.status().map(InteractionStatus::value).orElse(\"\"));\n" + }, + { + "label": "get", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n\n interaction, err := client.Interactions.Get(ctx, operations.GetInteractionByIDRequest{\n ID: *created.Interaction.ID,\n })\n if err != nil {\n log.Fatal(err)\n }\n\n if interaction.Interaction != nil {\n fmt.Println(interaction.Interaction.Status)\n }\n}\n" + } + ] + } + }, + "/{api_version}/interactions/{id}/cancel": { + "post": { + "operationId": "cancelInteractionById", + "description": "Cancels an interaction by id. This only applies to background interactions that are still running.", + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + }, + { + "name": "id", + "in": "path", + "description": "The unique identifier of the interaction to cancel.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successful operation", + "content": { + "application/json": { + "examples": { + "cancel": { + "summary": "Cancel Interaction", + "value": { + "created": "2025-11-26T12:25:15Z", + "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "cancelled", + "updated": "2025-11-26T12:25:15Z" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Interaction" + } + } + } + }, + "4XX": { + "description": "Error cancelling interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + }, + "5XX": { + "description": "Error cancelling interaction", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "$ref": "#/components/schemas/Error" + } + }, + "required": [ + "error" + ] + } + } + } + } + }, + "summary": "Canceling an interaction", + "x-speakeasy-group": "interactions", + "x-speakeasy-name-override": "cancel", + "x-codeSamples": [ + { + "label": "cancel", + "lang": "sh", + "source": "curl -X POST \"https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID/cancel\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "cancel", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n# Start a background interaction so it stays in-progress.\ncreated = client.interactions.create(\n model=\"gemini-flash-latest\",\n input=\"Write a long essay about the history of computing.\",\n tools=[{\"type\": \"computer_use\"}],\n background=True,\n)\n\n# Cancel the in-progress interaction.\ninteraction = client.interactions.cancel(id=created.id)\nprint(interaction.status)\n" + }, + { + "label": "cancel", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n// Start a background interaction so it stays in-progress.\nconst created = await ai.interactions.create({\n model: 'gemini-flash-latest',\n input: 'Write a long essay about the history of computing.',\n tools: [{type: 'computer_use'}],\n background: true,\n});\n\n// Cancel the in-progress interaction.\nconst interaction = await ai.interactions.cancel(created.id);\nconsole.log(interaction.status);\n" + }, + { + "label": "cancel", + "lang": "java", + "source": "import com.google.genai.gaos.models.operations.CancelInteractionByIdResponse;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.ComputerUse;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionStatus;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\n\n// Start a background interaction so it stays in-progress.\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .input(InteractionsInput.of(\"Write a long essay about the history of computing.\"))\n .tools(List.of(new ComputerUse()))\n .background(true)\n .build();\nCreateInteractionResponse created =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nString interactionId = created.interaction().flatMap(Interaction::id).orElseThrow();\n\n// Cancel the in-progress interaction.\nCancelInteractionByIdResponse cancelResponse = client.interactions.cancel(interactionId);\nInteraction interaction =\n cancelResponse\n .interaction()\n .orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.status().map(InteractionStatus::value).orElse(\"\"));\n" + }, + { + "label": "cancel", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n\n req := operations.CancelInteractionByIDRequest{\n ID: interactionID,\n }\n\n res, err := client.Interactions.Cancel(\n ctx,\n req,\n )\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil {\n fmt.Println(res.Interaction.Status)\n }\n}\n" + } + ] + } + }, + "/{api_version}/triggers": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListTriggers", + "description": "Lists triggers for a project.", + "parameters": [ + { + "name": "filter", + "in": "query", + "description": "Optional. Filter expression (e.g., by state).", + "schema": { + "type": "string" + } + }, + { + "name": "page_size", + "in": "query", + "description": "Optional. The maximum number of triggers to return per page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "Optional. A page token from a previous ListTriggers call.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTriggersResponse" + } + } + } + } + }, + "tags": [ + "triggers" + ] + }, + "post": { + "operationId": "CreateTrigger", + "description": "Creates a new trigger that will invoke the specified agent on the given\ncron schedule.", + "parameters": [], + "requestBody": { + "description": "Required. The trigger configuration to create.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Trigger" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Trigger" + } + } + } + } + }, + "tags": [ + "triggers" + ], + "x-codeSamples": [ + { + "label": "create", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/triggers \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"schedule\": \"0 9 * * *\",\n \"time_zone\": \"America/New_York\",\n \"interaction\": {\n \"agent\": \"antigravity-preview-05-2026\",\n \"input\": \"Summarize top news stories.\",\n \"environment\": \"remote\"\n }\n }'\n" + }, + { + "label": "create", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\ntrigger = client.triggers.create(\n schedule=\"0 9 * * *\",\n time_zone=\"America/New_York\",\n interaction={\n \"agent\": \"antigravity-preview-05-2026\",\n \"input\": \"Summarize top news stories.\",\n \"environment\": \"remote\",\n },\n)\nprint(trigger.id, trigger.interaction.agent)\n" + }, + { + "label": "create", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst trigger = await ai.triggers.create({\n schedule: '0 9 * * *',\n time_zone: 'America/New_York',\n interaction: {\n agent: 'antigravity-preview-05-2026',\n input: 'Summarize top news stories.',\n environment: 'remote',\n },\n});\nconsole.log(trigger.id, trigger.interaction.agent);\n" + }, + { + "label": "create", + "lang": "java", + "source": "import com.google.genai.gaos.models.interactions.AgentOption;\nimport com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteraction;\nimport com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;\nimport com.google.genai.gaos.models.operations.CreateTriggerResponse;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.triggers.Trigger;\nimport com.google.genai.gaos.models.triggers.TriggerCreateParams;\n\nClient client = new Client();\nCreateAgentInteraction interaction =\n CreateAgentInteraction.builder()\n .agent(AgentOption.of(\"antigravity-preview-05-2026\"))\n .input(InteractionsInput.of(\"Summarize top news stories.\"))\n .environment(CreateAgentInteractionEnvironment.of(\"remote\"))\n .build();\nTriggerCreateParams params =\n TriggerCreateParams.builder()\n .schedule(\"0 9 * * *\")\n .timeZone(\"America/New_York\")\n .interaction(interaction)\n .build();\nCreateTriggerResponse response = client.triggers.create(params);\nTrigger trigger =\n response.trigger().orElseThrow(() -> new RuntimeException(\"No trigger returned\"));\nSystem.out.println(\n trigger.id().orElse(\"\")\n + \" \"\n + trigger.interaction().flatMap(CreateAgentInteraction::agent).orElse(null));\n" + } + ] + } + }, + "/{api_version}/triggers/{id}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "delete": { + "operationId": "DeleteTrigger", + "description": "Deletes a trigger.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource name of the trigger.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Empty" + } + } + } + } + }, + "tags": [ + "triggers" + ] + }, + "get": { + "operationId": "GetTrigger", + "description": "Gets details of a single trigger.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource name of the trigger.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Trigger" + } + } + } + } + }, + "tags": [ + "triggers" + ] + }, + "patch": { + "operationId": "UpdateTrigger", + "description": "Updates a trigger.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. Resource name of the trigger.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Required. The trigger with updated fields.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTriggerRequest" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Trigger" + } + } + } + } + }, + "tags": [ + "triggers" + ] + } + }, + "/{api_version}/triggers/{triggerId}/executions": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListTriggerExecutions", + "description": "Lists executions for a trigger.", + "parameters": [ + { + "name": "filter", + "in": "query", + "description": "Optional. Filter expression.", + "schema": { + "type": "string" + } + }, + { + "name": "page_size", + "in": "query", + "description": "The maximum number of executions to return per page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "A page token from a previous ListTriggerExecutions call.", + "schema": { + "type": "string" + } + }, + { + "name": "triggerId", + "in": "path", + "description": "Required. The trigger ID to list executions from.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTriggerExecutionsResponse" + } + } + } + } + }, + "tags": [ + "triggers.executions" + ] + }, + "post": { + "operationId": "RunTrigger", + "description": "Runs a trigger immediately.", + "parameters": [ + { + "name": "triggerId", + "in": "path", + "description": "Required. Resource name of the trigger.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TriggerExecution" + } + } + } + } + }, + "tags": [ + "triggers" + ] + } + }, + "/{api_version}/voices": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListVoices", + "description": "Lists custom stored voices owned by the caller (ordered newest first)\nfollowed by prebuilt system voices from Google's voice catalog.", + "parameters": [ + { + "name": "accent", + "in": "query", + "description": "Optional. Filter by accent description (e.g. \"American\", \"British\").\nCase-insensitive exact match. If multiple values are specified, matches\nvoices with any of the specified accents (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "context", + "in": "query", + "description": "Optional. Filter by intended context or domain (e.g. \"News, Commercial\").\nCase-insensitive exact match. If multiple values are specified, matches\nvoices with any of the specified contexts (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "gender", + "in": "query", + "description": "Optional. Filter by gender presentation (e.g. \"female\", \"male\", \"neutral\").\nCase-insensitive exact match. If multiple values are specified, matches\nvoices with any of the specified genders (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "language_code", + "in": "query", + "description": "Optional. Filter by BCP-47 language code (e.g. \"en-US\").\nCase-insensitive exact match. If multiple values are specified, matches\nvoices with any of the specified language codes (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "page_size", + "in": "query", + "description": "Optional. The maximum number of voices to return per page. The service may\nreturn fewer than this value. If unspecified, at most 50 voices are\nreturned. The maximum value is 1000; values above 1000 are coerced to\n1000.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "Optional. A page token received from a previous `ListVoices` call. Provide\nthis to retrieve the subsequent page.\n\nWhen paginating, all filter query parameters (`language_code`,\n`region_code`, `accent`, `persona`, `context`, `gender`, `pitch`, `type`,\nand `search`) must match the call that returned this token; otherwise the\nrequest fails with `INVALID_ARGUMENT`. `page_size` may change between\npages.", + "schema": { + "type": "string" + } + }, + { + "name": "persona", + "in": "query", + "description": "Optional. Filter by vocal persona (e.g. \"Warm, Friendly\").\nCase-insensitive exact match. If multiple values are specified, matches\nvoices with any of the specified personas (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "pitch", + "in": "query", + "description": "Optional. Filter by vocal pitch. Accepts `\"low\"`, `\"medium\"`, `\"high\"`\n(case-insensitive). If multiple values are specified, matches voices with\nany of the specified pitches (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "region_code", + "in": "query", + "description": "Optional. Filter by ISO 3166-1 alpha-2 or UN M.49 region code (e.g. \"US\",\n\"001\").\nCase-insensitive exact match. If multiple values are specified, matches\nvoices with any of the specified region codes (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "search", + "in": "query", + "description": "Optional. Free-text substring search query matched case-insensitively\nagainst both `display_name` and `description`. Maximum 2048 bytes.", + "schema": { + "type": "string" + } + }, + { + "name": "type", + "in": "query", + "description": "Optional. Filter by voice type. Accepts `\"prebuilt\"`, `\"replicated\"`,\n`\"prompted\"` (case-insensitive). If multiple values are specified, matches\nvoices with any of the specified types (OR).", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListVoicesResponse" + } + } + } + } + }, + "tags": [ + "voices" + ], + "x-codeSamples": [ + { + "label": "list", + "lang": "sh", + "source": "curl -X GET https://generativelanguage.googleapis.com/v1beta/voices \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "list", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.voices.list()\nfor voice in response.voices or []:\n print(voice.id, voice.display_name)\n" + }, + { + "label": "list", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst response = await ai.voices.list();\nfor (const voice of response.voices ?? []) {\n console.log(voice.id, voice.display_name);\n}\n" + }, + { + "label": "list", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n res, err := client.Voices.List(ctx, operations.ListVoicesRequest{})\n if err != nil {\n log.Fatal(err)\n }\n\n if res.ListVoicesResponse != nil {\n for _, voice := range res.ListVoicesResponse.Voices {\n if voice.ID != nil && voice.DisplayName != nil {\n fmt.Println(*voice.ID, *voice.DisplayName)\n }\n }\n }\n}\n" + } + ] + }, + "post": { + "operationId": "CreateVoice", + "description": "Creates a custom voice from a natural-language prompt\n(`VOICE_TYPE_PROMPTED`) or from reference and consent audio recordings\n(`VOICE_TYPE_REPLICATED`).", + "parameters": [], + "requestBody": { + "description": "The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateVoiceRequest" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Voice" + } + } + } + } + }, + "tags": [ + "voices" + ], + "x-codeSamples": [ + { + "label": "create", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/voices \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"store\": true,\n \"voice\": {\n \"type\": \"prompted\",\n \"display_name\": \"Warm Narrator\",\n \"language_code\": \"en-US\",\n \"prompted\": {\n \"input\": \"A warm, friendly narrator voice with a calm pace.\"\n }\n }\n }'\n" + }, + { + "label": "create", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nvoice = client.voices.create(\n store=True,\n voice={\n \"type\": \"prompted\",\n \"display_name\": \"Warm Narrator\",\n \"language_code\": \"en-US\",\n \"prompted\": {\n \"input\": \"A warm, friendly narrator voice with a calm pace.\",\n },\n },\n)\nprint(voice.id)\n" + }, + { + "label": "create", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst voice = await ai.voices.create({\n store: true,\n voice: {\n type: 'prompted',\n display_name: 'Warm Narrator',\n language_code: 'en-US',\n prompted: {\n input: 'A warm, friendly narrator voice with a calm pace.',\n },\n },\n});\nconsole.log(voice.id);\n" + }, + { + "label": "create", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_voices \"google.golang.org/genai/interactions/models/voices\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n req := operations.CreateVoiceRequest{\n Body: gaos_voices.CreateVoiceRequest{\n Store: genai.Ptr(true),\n Voice: gaos_voices.VoiceInput{\n Type: gaos_voices.VoiceTypePrompted,\n DisplayName: genai.Ptr(\"Warm Narrator\"),\n LanguageCode: genai.Ptr(\"en-US\"),\n Prompted: &gaos_voices.PromptedVoice{\n Input: \"A warm, friendly narrator voice with a calm pace.\",\n },\n },\n },\n }\n\n res, err := client.Voices.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Voice != nil && res.Voice.ID != nil {\n fmt.Println(*res.Voice.ID)\n }\n}\n" + } + ] + } + }, + "/{api_version}/voices/{voicesId}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "delete": { + "operationId": "DeleteVoice", + "description": "Deletes a custom stored voice (`store = true`) by resource name.\nPrebuilt catalog voices (`VOICE_TYPE_PREBUILT`) cannot be deleted.", + "parameters": [ + { + "name": "voicesId", + "in": "path", + "description": "Required. The resource name of the custom stored voice to delete\n(for example, `voices/voice_abc123def456`).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteVoiceResponse" + } + } + } + } + }, + "tags": [ + "voices" + ], + "x-codeSamples": [ + { + "label": "delete", + "lang": "sh", + "source": "curl -X DELETE https://generativelanguage.googleapis.com/v1beta/voices/voice_abc123 \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "delete", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nclient.voices.delete(id=\"voice_abc123\")\n" + }, + { + "label": "delete", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nawait ai.voices.delete('voice_abc123');\n" + }, + { + "label": "delete", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n _, err = client.Voices.Delete(ctx, operations.DeleteVoiceRequest{\n ID: \"voice_abc123\",\n })\n if err != nil {\n log.Fatal(err)\n }\n}\n" + } + ] + }, + "get": { + "operationId": "GetVoice", + "description": "Gets a custom stored voice (`store = true`) by resource name.\nPrebuilt catalog voices (`VOICE_TYPE_PREBUILT`) cannot be retrieved via\n`GetVoice`; use `ListVoices` instead.", + "parameters": [ + { + "name": "voicesId", + "in": "path", + "description": "Required. The resource name of the custom stored voice to retrieve\n(for example, `voices/voice_abc123def456`).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Voice" + } + } + } + } + }, + "tags": [ + "voices" + ], + "x-codeSamples": [ + { + "label": "get", + "lang": "sh", + "source": "curl -X GET https://generativelanguage.googleapis.com/v1beta/voices/voice_abc123 \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\"\n" + }, + { + "label": "get", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nvoice = client.voices.get(id=\"voice_abc123\")\nprint(voice.id, voice.display_name)\n" + }, + { + "label": "get", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst voice = await ai.voices.get('voice_abc123');\nconsole.log(voice.id, voice.display_name);\n" + }, + { + "label": "get", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n res, err := client.Voices.Get(ctx, operations.GetVoiceRequest{\n ID: \"voice_abc123\",\n })\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Voice != nil && res.Voice.ID != nil && res.Voice.DisplayName != nil {\n fmt.Println(*res.Voice.ID, *res.Voice.DisplayName)\n }\n}\n" + } + ] + } + }, + "/{api_version}/webhooks": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "get": { + "operationId": "ListWebhooks", + "description": "Lists all Webhooks.", + "parameters": [ + { + "name": "page_size", + "in": "query", + "description": "Optional. The maximum number of webhooks to return. The service may return\nfewer than this value. If unspecified, at most 50 webhooks will be\nreturned. The maximum value is 1000.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "page_token", + "in": "query", + "description": "Optional. A page token, received from a previous `ListWebhooks` call.\nProvide this to retrieve the subsequent page.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListWebhooksResponse" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + }, + "post": { + "operationId": "CreateWebhook", + "description": "Creates a new Webhook.", + "parameters": [ + { + "name": "webhook_id", + "in": "query", + "description": "The webhook_id to use for the webhook. If not specified, the server will\ngenerate a unique ID.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Required. The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateWebhookRequest" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhook" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + } + }, + "/{api_version}/webhooks/{id}": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "delete": { + "operationId": "DeleteWebhook", + "description": "Deletes a Webhook.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. The ID of the webhook to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Empty" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + }, + "get": { + "operationId": "GetWebhook", + "description": "Gets a specific Webhook.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. The ID of the webhook to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhook" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + }, + "patch": { + "operationId": "UpdateWebhook", + "description": "Updates an existing Webhook.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. The ID of the webhook to update.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Required. The request body.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateWebhookRequest" + } + } + } + }, + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhook" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + } + }, + "/{api_version}/webhooks/{id}:ping": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "post": { + "operationId": "PingWebhook", + "description": "Sends a ping event to a Webhook.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. The ID of the webhook to ping.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PingWebhookResponse" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + } + }, + "/{api_version}/webhooks/{id}:rotateSigningSecret": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + } + ], + "post": { + "operationId": "RotateSigningSecret", + "description": "Generates a new signing secret for a Webhook.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Required. The ID of the webhook for which to generate a signing secret.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "default": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RotateSigningSecretResponse" + } + } + } + } + }, + "tags": [ + "webhooks" + ] + } + } + }, + "components": { + "parameters": { + "EnvironmentFileExtract": { + "name": "extract", + "in": "query", + "description": "Optional. If true, treats the uploaded file as a tar/tar.gz archive and unpacks it into `path`.", + "schema": { + "type": "boolean" + } + }, + "EnvironmentFileOverwrite": { + "name": "overwrite", + "in": "query", + "description": "Optional. Whether to overwrite the destination file if it already exists.", + "schema": { + "type": "boolean" + } + }, + "EnvironmentFileUploadCommand": { + "name": "X-Goog-Upload-Command", + "in": "header", + "description": "Command that starts the resumable upload session.", + "required": true, + "schema": { + "type": "string", + "const": "start", + "default": "start" + } + }, + "EnvironmentFileUploadContentLength": { + "name": "X-Goog-Upload-Header-Content-Length", + "in": "header", + "description": "Total number of file bytes that will be uploaded to the session URL.", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 0 + } + }, + "EnvironmentFileUploadContentType": { + "name": "X-Goog-Upload-Header-Content-Type", + "in": "header", + "description": "MIME type of the file that will be uploaded to the session URL.", + "required": true, + "schema": { + "type": "string", + "minLength": 1 + } + }, + "EnvironmentFileUploadProtocol": { + "name": "X-Goog-Upload-Protocol", + "in": "header", + "description": "Resumable upload protocol selector.", + "required": true, + "schema": { + "type": "string", + "const": "resumable", + "default": "resumable" + } + }, + "api_version": { + "name": "api_version", + "in": "path", + "description": "API version for request routing.", + "required": true, + "schema": { + "type": "string" + } + }, + "google_genai_user_project": { + "name": "x-goog-user-project", + "in": "header", + "description": "Quota project header to send with Google GenAI API requests.", + "schema": { + "type": "string" + }, + "x-speakeasy-name-override": "user_project" + } + }, + "headers": { + "EnvironmentFileUploadUrl": { + "description": "Opaque URL to which file chunks are uploaded and finalized.", + "schema": { + "type": "string", + "format": "uri" + } + } + }, + "schemas": { + "Agent": { + "description": "An agent definition for the CreateAgent API.\nThis message is the target for annotation-parser-based JSON parsing.\nNew format:\n {\n \"id\": \"customer-sentinel\",\n \"base_agent\": \"\",\n \"system_instruction\": \"...\",\n \"base_environment\": { \"type\": \"remote\", \"sources\": [...] },\n \"tools\": [ {\"type\": \"code_execution\"} ]\n }", + "type": "object", + "properties": { + "agent_config": { + "description": "Configuration parameters for the agent.", + "oneOf": [ + { + "$ref": "#/components/schemas/AntigravityAgentConfig" + } + ] + }, + "base_environment": { + "description": "The environment configuration for the agent.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentConfig" + }, + { + "type": "string" + } + ] + }, + "id": { + "description": "The unique identifier for the agent.", + "type": "string" + }, + "base_agent": { + "description": "The base agent to extend.", + "type": "string" + }, + "system_instruction": { + "description": "System instruction for the agent.", + "type": "string" + }, + "description": { + "description": "Agent description for developers to quickly read and understand.", + "type": "string" + }, + "tools": { + "description": "The tools available to the agent.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentTool" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "AgentOption": { + "title": "Agent", + "description": "The agent to interact with.", + "type": "string", + "enum": [ + "deep-research-pro-preview-12-2025", + "deep-research-preview-04-2026", + "deep-research-max-preview-04-2026", + "antigravity-preview-05-2026" + ], + "x-speakeasy-enum-descriptions": [ + "Gemini Deep Research Agent", + "Gemini Deep Research Agent", + "Gemini Deep Research Max Agent", + "Use the Antigravity managed agent to perform multi-step tasks that require reasoning, file operations, and tool use." + ], + "x-speakeasy-enum-format": "union", + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-unknown-values": "allow" + }, + "AgentTool": { + "description": "A tool that the agent can use.", + "oneOf": [ + { + "$ref": "#/components/schemas/CodeExecution" + }, + { + "$ref": "#/components/schemas/Function" + }, + { + "$ref": "#/components/schemas/GoogleSearch" + }, + { + "$ref": "#/components/schemas/McpServer" + }, + { + "$ref": "#/components/schemas/UrlContext" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "AllowedTools": { + "description": "The configuration for allowed tools.", + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "auto", + "any", + "none", + "validated" + ], + "x-google-enum-descriptions": [ + "Auto tool choice.", + "Any tool choice.", + "No tool choice.", + "Validated tool choice." + ], + "x-speakeasy-model-namespace": "interactions", + "description": "The mode of the tool choice." + }, + "tools": { + "description": "The names of the allowed tools.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "Annotation": { + "description": "Citation information for model-generated content.", + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/FileCitation" + }, + { + "$ref": "#/components/schemas/PlaceCitation" + }, + { + "$ref": "#/components/schemas/SpeechAnnotation" + }, + { + "$ref": "#/components/schemas/UrlCitation" + }, + { + "$ref": "#/components/schemas/WordInfo" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "AntigravityAgentConfig": { + "description": "Configuration for the Antigravity agent runtime.\nProvides server-side control over the agent's execution environment\nand tool configuration.", + "type": "object", + "properties": { + "type": { + "const": "antigravity" + }, + "model": { + "description": "The model to use for agent reasoning.", + "type": "string" + }, + "max_total_tokens": { + "description": "Max total tokens for the agent run.", + "type": "string", + "format": "int64" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ArgumentsDelta": { + "type": "object", + "properties": { + "type": { + "const": "arguments_delta" + }, + "arguments": { + "type": "string" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "AudioContent": { + "description": "An audio content block.", + "type": "object", + "properties": { + "type": { + "const": "audio" + }, + "data": { + "description": "The audio content.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "description": "The URI of the audio.", + "type": "string" + }, + "channels": { + "description": "The number of audio channels.", + "type": "integer", + "format": "int32" + }, + "sample_rate": { + "description": "The sample rate of the audio.", + "type": "integer", + "format": "int32" + }, + "mime_type": { + "description": "The mime type of the audio.", + "type": "string", + "enum": [ + "audio/wav", + "audio/mp3", + "audio/aiff", + "audio/aac", + "audio/ogg", + "audio/flac", + "audio/mpeg", + "audio/m4a", + "audio/l16", + "audio/opus", + "audio/alaw", + "audio/mulaw", + "audio/webm" + ], + "x-google-enum-descriptions": [ + "WAV audio format", + "MP3 audio format", + "AIFF audio format", + "AAC audio format", + "OGG audio format", + "FLAC audio format", + "MPEG audio format", + "M4A audio format", + "L16 audio format", + "OPUS audio format", + "ALAW audio format", + "MULAW audio format", + "WEBM audio format" + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "audio": { + "summary": "Audio", + "value": { + "type": "audio", + "data": "BASE64_ENCODED_AUDIO", + "mime_type": "audio/wav" + } + } + } + ], + "x-speakeasy-exports": [ + { + "name": "audio_content_param", + "group": "interactions", + "representation": "input" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "AudioData": { + "description": "Audio payload used for voice creation.", + "type": "object", + "properties": { + "mime_type": { + "description": "Required. The IANA MIME type of the audio data (for example, `audio/wav` or\n`audio/mpeg`).", + "type": "string" + }, + "data": { + "description": "Required. The raw audio bytes.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "data", + "mime_type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "AudioDelta": { + "type": "object", + "properties": { + "type": { + "const": "audio" + }, + "data": { + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "type": "string" + }, + "mime_type": { + "type": "string", + "enum": [ + "audio/wav", + "audio/mp3", + "audio/aiff", + "audio/aac", + "audio/ogg", + "audio/flac", + "audio/mpeg", + "audio/m4a", + "audio/l16", + "audio/opus", + "audio/alaw", + "audio/mulaw", + "audio/webm" + ], + "x-google-enum-descriptions": [ + "WAV audio format", + "MP3 audio format", + "AIFF audio format", + "AAC audio format", + "OGG audio format", + "FLAC audio format", + "MPEG audio format", + "M4A audio format", + "L16 audio format", + "OPUS audio format", + "ALAW audio format", + "MULAW audio format", + "WEBM audio format" + ] + }, + "rate": { + "description": "Deprecated. Use sample_rate instead. The value is ignored.", + "type": "integer", + "deprecated": true, + "format": "int32" + }, + "sample_rate": { + "description": "The sample rate of the audio.", + "type": "integer", + "format": "int32" + }, + "channels": { + "description": "The number of audio channels.", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "AudioResponseFormat": { + "description": "Configuration for audio output format.", + "type": "object", + "properties": { + "type": { + "const": "audio" + }, + "mime_type": { + "description": "The MIME type of the audio output.", + "type": "string", + "enum": [ + "audio/mp3", + "audio/ogg_opus", + "audio/l16", + "audio/wav", + "audio/alaw", + "audio/mulaw" + ], + "x-google-enum-descriptions": [ + "MP3 audio format.", + "OGG Opus audio format.", + "Raw PCM (L16) audio format.", + "WAV audio format.", + "A-law audio format.", + "Mu-law audio format." + ] + }, + "delivery": { + "description": "The delivery mode for the audio output.", + "type": "string", + "enum": [ + "inline", + "uri" + ], + "x-google-enum-descriptions": [ + "Audio data is returned inline in the response.", + "Audio data is returned as a URI." + ] + }, + "sample_rate": { + "description": "Sample rate in Hz.", + "type": "integer", + "format": "int32" + }, + "bit_rate": { + "description": "Bit rate in bits per second (bps). Only applicable for compressed formats\n(MP3, Opus).", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "examples": [ + { + "audio_response_format": { + "summary": "Audio Output", + "value": { + "type": "audio", + "sample_rate": 24000 + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CodeExecution": { + "description": "A tool that can be used by the model to execute code.", + "type": "object", + "properties": { + "type": { + "const": "code_execution" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "code_execution", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"code_execution\"\n }],\n \"input\": \"Calculate the first 10 Fibonacci numbers\"\n }'\n" + }, + { + "label": "code_execution", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[{\"type\": \"code_execution\"}],\n input=\"Calculate the first 10 Fibonacci numbers\",\n)\nprint(response.output_text)\n" + }, + { + "label": "code_execution", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [{type: 'code_execution'}],\n input: 'Calculate the first 10 Fibonacci numbers',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "code_execution", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.CodeExecution;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(new CodeExecution()))\n .input(InteractionsInput.of(\"Calculate the first 10 Fibonacci numbers\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "code_execution", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n tool := gaos_interactions.NewTool(gaos_interactions.CodeExecution{})\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Calculate the first 10 Fibonacci numbers\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "CodeExecutionCallArguments": { + "description": "The arguments to pass to the code execution.", + "type": "object", + "properties": { + "language": { + "description": "Programming language of the `code`.", + "type": "string", + "enum": [ + "python", + "bash" + ], + "x-google-enum-descriptions": [ + "Python >= 3.10, with numpy and simpy available.", + "Bash. Only available for Gemini 3.0 model or above." + ] + }, + "code": { + "description": "The code to be executed.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "CodeExecutionCallDelta": { + "type": "object", + "properties": { + "arguments": { + "$ref": "#/components/schemas/CodeExecutionCallArguments" + }, + "type": { + "const": "code_execution_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "arguments", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CodeExecutionCallStep": { + "description": "Code execution call step.", + "type": "object", + "properties": { + "arguments": { + "description": "Required. The arguments to pass to the code execution.", + "$ref": "#/components/schemas/CodeExecutionCallStepArguments" + }, + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "code_execution_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "arguments", + "id", + "type" + ], + "examples": [ + { + "code_execution_call": { + "summary": "CodeExecutionCallStep", + "value": { + "type": "code_execution_call", + "arguments": { + "code": "print(sum(range(1, 11)))" + }, + "id": "code_call_71021" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CodeExecutionCallStepArguments": { + "description": "The arguments to pass to the code execution.", + "type": "object", + "properties": { + "language": { + "description": "Programming language of the `code`.", + "type": "string", + "enum": [ + "python", + "bash" + ], + "x-google-enum-descriptions": [ + "Python >= 3.10, with numpy and simpy available.", + "Bash. Only available for Gemini 3.0 model or above." + ] + }, + "code": { + "description": "The code to be executed.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "CodeExecutionCallArguments" + }, + "CodeExecutionResultDelta": { + "type": "object", + "properties": { + "result": { + "type": "string" + }, + "type": { + "const": "code_execution_result" + }, + "is_error": { + "type": "boolean" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "result", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CodeExecutionResultStep": { + "description": "Code execution result step.", + "type": "object", + "properties": { + "result": { + "description": "Required. The output of the code execution.", + "type": "string" + }, + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "code_execution_result" + }, + "is_error": { + "description": "Whether the code execution resulted in an error.", + "type": "boolean" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "call_id", + "result", + "type" + ], + "examples": [ + { + "code_execution_result": { + "summary": "CodeExecutionResultStep", + "value": { + "type": "code_execution_result", + "call_id": "code_call_71021", + "result": "55\n" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ComputerUse": { + "description": "A tool that can be used by the model to interact with the computer.", + "type": "object", + "properties": { + "type": { + "const": "computer_use" + }, + "environment": { + "description": "The environment being operated.", + "type": "string", + "enum": [ + "browser", + "mobile", + "desktop" + ], + "x-google-enum-descriptions": [ + "Operates in a web browser.", + "Operates in a mobile environment.", + "Operates in a desktop environment." + ] + }, + "excluded_predefined_functions": { + "description": "The list of predefined functions that are excluded from the model call.", + "type": "array", + "items": { + "type": "string" + } + }, + "enable_prompt_injection_detection": { + "description": "Whether enable the prompt injection detection check on computer-use\nrequest.", + "type": "boolean" + }, + "disabled_safety_policies": { + "description": "Optional. Disabled safety policies for computer use.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "financial_transactions", + "sensitive_data_modification", + "communication_tool", + "account_creation", + "data_modification", + "user_consent_management", + "legal_terms_and_agreements" + ], + "x-google-enum-descriptions": [ + "Safety policy for financial transactions.", + "Safety policy for sensitive data modification.", + "Safety policy for communication tools (e.g. Gmail, Chat, Meet).", + "Safety policy for account creation.", + "Safety policy for data modification.", + "Safety policy for user consent management.", + "Safety policy for legal terms and agreements." + ] + } + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "computer_use", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-2.5-computer-use-preview-10-2025\",\n \"tools\": [{\n \"type\": \"computer_use\"\n }],\n \"input\": \"Find a flight to Tokyo\"\n }'\n" + }, + { + "label": "computer_use", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-2.5-computer-use-preview-10-2025\",\n tools=[{\"type\": \"computer_use\"}],\n input=\"Find a flight to Tokyo\",\n)\nprint(response.output_text)\n" + }, + { + "label": "computer_use", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-2.5-computer-use-preview-10-2025',\n tools: [{type: 'computer_use'}],\n input: 'Find a flight to Tokyo',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "computer_use", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.interactions.ComputerUse;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-2.5-computer-use-preview-10-2025\")\n .tools(List.of(new ComputerUse()))\n .input(InteractionsInput.of(\"Find a flight to Tokyo\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "computer_use", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n tool := gaos_interactions.NewTool(gaos_interactions.ComputerUse{})\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-2.5-computer-use-preview-10-2025\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Find a flight to Tokyo\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "Content": { + "description": "The content of the response.", + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/AudioContent" + }, + { + "$ref": "#/components/schemas/DocumentContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + }, + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/VideoContent" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CreateAgentInteractionParams": { + "description": "Parameters for creating agent interactions", + "properties": { + "agent": { + "description": "The name of the `Agent` used for generating the interaction.", + "$ref": "#/components/schemas/AgentOption" + }, + "input": { + "$ref": "#/components/schemas/InteractionsInput" + }, + "agent_config": { + "description": "Configuration parameters for the agent interaction.", + "oneOf": [ + { + "$ref": "#/components/schemas/AntigravityAgentConfig" + }, + { + "$ref": "#/components/schemas/DeepResearchAgentConfig" + }, + { + "$ref": "#/components/schemas/DynamicAgentConfig" + } + ] + }, + "response_format": { + "description": "Enforces that the generated response is a JSON object that complies with\nthe JSON schema specified in this field.", + "oneOf": [ + { + "$ref": "#/components/schemas/ResponseFormat" + }, + { + "title": "ResponseFormatList", + "type": "array", + "items": { + "$ref": "#/components/schemas/ResponseFormat" + } + } + ] + }, + "environment": { + "description": "The environment configuration for the interaction. Can be an object\nspecifying remote environment sources or a string referencing an existing\nenvironment ID.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentConfig" + }, + { + "type": "string" + } + ] + }, + "id": { + "description": "Required. Output only. A unique identifier for the interaction completion.", + "type": "string", + "readOnly": true + }, + "status": { + "description": "Required. Output only. The status of the interaction.", + "type": "string", + "enum": [ + "in_progress", + "requires_action", + "completed", + "failed", + "cancelled", + "incomplete", + "budget_exceeded" + ], + "readOnly": true, + "x-google-enum-deprecated": [ + false, + false, + false, + false, + false, + false, + true + ], + "x-google-enum-descriptions": [ + "The interaction is in progress.", + "The interaction requires action/input from the user.", + "The interaction is completed.", + "The interaction failed.", + "The interaction was cancelled.", + "The interaction is completed, but contains incomplete results (e.g.\nhitting max_tokens).", + "Deprecated: Token and execution budget exhaustion returns INCOMPLETE\n(11)." + ] + }, + "created": { + "description": "Required. Output only. The time at which the response was created in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "updated": { + "description": "Required. Output only. The time at which the response was last updated in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "system_instruction": { + "description": "System instruction for the interaction.", + "type": "string" + }, + "tools": { + "description": "A list of tool declarations the model may call during interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Tool" + } + }, + "response_modalities": { + "description": "The requested modalities of the response (TEXT, IMAGE, AUDIO).", + "type": "array", + "deprecated": true, + "items": { + "$ref": "#/components/schemas/ResponseModality" + } + }, + "response_mime_type": { + "description": "The mime type of the response. This is required if response_format is set.", + "type": "string", + "deprecated": true + }, + "previous_interaction_id": { + "description": "The ID of the previous interaction, if any.", + "type": "string" + }, + "environment_id": { + "description": "Output only. The environment ID for the interaction. Only populated if environment\nconfig is set in the request.", + "type": "string", + "readOnly": true + }, + "service_tier": { + "description": "The service tier for the interaction.", + "$ref": "#/components/schemas/ServiceTier" + }, + "webhook_config": { + "description": "Optional. Webhook configuration for receiving notifications when the\ninteraction completes.", + "$ref": "#/components/schemas/WebhookConfig" + }, + "safety_settings": { + "description": "Safety settings for the interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SafetySetting" + } + }, + "labels": { + "description": "The labels with user-defined metadata for the request.\n\nLabel keys and values can be no longer than 63 characters\n(Unicode codepoints) and can only contain lowercase letters, numeric\ncharacters, underscores, and dashes. International characters are allowed.\nLabel values are optional. Label keys must start with a letter.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "stream": { + "description": "Input only. Whether the interaction will be streamed.", + "type": "boolean", + "writeOnly": true + }, + "store": { + "description": "Input only. Whether to store the response and request for later retrieval.", + "type": "boolean", + "writeOnly": true + }, + "background": { + "description": "Input only. Whether to run the model interaction in the background.", + "type": "boolean", + "writeOnly": true + } + }, + "required": [ + "agent", + "input" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "CreateAgentInteraction" + }, + "CreateEnvironmentRequest": { + "description": "Request for `CreateEnvironment`.", + "type": "object", + "properties": { + "network": { + "description": "Network configuration for the environment.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentNetworkEgressAllowlist" + }, + { + "type": "string", + "enum": [ + "disabled" + ], + "x-google-enum-descriptions": [ + "All network egress is blocked." + ] + } + ] + }, + "sources": { + "description": "Sources to be mounted into the environment.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Source" + } + }, + "from_environment": { + "description": "Optional. The source environment to copy/fork from.\nFormat: `environments/{environment_id}` or `{environment_id}`.\nWhen specified, `sources` and `env` must be empty.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "CreateModelInteractionParams": { + "description": "Parameters for creating model interactions", + "properties": { + "model": { + "description": "The name of the `Model` used for generating the interaction.", + "$ref": "#/components/schemas/ModelOption" + }, + "input": { + "$ref": "#/components/schemas/InteractionsInput" + }, + "generation_config": { + "description": "Input only. Configuration parameters for the model interaction.", + "$ref": "#/components/schemas/GenerationConfig", + "writeOnly": true + }, + "response_format": { + "description": "Enforces that the generated response is a JSON object that complies with\nthe JSON schema specified in this field.", + "oneOf": [ + { + "$ref": "#/components/schemas/ResponseFormat" + }, + { + "title": "ResponseFormatList", + "type": "array", + "items": { + "$ref": "#/components/schemas/ResponseFormat" + } + } + ] + }, + "environment": { + "description": "The environment configuration for the interaction. Can be an object\nspecifying remote environment sources or a string referencing an existing\nenvironment ID.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentConfig" + }, + { + "type": "string" + } + ] + }, + "id": { + "description": "Required. Output only. A unique identifier for the interaction completion.", + "type": "string", + "readOnly": true + }, + "status": { + "description": "Required. Output only. The status of the interaction.", + "type": "string", + "enum": [ + "in_progress", + "requires_action", + "completed", + "failed", + "cancelled", + "incomplete", + "budget_exceeded" + ], + "readOnly": true, + "x-google-enum-deprecated": [ + false, + false, + false, + false, + false, + false, + true + ], + "x-google-enum-descriptions": [ + "The interaction is in progress.", + "The interaction requires action/input from the user.", + "The interaction is completed.", + "The interaction failed.", + "The interaction was cancelled.", + "The interaction is completed, but contains incomplete results (e.g.\nhitting max_tokens).", + "Deprecated: Token and execution budget exhaustion returns INCOMPLETE\n(11)." + ] + }, + "created": { + "description": "Required. Output only. The time at which the response was created in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "updated": { + "description": "Required. Output only. The time at which the response was last updated in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "system_instruction": { + "description": "System instruction for the interaction.", + "type": "string" + }, + "tools": { + "description": "A list of tool declarations the model may call during interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Tool" + } + }, + "response_modalities": { + "description": "The requested modalities of the response (TEXT, IMAGE, AUDIO).", + "type": "array", + "deprecated": true, + "items": { + "$ref": "#/components/schemas/ResponseModality" + } + }, + "response_mime_type": { + "description": "The mime type of the response. This is required if response_format is set.", + "type": "string", + "deprecated": true + }, + "previous_interaction_id": { + "description": "The ID of the previous interaction, if any.", + "type": "string" + }, + "environment_id": { + "description": "Output only. The environment ID for the interaction. Only populated if environment\nconfig is set in the request.", + "type": "string", + "readOnly": true + }, + "service_tier": { + "description": "The service tier for the interaction.", + "$ref": "#/components/schemas/ServiceTier" + }, + "webhook_config": { + "description": "Optional. Webhook configuration for receiving notifications when the\ninteraction completes.", + "$ref": "#/components/schemas/WebhookConfig" + }, + "safety_settings": { + "description": "Safety settings for the interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SafetySetting" + } + }, + "labels": { + "description": "The labels with user-defined metadata for the request.\n\nLabel keys and values can be no longer than 63 characters\n(Unicode codepoints) and can only contain lowercase letters, numeric\ncharacters, underscores, and dashes. International characters are allowed.\nLabel values are optional. Label keys must start with a letter.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "stream": { + "description": "Input only. Whether the interaction will be streamed.", + "type": "boolean", + "writeOnly": true + }, + "store": { + "description": "Input only. Whether to store the response and request for later retrieval.", + "type": "boolean", + "writeOnly": true + }, + "background": { + "description": "Input only. Whether to run the model interaction in the background.", + "type": "boolean", + "writeOnly": true + } + }, + "required": [ + "input", + "model" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "CreateModelInteraction" + }, + "CreateVoiceRequest": { + "description": "Request message for `VoicesService.CreateVoice`.", + "type": "object", + "properties": { + "voice": { + "description": "Required. The voice to create.\n`voice.model` is optional; if omitted, the service selects the default\nvoice creation model. Output-only fields on `Voice` (`id`, `key`,\n`expire_time`, `usage`) are ignored if set.", + "$ref": "#/components/schemas/Voice" + }, + "store": { + "description": "Optional. Whether the created voice is persisted and managed by Google.\n\n* When `true`, Google stores the voice and returns `Voice.id` (for example,\n `voice_abc123def456`), which can be managed via `GetVoice`, `ListVoices`,\n and `DeleteVoice` and referenced by ID in synthesis requests. Stored\n voices expire after 1 year of inactivity; using a stored voice in speech\n synthesis or as a `base_voice` in `CreateVoice` extends its\n `expire_time`. Projects are subject to a maximum active stored voice\n quota; exceeding the quota returns `RESOURCE_EXHAUSTED`.\n* When `false` (default), the voice is not stored by Google and `Voice.key`\n (for example, `voicekey_...`) is returned for client-side storage and\n synthesis. Optional discovery metadata fields on `voice` are not\n persisted or returned when `store` is `false`.\n* Required to be `true` when `voice.type` is `\"prompted\"`\n (otherwise fails with `INVALID_ARGUMENT`).", + "type": "boolean" + } + }, + "required": [ + "voice" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CreateWebhookRequest": { + "description": "Request message for WebhookService.CreateWebhook.", + "type": "object", + "properties": { + "webhook": { + "description": "Required. The webhook to create.", + "$ref": "#/components/schemas/Webhook" + } + }, + "required": [ + "webhook" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Credential": { + "description": "Server-managed credential resource stored in Secret Manager.", + "type": "object", + "properties": { + "id": { + "description": "Required. Output only. Identifier. Unique identifier for the credential.", + "type": "string", + "readOnly": true, + "x-google-identifier": true + }, + "type": { + "description": "Required. Output only. The type of credential.", + "type": "string", + "enum": [ + "bearer_token", + "oauth2", + "environment_variable" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "Static token injected as header. No refresh logic.", + "Auto-refresh expired access tokens using stored refresh token.", + "Environment variable injected into sandbox container." + ] + }, + "status": { + "description": "Output only. Current status of the credential.", + "type": "string", + "enum": [ + "active", + "revoked" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "The credential is active and valid for use.", + "The credential has been revoked and is no longer valid." + ] + }, + "create_time": { + "description": "Output only. The timestamp when the credential was created.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "update_time": { + "description": "Output only. The timestamp when the credential was last updated.", + "type": "string", + "format": "date-time", + "readOnly": true + } + }, + "required": [ + "id", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CredentialCreateParams": { + "description": "Represents the fields of a Credential provided on creation.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentVariableConfig" + }, + { + "$ref": "#/components/schemas/HttpBearerConfig" + }, + { + "$ref": "#/components/schemas/OAuth2Config" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "CredentialUpdateParams": { + "description": "Represents the fields of a Credential that can be updated.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentVariableUpdateConfig" + }, + { + "$ref": "#/components/schemas/HttpBearerUpdateConfig" + }, + { + "$ref": "#/components/schemas/OAuth2UpdateConfig" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "DeepResearchAgentConfig": { + "description": "Configuration for the Deep Research agent.", + "type": "object", + "properties": { + "type": { + "const": "deep-research" + }, + "thinking_summaries": { + "description": "Whether to include thought summaries in the response.", + "$ref": "#/components/schemas/ThinkingSummaries" + }, + "visualization": { + "description": "Whether to include visualizations in the response.", + "type": "string", + "enum": [ + "off", + "auto" + ], + "x-google-enum-descriptions": [ + "Do not include visualizations.", + "Automatically include visualizations." + ] + }, + "collaborative_planning": { + "description": "Enables human-in-the-loop planning for the Deep Research agent. If set to\ntrue, the Deep Research agent will provide a research plan in its response.\nThe agent will then proceed only if the user confirms the plan in the next\nturn.", + "type": "boolean" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "DeleteVoiceResponse": { + "description": "Response message for `VoicesService.DeleteVoice`.", + "type": "object", + "x-speakeasy-model-namespace": "interactions" + }, + "DocumentContent": { + "description": "A document content block.", + "type": "object", + "properties": { + "type": { + "const": "document" + }, + "data": { + "description": "The document content.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "description": "The URI of the document.", + "type": "string" + }, + "mime_type": { + "description": "The mime type of the document.", + "type": "string", + "enum": [ + "application/pdf", + "text/csv" + ], + "x-google-enum-descriptions": [ + "PDF document format", + "CSV document format" + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "document": { + "summary": "Document", + "value": { + "type": "document", + "data": "BASE64_ENCODED_DOCUMENT", + "mime_type": "application/pdf" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "DocumentDelta": { + "type": "object", + "properties": { + "type": { + "const": "document" + }, + "data": { + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "type": "string" + }, + "mime_type": { + "type": "string", + "enum": [ + "application/pdf", + "text/csv" + ], + "x-google-enum-descriptions": [ + "PDF document format", + "CSV document format" + ] + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "DynamicAgentConfig": { + "description": "Configuration for dynamic agents.", + "type": "object", + "properties": { + "type": { + "const": "dynamic" + } + }, + "required": [ + "type" + ], + "additionalProperties": { + "description": "For agents that are not supported statically in the API definition." + }, + "x-speakeasy-model-namespace": "interactions" + }, + "EgressRule": { + "description": "A single domain allowlist rule with optional header injection.", + "type": "object", + "properties": { + "domain": { + "description": "Domain to allow outbound requests to. Supports wildcards (e.g.\n'*.googleapis.com'). Use '*' to allow all domains.", + "type": "string" + }, + "transform": { + "description": "Headers to inject into requests matching this rule.\nKey: header name (e.g., \"Authorization\").\nValue: header value (e.g., \"Bearer your-token\").", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "credential": { + "description": "Optional. Reference to a server-managed Credential resource by ID.", + "type": "string" + } + }, + "required": [ + "domain" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Empty": { + "description": "A generic empty message that you can re-use to avoid defining duplicated\nempty messages in your APIs. A typical example is to use it as the request\nor the response type of an API method. For instance:\n\n service Foo {\n rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);\n }", + "type": "object", + "x-speakeasy-model-namespace": "interactions" + }, + "EnvVar": { + "description": "An environment variable to set in the execution environment.", + "type": "object", + "properties": { + "value": { + "description": "Direct string value for plain environment variables.", + "type": "string" + }, + "credential": { + "description": "Optional reference to a server-managed Credential resource by ID.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "Environment": { + "description": "An execution environment for an agent.", + "type": "object", + "properties": { + "id": { + "description": "Required. Output only. The ID of the environment.", + "type": "string", + "readOnly": true + }, + "network": { + "description": "Network configuration for the environment.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentNetworkEgressAllowlist" + }, + { + "type": "string", + "enum": [ + "disabled" + ], + "x-google-enum-descriptions": [ + "All network egress is blocked." + ] + } + ] + }, + "sources": { + "description": "Sources to be mounted into the environment.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Source" + } + }, + "created": { + "description": "Output only. The time at which the environment was created in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "updated": { + "description": "Output only. The time at which the environment was last updated in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "last_accessed": { + "description": "Output only. The time at which the environment was last accessed in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "status": { + "description": "Output only. The status of the environment container.", + "type": "string", + "enum": [ + "active", + "expired" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "", + "" + ] + }, + "file_count": { + "description": "Output only. The number of files in the environment, output only.", + "type": "string", + "format": "int64", + "readOnly": true + }, + "size_bytes": { + "description": "Output only. The total size of the environment files in bytes, output only.", + "type": "string", + "format": "int64", + "readOnly": true + } + }, + "required": [ + "id" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "EnvironmentConfig": { + "description": "Configuration for a custom environment.", + "type": "object", + "properties": { + "type": { + "const": "remote" + }, + "network": { + "description": "Network configuration for the environment.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentNetworkEgressAllowlist" + }, + { + "type": "string", + "enum": [ + "disabled" + ], + "x-google-enum-descriptions": [ + "All network egress is blocked." + ] + } + ] + }, + "sources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Source" + } + }, + "environment_id": { + "description": "Optional. The environment ID for the interaction. If specified, the request will\nupdate the existing environment instead of creating a new one.", + "type": "string" + }, + "env": { + "description": "Environment variables to set in the sandbox environment.", + "oneOf": [ + { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/EnvVar" + } + }, + { + "type": "string" + } + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "inline_sources": { + "summary": "Inline Sources", + "value": { + "type": "remote", + "sources": [ + { + "type": "inline", + "content": "You are a data analyst. Always include visualizations and export results as PDF.", + "target": ".agents/AGENTS.md" + }, + { + "type": "inline", + "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html", + "target": ".agents/skills/slide-maker/SKILL.md" + } + ] + } + } + }, + { + "external_sources": { + "summary": "External Sources", + "value": { + "type": "remote", + "sources": [ + { + "type": "repository", + "source": "https://github.com/my-org/my-skills.git", + "target": ".agents/skills" + }, + { + "type": "gcs", + "source": "gs://my-bucket/my-folder", + "target": "/workspace/data" + } + ] + } + } + }, + { + "network_allowlist": { + "summary": "Network Allowlist", + "value": { + "type": "remote", + "network": { + "allowlist": [ + { + "domain": "pypi.org" + }, + { + "domain": "*.github.com" + } + ] + } + } + } + }, + { + "proxy_credentials": { + "summary": "Proxy Credentials", + "value": { + "type": "remote", + "network": { + "allowlist": [ + { + "domain": "api.github.com", + "transform": { + "Authorization": "Bearer YOUR_GITHUB_TOKEN" + } + } + ] + } + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "EnvironmentFile": { + "description": "Metadata for a file or directory within an environment.", + "type": "object", + "properties": { + "name": { + "description": "Output only. The name of the file or directory (e.g., \"main.py\" or \"src\").", + "type": "string", + "readOnly": true + }, + "path": { + "description": "Output only. The full relative path within the environment\n(e.g., \"workspace/src/main.py\").", + "type": "string", + "readOnly": true + }, + "type": { + "description": "Output only. The type of the entry.", + "type": "string", + "enum": [ + "file", + "directory" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "A regular file.", + "A directory." + ] + }, + "size_bytes": { + "description": "Output only. The size of the file/directory in bytes.\nNOLINT", + "type": "string", + "format": "int64", + "readOnly": true + }, + "mime_type": { + "description": "Output only. The MIME type of the file (e.g., \"text/python\", \"image/png\").\nEmpty for directories.\nNOLINT", + "type": "string", + "readOnly": true + }, + "created": { + "description": "Output only. The creation time of the file/directory.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "modified": { + "description": "Output only. The modification time of the file/directory.", + "type": "string", + "format": "date-time", + "readOnly": true + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "EnvironmentNetworkEgressAllowlist": { + "description": "Network egress configuration for the environment.", + "type": "object", + "properties": { + "allowlist": { + "description": "List of allowed domains and their configurations. Set to `\"disabled\"`\nto block all network egress.", + "oneOf": [ + { + "type": "array", + "items": { + "$ref": "#/components/schemas/EgressRule" + } + }, + { + "type": "string", + "enum": [ + "disabled" + ], + "x-google-enum-descriptions": [ + "All network egress is blocked." + ] + } + ] + } + }, + "examples": [ + { + "network_allowlist": { + "summary": "Network Allowlist", + "value": { + "allowlist": [ + { + "domain": "github.com", + "transform": [ + { + "Authorization": "Bearer your-token" + } + ] + }, + { + "domain": "*.googleapis.com" + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "EnvironmentVariableConfig": { + "description": "Configuration for environment variable credentials.", + "type": "object", + "properties": { + "value": { + "description": "Required. Input only. Secret value of the environment variable. Write-only; never\nreturned in responses.", + "type": "string", + "writeOnly": true + }, + "injection_location": { + "description": "Required. Locations where the environment variable can be injected in\noutgoing HTTP requests. Must contain at least one location.\nAccepts either a single location (e.g. \"header\") or an array of locations.", + "oneOf": [ + { + "$ref": "#/components/schemas/InjectionLocation" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InjectionLocation" + } + } + ] + }, + "id": { + "type": "string" + }, + "type": { + "const": "environment_variable" + }, + "trusted_domains": { + "description": "Optional. List of domains allowed to receive this environment variable\nvalue in HTTP requests.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "id", + "injection_location", + "type", + "value" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "EnvironmentVariableUpdateConfig": { + "description": "Configuration for updating environment variable credentials.", + "type": "object", + "properties": { + "type": { + "const": "environment_variable" + }, + "value": { + "description": "Optional. Input only. Secret value of the environment variable. Write-only; never\nreturned in responses.", + "type": "string", + "writeOnly": true + }, + "trusted_domains": { + "description": "Optional. List of domains allowed to receive this environment variable\nvalue in HTTP requests.", + "type": "array", + "items": { + "type": "string" + } + }, + "injection_location": { + "description": "Optional. Locations where the environment variable can be injected in\noutgoing HTTP requests.\nAccepts either a single location (e.g. \"header\") or an array of locations.", + "oneOf": [ + { + "$ref": "#/components/schemas/InjectionLocation" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InjectionLocation" + } + } + ] + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Error": { + "description": "Error message from an interaction.", + "type": "object", + "properties": { + "code": { + "description": "A URI that identifies the error type.", + "type": "string" + }, + "message": { + "description": "A human-readable error message.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ErrorEvent": { + "type": "object", + "properties": { + "event_type": { + "const": "error" + }, + "error": { + "$ref": "#/components/schemas/Error" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + } + }, + "required": [ + "event_type" + ], + "examples": [ + { + "error_event": { + "summary": "Error Event", + "value": { + "error": { + "code": "not_found", + "message": "Failed to get completed interaction: Result not found." + }, + "event_type": "error" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FileCitation": { + "description": "A file citation annotation.", + "type": "object", + "properties": { + "type": { + "const": "file_citation" + }, + "document_uri": { + "description": "The URI of the file.", + "type": "string" + }, + "file_name": { + "description": "The name of the file.", + "type": "string" + }, + "source": { + "description": "Source attributed for a portion of the text.", + "type": "string" + }, + "custom_metadata": { + "description": "User provided metadata about the retrieved context.", + "type": "object", + "additionalProperties": { + "description": "Properties of the object." + } + }, + "page_number": { + "description": "Page number of the cited document, if applicable.", + "type": "integer", + "format": "int32" + }, + "media_id": { + "description": "Media ID in-case of image citations, if applicable.", + "type": "string" + }, + "start_index": { + "description": "Start of segment of the response that is attributed to this source.\n\nIndex indicates the start of the segment, measured in bytes.", + "type": "integer", + "format": "int32" + }, + "end_index": { + "description": "End of the attributed segment, exclusive.", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FileSearch": { + "description": "A tool that can be used by the model to search files.", + "type": "object", + "properties": { + "type": { + "const": "file_search" + }, + "file_search_store_names": { + "description": "The file search store names to search.", + "type": "array", + "items": { + "type": "string" + } + }, + "top_k": { + "description": "The number of semantic retrieval chunks to retrieve.", + "type": "integer", + "format": "int32" + }, + "metadata_filter": { + "description": "Metadata filter to apply to the semantic retrieval documents and chunks.", + "type": "string" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "file_search", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"file_search\",\n \"file_search_store_names\": [\"fileSearchStores/m64d1sevsr4y-xfyawui3fxqg\"]\n }],\n \"input\": \"Who is the author of the book?\"\n }'\n" + }, + { + "label": "file_search", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\n\n# Create a file search store so we have a valid one to use.\nstore = client.file_search_stores.create()\n\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[\n {\"type\": \"file_search\", \"file_search_store_names\": [store.name]}\n ],\n input=\"What documents are available?\",\n)\nprint(response.output_text)\n" + }, + { + "label": "file_search", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\n\n// Create a file search store so we have a valid one to use.\nconst store = await ai.fileSearchStores.create({});\nif (!store.name) {\n throw new Error('Store creation failed: Name is undefined');\n}\n\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [\n {\n type: 'file_search',\n file_search_store_names: [store.name],\n },\n ],\n input: 'What documents are available?',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "file_search", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.types.CreateFileSearchStoreConfig;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.FileSearch;\nimport com.google.genai.types.FileSearchStore;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\n\n// Create a file search store so we have a valid one to use.\nFileSearchStore store =\n client.fileSearchStores.create(CreateFileSearchStoreConfig.builder().build());\nString storeName = store.name().orElseThrow();\n\nFileSearch tool = FileSearch.builder().fileSearchStoreNames(List.of(storeName)).build();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(tool))\n .input(InteractionsInput.of(\"What documents are available?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "file_search", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n\n tool := gaos_interactions.NewTool(gaos_interactions.FileSearch{\n FileSearchStoreNames: []string{store.Name},\n })\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"What documents are available?\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "FileSearchCallDelta": { + "type": "object", + "properties": { + "type": { + "const": "file_search_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FileSearchCallStep": { + "description": "File Search call step.", + "type": "object", + "properties": { + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "file_search_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "id", + "type" + ], + "examples": [ + { + "file_search_call": { + "summary": "FileSearchCallStep", + "value": { + "type": "file_search_call", + "id": "file_call_88192" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FileSearchResult": { + "description": "The result of the File Search.", + "type": "object", + "x-speakeasy-model-namespace": "interactions" + }, + "FileSearchResultDelta": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FileSearchResult" + } + }, + "type": { + "const": "file_search_result" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "result", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FileSearchResultStep": { + "description": "File Search result step.", + "type": "object", + "properties": { + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "file_search_result" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "call_id", + "type" + ], + "examples": [ + { + "file_search_result": { + "summary": "FileSearchResultStep", + "value": { + "type": "file_search_result", + "call_id": "file_call_88192" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Function": { + "description": "A tool that can be used by the model.", + "type": "object", + "properties": { + "type": { + "const": "function" + }, + "name": { + "description": "The name of the function.", + "type": "string" + }, + "description": { + "description": "A description of the function.", + "type": "string" + }, + "parameters": { + "description": "The JSON Schema for the function's parameters.\n\nSupports a subset of JSON Schema. `minLength`, `maxLength`,\n`minProperties`, `maxProperties`, `uniqueItems`, `contains`,\n`minContains`, and `maxContains` are ignored and not enforced." + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "function_calling", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"function\",\n \"name\": \"get_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\"\n }\n },\n \"required\": [\"location\"]\n }\n }],\n \"input\": \"What is the weather like in Boston, MA?\"\n }'\n" + }, + { + "label": "function_calling", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[{\n \"type\": \"function\",\n \"name\": \"get_weather\",\n \"description\": \"Get the current weather in a given location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": (\n \"The city and state, e.g. San Francisco, CA\"\n ),\n }\n },\n \"required\": [\"location\"],\n },\n }],\n input=\"What is the weather like in Boston?\",\n)\nprint(response.steps[-1])\n" + }, + { + "label": "function_calling", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [\n {\n type: 'function',\n name: 'get_weather',\n description: 'Get the current weather in a given location',\n parameters: {\n type: 'object',\n properties: {\n location: {\n type: 'string',\n description: 'The city and state, e.g. San Francisco, CA',\n },\n },\n required: ['location'],\n },\n },\n ],\n input: 'What is the weather like in Boston?',\n});\nconsole.log(interaction.steps.at(-1));\n" + }, + { + "label": "function_calling", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Function;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.Step;\n\nClient client = new Client();\nMap parameters =\n Map.of(\n \"type\", \"object\",\n \"properties\",\n Map.of(\n \"location\",\n Map.of(\n \"type\", \"string\",\n \"description\", \"The city and state, e.g. San Francisco, CA\")),\n \"required\", List.of(\"location\"));\nFunction functionTool =\n Function.builder()\n .name(\"get_weather\")\n .description(\"Get the current weather in a given location\")\n .parameters(parameters)\n .build();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(functionTool))\n .input(InteractionsInput.of(\"What is the weather like in Boston?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nList steps = interaction.steps().orElse(List.of());\nif (!steps.isEmpty()) {\n System.out.println(steps.get(steps.size() - 1));\n}\n" + }, + { + "label": "function_calling", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n function := gaos_interactions.Function{\n Name: genai.Ptr(\"get_weather\"),\n Description: genai.Ptr(\"Get the current weather in a given location\"),\n Parameters: map[string]any{\n \"type\": \"object\",\n \"properties\": map[string]any{\n \"location\": map[string]any{\n \"type\": \"string\",\n \"description\": \"The city and state, e.g. San Francisco, CA\",\n },\n },\n \"required\": []string{\"location\"},\n },\n }\n\n tool := gaos_interactions.NewTool(function)\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"What is the weather like in Boston, MA?\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil {\n for _, step := range res.Interaction.Steps {\n if step.FunctionCallStep != nil {\n fmt.Println(\"Function Call:\", step.FunctionCallStep.Name)\n fmt.Println(\"Arguments:\", step.FunctionCallStep.Arguments)\n }\n }\n }\n}\n" + } + ] + }, + "FunctionCallStep": { + "description": "A function tool call step.", + "type": "object", + "properties": { + "name": { + "description": "Required. The name of the tool to call.", + "type": "string" + }, + "arguments": { + "description": "Required. The arguments to pass to the function.", + "type": "object", + "additionalProperties": { + "description": "Properties of the object." + } + }, + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "function_call" + } + }, + "required": [ + "arguments", + "id", + "name", + "type" + ], + "examples": [ + { + "function_call": { + "summary": "FunctionCallStep", + "value": { + "name": "get_weather", + "type": "function_call", + "arguments": { + "location": "Boston, MA" + }, + "id": "call_98231" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FunctionResultDelta": { + "type": "object", + "properties": { + "result": { + "oneOf": [ + { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ImageContent" + }, + { + "$ref": "#/components/schemas/TextContent" + } + ] + } + }, + { + "type": "object" + }, + { + "type": "string" + } + ] + }, + "type": { + "const": "function_result" + }, + "name": { + "type": "string" + }, + "is_error": { + "type": "boolean" + } + }, + "required": [ + "result", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "FunctionResultStep": { + "description": "Result of a function tool call.", + "type": "object", + "properties": { + "result": { + "description": "Required. The result of the tool call.", + "oneOf": [ + { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ImageContent" + }, + { + "$ref": "#/components/schemas/TextContent" + } + ] + } + }, + { + "type": "object" + }, + { + "type": "string" + } + ] + }, + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "function_result" + }, + "name": { + "description": "The name of the tool that was called.", + "type": "string" + }, + "is_error": { + "description": "Whether the tool call resulted in an error.", + "type": "boolean" + } + }, + "required": [ + "call_id", + "result", + "type" + ], + "examples": [ + { + "function_result": { + "summary": "FunctionResultStep", + "value": { + "name": "get_weather", + "type": "function_result", + "call_id": "call_98231", + "result": [ + { + "type": "text", + "text": "{\"weather\":\"sunny\"}" + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GenerationConfig": { + "description": "Configuration parameters for model interactions.", + "type": "object", + "properties": { + "tool_choice": { + "description": "The tool choice configuration.", + "oneOf": [ + { + "$ref": "#/components/schemas/ToolChoiceConfig" + }, + { + "type": "string", + "enum": [ + "auto", + "any", + "none", + "validated" + ], + "x-google-enum-descriptions": [ + "Auto tool choice.", + "Any tool choice.", + "No tool choice.", + "Validated tool choice." + ], + "x-speakeasy-model-namespace": "interactions" + } + ] + }, + "temperature": { + "description": "Controls the randomness of the output.", + "type": "number", + "deprecated": true, + "format": "float" + }, + "top_p": { + "description": "The maximum cumulative probability of tokens to consider when sampling.", + "type": "number", + "deprecated": true, + "format": "float" + }, + "seed": { + "description": "Seed used in decoding for reproducibility.", + "type": "integer", + "format": "int32" + }, + "stop_sequences": { + "description": "A list of character sequences that will stop output interaction.", + "type": "array", + "items": { + "type": "string" + } + }, + "thinking_level": { + "description": "The level of thought tokens that the model should generate.", + "$ref": "#/components/schemas/ThinkingLevel" + }, + "thinking_summaries": { + "description": "Whether to include thought summaries in the response.", + "$ref": "#/components/schemas/ThinkingSummaries" + }, + "max_output_tokens": { + "description": "The maximum number of tokens to include in the response.", + "type": "integer", + "format": "int32" + }, + "image_config": { + "description": "Configuration for image interaction.", + "$ref": "#/components/schemas/ImageConfig", + "deprecated": true + }, + "video_config": { + "description": "Configuration for video generation.", + "$ref": "#/components/schemas/VideoConfig" + }, + "transcription_config": { + "description": "Optional. Configuration for speech recognition (transcription). If present, ASR is\nenabled.", + "$ref": "#/components/schemas/TranscriptionConfig" + }, + "structured_speech_config": { + "description": "Speech and multi-speaker configuration.", + "oneOf": [ + { + "$ref": "#/components/schemas/SpeakerConfig" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/SpeechConfig" + } + } + ] + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GetEnvironmentFilesResponse": { + "description": "Response for `GetEnvironmentFiles`.", + "type": "object", + "properties": { + "files": { + "description": "If the requested path is a directory, this contains its contents.\nIf the requested path is a file, this contains a single entry with the\nfile's metadata.\nIf alt=media was specified, this is empty (content is served via `blob`).", + "type": "array", + "items": { + "$ref": "#/components/schemas/EnvironmentFile" + } + }, + "next_page_token": { + "description": "Pagination token for directory listing.\nNOLINT", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMaps": { + "description": "A tool that can be used by the model to call Google Maps.", + "type": "object", + "properties": { + "type": { + "const": "google_maps" + }, + "enable_widget": { + "description": "Whether to return a widget context token in the tool call result of the\nresponse.", + "type": "boolean" + }, + "latitude": { + "description": "The latitude of the user's location.", + "type": "number", + "format": "double" + }, + "longitude": { + "description": "The longitude of the user's location.", + "type": "number", + "format": "double" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "google_maps", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"google_maps\",\n \"latitude\": 37.7749,\n \"longitude\": -122.4194\n }],\n \"input\": \"What is the best food near me?\"\n }'\n" + }, + { + "label": "google_maps", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[\n {\"type\": \"google_maps\", \"latitude\": 37.7749, \"longitude\": -122.4194}\n ],\n input=\"What is the best food near me?\",\n)\nprint(response.output_text)\n" + }, + { + "label": "google_maps", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [\n {\n type: 'google_maps',\n latitude: 37.7749,\n longitude: -122.4194,\n },\n ],\n input: 'What is the best food near me?',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "google_maps", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.GoogleMaps;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nGoogleMaps tool = GoogleMaps.builder().latitude(37.7749).longitude(-122.4194).build();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(tool))\n .input(InteractionsInput.of(\"What is the best food near me?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "google_maps", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n tool := gaos_interactions.NewTool(gaos_interactions.GoogleMaps{\n Latitude: genai.Ptr(37.7749),\n Longitude: genai.Ptr(-122.4194),\n })\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"What is the best food near me?\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "GoogleMapsCallArguments": { + "description": "The arguments to pass to the Google Maps tool.", + "type": "object", + "properties": { + "queries": { + "description": "The queries to be executed.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMapsCallDelta": { + "type": "object", + "properties": { + "type": { + "const": "google_maps_call" + }, + "arguments": { + "description": "The arguments to pass to the Google Maps tool.", + "$ref": "#/components/schemas/GoogleMapsCallArguments" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMapsCallStep": { + "description": "Google Maps call step.", + "type": "object", + "properties": { + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "google_maps_call" + }, + "arguments": { + "description": "The arguments to pass to the Google Maps tool.", + "$ref": "#/components/schemas/GoogleMapsCallStepArguments" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "id", + "type" + ], + "examples": [ + { + "google_maps_call": { + "summary": "GoogleMapsCallStep", + "value": { + "type": "google_maps_call", + "arguments": { + "latitude": 37.7749, + "longitude": -122.4194 + }, + "id": "maps_call_39201" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMapsCallStepArguments": { + "description": "The arguments to pass to the Google Maps tool.", + "type": "object", + "properties": { + "queries": { + "description": "The queries to be executed.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "GoogleMapsCallArguments" + }, + "GoogleMapsResult": { + "description": "The result of the Google Maps.", + "type": "object", + "properties": { + "places": { + "description": "The places that were found.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Places" + } + }, + "widget_context_token": { + "description": "Resource name of the Google Maps widget context token.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMapsResultDelta": { + "type": "object", + "properties": { + "type": { + "const": "google_maps_result" + }, + "result": { + "description": "The results of the Google Maps.", + "type": "array", + "items": { + "$ref": "#/components/schemas/GoogleMapsResult" + } + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMapsResultItem": { + "description": "The result of the Google Maps.", + "type": "object", + "properties": { + "places": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GoogleMapsResultPlaces" + } + }, + "widget_context_token": { + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "GoogleMapsResult" + }, + "GoogleMapsResultPlaces": { + "type": "object", + "properties": { + "place_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "url": { + "type": "string" + }, + "review_snippets": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReviewSnippet" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleMapsResultStep": { + "description": "Google Maps result step.", + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GoogleMapsResultItem" + } + }, + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "google_maps_result" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "call_id", + "result", + "type" + ], + "examples": [ + { + "google_maps_result": { + "summary": "GoogleMapsResultStep", + "value": { + "type": "google_maps_result", + "call_id": "maps_call_39201", + "result": [ + { + "name": "Golden Gate Park", + "place_id": "ChIJIQBpAG2ahYAR9R7bNdTLg8M", + "rating": 4.8 + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleSearch": { + "description": "A tool that can be used by the model to search Google.", + "type": "object", + "properties": { + "type": { + "const": "google_search" + }, + "search_types": { + "description": "The types of search grounding to enable.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "web_search", + "image_search" + ], + "x-google-enum-descriptions": [ + "Setting this field enables web search. Only text results are returned.", + "Setting this field enables image search. Image bytes are returned." + ] + } + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "google_search", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"google_search\"\n }],\n \"input\": \"Who is the current president of France?\"\n }'\n" + }, + { + "label": "google_search", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[{\"type\": \"google_search\"}],\n input=\"Who is the current president of France?\",\n)\nprint(response.output_text)\n" + }, + { + "label": "google_search", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [{type: 'google_search'}],\n input: 'Who is the current president of France?',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "google_search", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.GoogleSearch;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\n\nClient client = new Client();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(new GoogleSearch()))\n .input(InteractionsInput.of(\"Who is the current president of France?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "google_search", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n tool := gaos_interactions.NewTool(gaos_interactions.GoogleSearch{})\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Who is the current president of France?\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "GoogleSearchCallArguments": { + "description": "The arguments to pass to Google Search.", + "type": "object", + "properties": { + "queries": { + "description": "Web search queries for the following-up web search.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleSearchCallDelta": { + "type": "object", + "properties": { + "arguments": { + "$ref": "#/components/schemas/GoogleSearchCallArguments" + }, + "type": { + "const": "google_search_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "arguments", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleSearchCallStep": { + "description": "Google Search call step.", + "type": "object", + "properties": { + "arguments": { + "description": "Required. The arguments to pass to Google Search.", + "$ref": "#/components/schemas/GoogleSearchCallStepArguments" + }, + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "google_search_call" + }, + "search_type": { + "description": "The type of search grounding enabled.", + "type": "string", + "enum": [ + "web_search", + "image_search" + ], + "x-google-enum-descriptions": [ + "Setting this field enables web search. Only text results are returned.", + "Setting this field enables image search. Image bytes are returned." + ] + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "arguments", + "id", + "type" + ], + "examples": [ + { + "google_search_call": { + "summary": "GoogleSearchCallStep", + "value": { + "type": "google_search_call", + "arguments": { + "query": "Who won the men's 100m in Paris 2024?" + }, + "id": "search_call_19201" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleSearchCallStepArguments": { + "description": "The arguments to pass to Google Search.", + "type": "object", + "properties": { + "queries": { + "description": "Web search queries for the following-up web search.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "GoogleSearchCallArguments" + }, + "GoogleSearchResult": { + "description": "The result of the Google Search.", + "type": "object", + "properties": { + "search_suggestions": { + "description": "Web content snippet that can be embedded in a web page or an app webview.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleSearchResultDelta": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GoogleSearchResult" + } + }, + "type": { + "const": "google_search_result" + }, + "is_error": { + "type": "boolean" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "result", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GoogleSearchResultItem": { + "description": "The result of the Google Search.", + "type": "object", + "properties": { + "search_suggestions": { + "description": "Web content snippet that can be embedded in a web page or an app webview.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "GoogleSearchResult" + }, + "GoogleSearchResultStep": { + "description": "Google Search result step.", + "type": "object", + "properties": { + "result": { + "description": "Required. The results of the Google Search.", + "type": "array", + "items": { + "$ref": "#/components/schemas/GoogleSearchResultItem" + } + }, + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "google_search_result" + }, + "is_error": { + "description": "Whether the Google Search resulted in an error.", + "type": "boolean" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "call_id", + "result", + "type" + ], + "examples": [ + { + "google_search_result": { + "summary": "GoogleSearchResultStep", + "value": { + "type": "google_search_result", + "call_id": "search_call_19201", + "result": [ + { + "title": "Paris 2024 Olympics: Noah Lyles wins men's 100m gold", + "url": "https://olympics.com/en/news/paris-2024-noah-lyles-wins-mens-100m-gold", + "snippet": "American Noah Lyles won the Olympic men's 100m gold medal in a photo finish." + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "GroundingToolCount": { + "description": "The number of grounding tool counts.", + "type": "object", + "properties": { + "type": { + "description": "The grounding tool type associated with the count.", + "type": "string", + "enum": [ + "google_search", + "google_maps" + ], + "x-google-enum-descriptions": [ + "Grounding with Google Web Search and Image Search, & Web Grounding\nfor Enterprise.", + "Grounding with Google Maps." + ] + }, + "count": { + "description": "The number of grounding tool counts.", + "type": "integer", + "format": "int32" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "HarmCategory": { + "type": "string", + "enum": [ + "hate_speech", + "dangerous_content", + "harassment", + "sexually_explicit", + "jailbreak" + ], + "x-google-enum-descriptions": [ + "Content that promotes violence or incites hatred against individuals or\ngroups based on certain attributes.", + "Content that promotes, facilitates, or enables dangerous activities.", + "Abusive, threatening, or content intended to bully, torment, or ridicule.", + "Content that contains sexually explicit material.", + "Prompts designed to bypass safety filters." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "HttpBearerConfig": { + "description": "Configuration for HTTP Bearer token credentials.", + "type": "object", + "properties": { + "token": { + "description": "Required. Input only. The static bearer token. Write-only; never returned in responses.", + "type": "string", + "writeOnly": true + }, + "id": { + "type": "string" + }, + "type": { + "const": "bearer_token" + }, + "header_name": { + "description": "Optional. Header name to inject the token into. Defaults to\n'Authorization'.", + "type": "string" + }, + "prefix": { + "description": "Optional. Prefix to prepend to the token. Defaults to 'Bearer'. Set to ''\nfor no prefix.", + "type": "string" + } + }, + "required": [ + "id", + "token", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "HttpBearerUpdateConfig": { + "description": "Configuration for updating HTTP Bearer token credentials.", + "type": "object", + "properties": { + "type": { + "const": "bearer_token" + }, + "token": { + "description": "Optional. Input only. The static bearer token. Write-only; never returned in responses.", + "type": "string", + "writeOnly": true + }, + "header_name": { + "description": "Optional. Header name to inject the token into. Defaults to\n'Authorization'.", + "type": "string" + }, + "prefix": { + "description": "Optional. Prefix to prepend to the token. Defaults to 'Bearer'. Set to ''\nfor no prefix.", + "type": "string" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "HttpBody": { + "description": "Message that represents an arbitrary HTTP body. It should only be used for\npayload formats that can't be represented as JSON, such as raw binary or\nan HTML page.\n\n\nThis message can be used both in streaming and non-streaming API methods in\nthe request as well as the response.\n\nIt can be used as a top-level request field, which is convenient if one\nwants to extract parameters from either the URL or HTTP template into the\nrequest fields and also want access to the raw HTTP body.\n\nExample:\n\n message GetResourceRequest {\n // A unique request id.\n string request_id = 1;\n\n // The raw HTTP body is bound to this field.\n google.api.HttpBody http_body = 2;\n\n }\n\n service ResourceService {\n rpc GetResource(GetResourceRequest)\n returns (google.api.HttpBody);\n rpc UpdateResource(google.api.HttpBody)\n returns (google.protobuf.Empty);\n\n }\n\nExample with streaming methods:\n\n service CaldavService {\n rpc GetCalendar(stream google.api.HttpBody)\n returns (stream google.api.HttpBody);\n rpc UpdateCalendar(stream google.api.HttpBody)\n returns (stream google.api.HttpBody);\n\n }\n\nUse of this type only changes how the request and response bodies are\nhandled, all other features will continue to work unchanged.", + "type": "object", + "properties": { + "content_type": { + "description": "The HTTP Content-Type header value specifying the content type of the body.", + "type": "string" + }, + "data": { + "description": "The HTTP request/response body as raw binary.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "extensions": { + "description": "Application specific response metadata. Must be set in the first response\nfor streaming APIs.", + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "description": "Properties of the object. Contains field @type with type URL." + } + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ImageConfig": { + "description": "The configuration for image interaction.", + "type": "object", + "properties": { + "aspect_ratio": { + "description": "The aspect ratio of the image to generate. Supported aspect ratios: 1:1,\n2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9.\n\nIf not specified, the model will choose a default aspect ratio based on any\nreference images provided.", + "type": "string" + }, + "image_size": { + "description": "Specifies the size of generated images. Supported values are `1K`, `2K`,\n`4K`. If not specified, the model will use default value `1K`.", + "type": "string" + } + }, + "deprecated": true, + "x-speakeasy-model-namespace": "interactions" + }, + "ImageContent": { + "description": "An image content block.", + "type": "object", + "properties": { + "type": { + "const": "image" + }, + "data": { + "description": "The image content.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "description": "The URI of the image.", + "type": "string" + }, + "resolution": { + "description": "The resolution of the media.", + "$ref": "#/components/schemas/MediaResolution" + }, + "mime_type": { + "description": "The mime type of the image.", + "type": "string", + "enum": [ + "image/png", + "image/jpeg", + "image/webp", + "image/heic", + "image/heif", + "image/gif", + "image/bmp", + "image/tiff" + ], + "x-google-enum-descriptions": [ + "PNG image format", + "JPEG image format", + "WebP image format", + "HEIC image format", + "HEIF image format", + "GIF image format", + "BMP image format", + "TIFF image format" + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "image": { + "summary": "Image", + "value": { + "type": "image", + "data": "BASE64_ENCODED_IMAGE", + "mime_type": "image/png" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ImageDelta": { + "type": "object", + "properties": { + "type": { + "const": "image" + }, + "data": { + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "type": "string" + }, + "mime_type": { + "type": "string", + "enum": [ + "image/png", + "image/jpeg", + "image/webp", + "image/heic", + "image/heif", + "image/gif", + "image/bmp", + "image/tiff" + ], + "x-google-enum-descriptions": [ + "PNG image format", + "JPEG image format", + "WebP image format", + "HEIC image format", + "HEIF image format", + "GIF image format", + "BMP image format", + "TIFF image format" + ] + }, + "resolution": { + "description": "The resolution of the media.", + "$ref": "#/components/schemas/MediaResolution" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ImageResponseFormat": { + "description": "Configuration for image output format.", + "type": "object", + "properties": { + "type": { + "const": "image" + }, + "mime_type": { + "description": "The MIME type of the image output.", + "type": "string", + "enum": [ + "image/jpeg" + ], + "x-google-enum-descriptions": [ + "JPEG image format." + ] + }, + "delivery": { + "description": "The delivery mode for the image output.", + "type": "string", + "enum": [ + "inline", + "uri" + ], + "x-google-enum-descriptions": [ + "Image data is returned inline in the response.", + "Image data is returned as a URI." + ] + }, + "aspect_ratio": { + "description": "The aspect ratio for the image output.", + "type": "string", + "enum": [ + "1:1", + "2:3", + "3:2", + "3:4", + "4:3", + "4:5", + "5:4", + "9:16", + "16:9", + "21:9", + "1:8", + "8:1", + "1:4", + "4:1" + ], + "x-google-enum-descriptions": [ + "1:1 aspect ratio.", + "2:3 aspect ratio.", + "3:2 aspect ratio.", + "3:4 aspect ratio.", + "4:3 aspect ratio.", + "4:5 aspect ratio.", + "5:4 aspect ratio.", + "9:16 aspect ratio.", + "16:9 aspect ratio.", + "21:9 aspect ratio.", + "1:8 aspect ratio.", + "8:1 aspect ratio.", + "1:4 aspect ratio.", + "4:1 aspect ratio." + ] + }, + "image_size": { + "description": "The size of the image output.", + "type": "string", + "enum": [ + "512", + "1K", + "2K", + "4K" + ], + "x-google-enum-descriptions": [ + "512px image size.", + "1K image size.", + "2K image size.", + "4K image size." + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "image_response_format": { + "summary": "Image Output", + "value": { + "type": "image", + "aspect_ratio": "16:9", + "image_size": "1K", + "mime_type": "image/jpeg" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "InjectionLocation": { + "type": "string", + "enum": [ + "header", + "query", + "body" + ], + "x-google-enum-descriptions": [ + "Injected into HTTP request headers.", + "Injected into HTTP URL query parameters.", + "Injected into HTTP request body." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Interaction": { + "description": "The Interaction resource.", + "properties": { + "id": { + "description": "Required. Output only. A unique identifier for the interaction completion.", + "type": "string", + "default": "", + "readOnly": true + }, + "status": { + "description": "Required. Output only. The status of the interaction.", + "type": "string", + "enum": [ + "in_progress", + "requires_action", + "completed", + "failed", + "cancelled", + "incomplete", + "budget_exceeded" + ], + "readOnly": true, + "x-google-enum-deprecated": [ + false, + false, + false, + false, + false, + false, + true + ], + "x-google-enum-descriptions": [ + "The interaction is in progress.", + "The interaction requires action/input from the user.", + "The interaction is completed.", + "The interaction failed.", + "The interaction was cancelled.", + "The interaction is completed, but contains incomplete results (e.g.\nhitting max_tokens).", + "Deprecated: Token and execution budget exhaustion returns INCOMPLETE\n(11)." + ] + }, + "created": { + "description": "Required. Output only. The time at which the response was created in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "updated": { + "description": "Required. Output only. The time at which the response was last updated in ISO 8601 format\n(YYYY-MM-DDThh:mm:ssZ).", + "type": "string", + "readOnly": true + }, + "steps": { + "description": "Required. Output only. The steps that make up the interaction, when included in the response.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Step" + }, + "readOnly": true + }, + "model": { + "description": "The name of the `Model` used for generating the interaction.", + "$ref": "#/components/schemas/ModelOption" + }, + "generation_config": { + "description": "Input only. Configuration parameters for the model interaction.", + "$ref": "#/components/schemas/GenerationConfig", + "writeOnly": true + }, + "input": { + "$ref": "#/components/schemas/InteractionsInput" + }, + "response_format": { + "description": "Enforces that the generated response is a JSON object that complies with\nthe JSON schema specified in this field.", + "oneOf": [ + { + "$ref": "#/components/schemas/ResponseFormat" + }, + { + "title": "ResponseFormatList", + "type": "array", + "items": { + "$ref": "#/components/schemas/ResponseFormat" + } + } + ] + }, + "environment": { + "description": "The environment configuration for the interaction. Can be an object\nspecifying remote environment sources or a string referencing an existing\nenvironment ID.", + "oneOf": [ + { + "$ref": "#/components/schemas/EnvironmentConfig" + }, + { + "type": "string" + } + ] + }, + "system_instruction": { + "description": "System instruction for the interaction.", + "type": "string" + }, + "tools": { + "description": "A list of tool declarations the model may call during interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Tool" + } + }, + "usage": { + "description": "Output only. Statistics on the interaction request's token usage.", + "$ref": "#/components/schemas/Usage", + "readOnly": true + }, + "response_modalities": { + "description": "The requested modalities of the response (TEXT, IMAGE, AUDIO).", + "type": "array", + "deprecated": true, + "items": { + "$ref": "#/components/schemas/ResponseModality" + } + }, + "response_mime_type": { + "description": "The mime type of the response. This is required if response_format is set.", + "type": "string", + "deprecated": true + }, + "previous_interaction_id": { + "description": "The ID of the previous interaction, if any.", + "type": "string" + }, + "environment_id": { + "description": "Output only. The environment ID for the interaction. Only populated if environment\nconfig is set in the request.", + "type": "string", + "readOnly": true + }, + "service_tier": { + "description": "The service tier for the interaction.", + "$ref": "#/components/schemas/ServiceTier" + }, + "webhook_config": { + "description": "Optional. Webhook configuration for receiving notifications when the\ninteraction completes.", + "$ref": "#/components/schemas/WebhookConfig" + }, + "safety_settings": { + "description": "Safety settings for the interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SafetySetting" + } + }, + "labels": { + "description": "The labels with user-defined metadata for the request.\n\nLabel keys and values can be no longer than 63 characters\n(Unicode codepoints) and can only contain lowercase letters, numeric\ncharacters, underscores, and dashes. International characters are allowed.\nLabel values are optional. Label keys must start with a letter.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "errors": { + "description": "Output only. Diagnostic faults / platform errors recorded on the interaction.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "readOnly": true + }, + "stream": { + "description": "Input only. Whether the interaction will be streamed.", + "type": "boolean", + "writeOnly": true + }, + "store": { + "description": "Input only. Whether to store the response and request for later retrieval.", + "type": "boolean", + "writeOnly": true + }, + "background": { + "description": "Input only. Whether to run the model interaction in the background.", + "type": "boolean", + "writeOnly": true + }, + "agent": { + "description": "The name of the `Agent` used for generating the interaction.", + "$ref": "#/components/schemas/AgentOption" + }, + "agent_config": { + "description": "Configuration parameters for the agent interaction.", + "oneOf": [ + { + "$ref": "#/components/schemas/AntigravityAgentConfig" + }, + { + "$ref": "#/components/schemas/DeepResearchAgentConfig" + }, + { + "$ref": "#/components/schemas/DynamicAgentConfig" + } + ] + }, + "max_total_tokens": { + "description": "Max total tokens for the agent run.", + "type": "string", + "format": "int64" + } + }, + "required": [ + "status", + "created", + "id", + "steps", + "updated" + ], + "example": { + "created": "2025-12-04T15:01:45Z", + "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", + "model": "gemini-3.6-flash", + "object": "interaction", + "status": "completed", + "steps": [ + { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "Hello! I'm doing well, functioning as expected. Thank you for asking! How are you doing today?" + } + ] + } + ], + "updated": "2025-12-04T15:01:45Z", + "usage": { + "input_tokens_by_modality": [ + { + "modality": "text", + "tokens": 7 + } + ], + "total_cached_tokens": 0, + "total_input_tokens": 7, + "total_output_tokens": 23, + "total_thought_tokens": 49, + "total_tokens": 79, + "total_tool_use_tokens": 0 + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "InteractionCompletedEvent": { + "description": "Signals that the Interaction completed. Sent when the Interaction receives\nComplete/Cancel or naturally terminates. No more input can be sent to the\nInteraction after this.", + "type": "object", + "properties": { + "interaction": { + "description": "Required. Partial completed interaction resource emitted at the end of the stream.", + "$ref": "#/components/schemas/InteractionSseEventInteraction" + }, + "event_type": { + "const": "interaction.completed" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + } + }, + "required": [ + "event_type", + "interaction" + ], + "examples": [ + { + "interaction_completed": { + "summary": "Interaction Completed", + "value": { + "event_id": "evt_123", + "event_type": "interaction.completed", + "interaction": { + "created": "2025-12-04T15:01:45Z", + "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", + "model": "gemini-3.6-flash", + "status": "completed", + "updated": "2025-12-04T15:01:45Z" + } + } + } + }, + { + "interaction_completed": { + "summary": "Interaction Completed", + "value": { + "event_id": "evt_123", + "event_type": "interaction.completed", + "interaction": { + "created": "2025-12-04T15:01:45Z", + "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", + "model": "gemini-3-flash-preview", + "object": "interaction", + "status": "completed", + "updated": "2025-12-04T15:01:45Z" + } + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "InteractionCreatedEvent": { + "description": "Server response confirming that a new interaction was created.", + "type": "object", + "properties": { + "interaction": { + "description": "Required. Partial interaction resource emitted when the stream is created.", + "$ref": "#/components/schemas/InteractionSseEventInteraction" + }, + "event_type": { + "const": "interaction.created" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + } + }, + "required": [ + "event_type", + "interaction" + ], + "examples": [ + { + "interaction_created": { + "summary": "Interaction Created", + "value": { + "event_id": "evt_123", + "event_type": "interaction.created", + "interaction": { + "created": "2025-12-04T15:01:45Z", + "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", + "model": "gemini-3.6-flash", + "status": "in_progress", + "updated": "2025-12-04T15:01:45Z" + } + } + } + }, + { + "interaction_created": { + "summary": "Interaction Created", + "value": { + "event_id": "evt_123", + "event_type": "interaction.created", + "interaction": { + "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", + "model": "gemini-3-flash-preview", + "object": "interaction", + "status": "in_progress" + } + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "InteractionSseEvent": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/ErrorEvent" + }, + { + "$ref": "#/components/schemas/InteractionCompletedEvent" + }, + { + "$ref": "#/components/schemas/InteractionCreatedEvent" + }, + { + "$ref": "#/components/schemas/InteractionStatusUpdate" + }, + { + "$ref": "#/components/schemas/StepDelta" + }, + { + "$ref": "#/components/schemas/StepStart" + }, + { + "$ref": "#/components/schemas/StepStop" + } + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "InteractionSSEEvent" + }, + "InteractionSseEventInteraction": { + "description": "Partial interaction resource emitted by interaction lifecycle SSE events.\nStreaming lifecycle payloads may omit fields that are only available on\nfull non-streaming Interaction responses.\n", + "type": "object", + "properties": { + "id": { + "description": "Required. Output only. A unique identifier for the interaction completion.", + "type": "string", + "readOnly": true + }, + "status": { + "description": "Required. Output only. The status of the interaction.", + "type": "string", + "enum": [ + "in_progress", + "requires_action", + "completed", + "failed", + "cancelled", + "incomplete" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "The interaction is in progress.", + "The interaction requires action/input from the user.", + "The interaction is completed.", + "The interaction failed.", + "The interaction was cancelled.", + "The interaction is completed, but contains incomplete results (e.g. hitting max_tokens)." + ] + }, + "model": { + "description": "The model that will complete your prompt.", + "type": "string" + }, + "created": { + "description": "Output only. The time at which the response was created in ISO 8601 format.", + "type": "string", + "readOnly": true + }, + "updated": { + "description": "Output only. The time at which the response was last updated in ISO 8601 format.", + "type": "string", + "readOnly": true + }, + "usage": { + "description": "Output only. Statistics on the interaction request's token usage.", + "$ref": "#/components/schemas/Usage", + "readOnly": true + }, + "service_tier": { + "description": "The service tier for the interaction.", + "$ref": "#/components/schemas/ServiceTier" + }, + "steps": { + "description": "Output only. The steps that make up the interaction, if included in this event.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Step" + }, + "readOnly": true + }, + "agent": { + "description": "The agent to interact with.", + "type": "string" + }, + "continuation_token": { + "description": "Opaque token to resume a long decode.\nOutput: set when status is INCOMPLETE and decoding can be resumed.\nInput: pass the latest token back unchanged in CreateInteraction to\ncontinue decoding.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "object": { + "description": "Output only. The resource type.", + "type": "string", + "readOnly": true + } + }, + "required": [ + "id", + "status" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "InteractionSseStreamEvent": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/InteractionSseEvent" + } + }, + "required": [ + "data" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "InteractionSSEStreamEvent" + }, + "InteractionStatusUpdate": { + "type": "object", + "properties": { + "interaction_id": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "requires_action", + "completed", + "failed", + "cancelled", + "incomplete", + "budget_exceeded" + ], + "x-google-enum-deprecated": [ + false, + false, + false, + false, + false, + false, + true + ], + "x-google-enum-descriptions": [ + "The interaction is in progress.", + "The interaction requires action/input from the user.", + "The interaction is completed.", + "The interaction failed.", + "The interaction was cancelled.", + "The interaction is completed, but contains incomplete results (e.g.\nhitting max_tokens).", + "Deprecated: Token and execution budget exhaustion returns INCOMPLETE\n(11)." + ] + }, + "event_type": { + "const": "interaction.status_update" + }, + "continuation_token": { + "description": "An optional opaque continuation token used to resume decoding from the\nlatest checkpoint after a disconnected stream.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "usage": { + "description": "Model usage statistics up to this checkpoint.", + "$ref": "#/components/schemas/Usage" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + } + }, + "required": [ + "event_type", + "interaction_id", + "status" + ], + "examples": [ + { + "interaction_status_update": { + "summary": "Interaction Status Update", + "value": { + "event_type": "interaction.status_update", + "interaction_id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM", + "status": "in_progress" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "InteractionsInput": { + "description": "The input for the interaction.", + "oneOf": [ + { + "$ref": "#/components/schemas/Content" + }, + { + "title": "StepList", + "type": "array", + "items": { + "$ref": "#/components/schemas/Step" + } + }, + { + "title": "ContentList", + "type": "array", + "items": { + "$ref": "#/components/schemas/Content" + } + }, + { + "type": "string" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ListAgentsResponse": { + "type": "object", + "properties": { + "agents": { + "description": "The list of agents.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Agent" + } + }, + "next_page_token": { + "description": "A token to retrieve the next page of results.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ListCredentialsResponse": { + "type": "object", + "properties": { + "credentials": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Credential" + } + }, + "next_page_token": { + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ListEnvironmentsResponse": { + "description": "Response for `ListEnvironments`.", + "type": "object", + "properties": { + "environments": { + "description": "Environments belonging to the provided project.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Environment" + } + }, + "next_page_token": { + "description": "Pagination token.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ListTriggerExecutionsResponse": { + "description": "Response message for TriggerService.ListTriggerExecutions.", + "type": "object", + "properties": { + "trigger_executions": { + "description": "The list of trigger executions.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TriggerExecution" + } + }, + "next_page_token": { + "description": "A page token, received from a previous `ListTriggerExecutions` call.\nProvide this to retrieve the subsequent page.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ListTriggersResponse": { + "description": "Response message for TriggerService.ListTriggers.", + "type": "object", + "properties": { + "triggers": { + "description": "The list of triggers.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Trigger" + } + }, + "next_page_token": { + "description": "A page token, received from a previous `ListTriggers` call.\nProvide this to retrieve the subsequent page.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ListVoicesResponse": { + "description": "Response message for `VoicesService.ListVoices`.", + "type": "object", + "properties": { + "voices": { + "description": "The voices from the specified collection.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Voice" + } + }, + "next_page_token": { + "description": "A token that can be sent as `page_token` to retrieve the next page.\nIf empty, there are no subsequent pages.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ListWebhooksResponse": { + "description": "Response message for WebhookService.ListWebhooks.", + "type": "object", + "properties": { + "webhooks": { + "description": "The webhooks.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Webhook" + } + }, + "next_page_token": { + "description": "A token, which can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "McpServer": { + "description": "A MCPServer is a server that can be called by the model to perform actions.", + "type": "object", + "properties": { + "type": { + "const": "mcp_server" + }, + "url": { + "description": "The full URL for the MCPServer endpoint.\nExample: \"https://api.example.com/mcp\"", + "type": "string" + }, + "name": { + "description": "The name of the MCPServer.", + "type": "string" + }, + "headers": { + "description": "Optional: Fields for authentication headers, timeouts, etc., if needed.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "allowed_tools": { + "description": "The allowed tools.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AllowedTools" + } + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-codeSamples": [ + { + "label": "mcp_server", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"mcp_server\",\n \"name\": \"weather_service\",\n \"url\": \"https://gemini-api-demos.uc.r.appspot.com/mcp\"\n }],\n \"input\": \"Today is 12-05-2025, what is the temperature today in London?\"\n }'\n" + }, + { + "label": "mcp_server", + "lang": "python", + "source": "import os\n\nfrom google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[{\n \"type\": \"mcp_server\",\n \"name\": \"weather_service\",\n \"url\": \"https://gemini-api-demos.uc.r.appspot.com/mcp\",\n }],\n input=\"Today is 12-05-2025, what is the temperature today in London?\",\n)\nprint(response.output_text)\n" + }, + { + "label": "mcp_server", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [\n {\n type: 'mcp_server',\n name: 'weather_service',\n url: 'https://gemini-api-demos.uc.r.appspot.com/mcp',\n },\n ],\n input: 'Today is 12-05-2025, what is the temperature today in London?',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "mcp_server", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.MCPServer;\n\nClient client = new Client();\nMCPServer mcpTool =\n MCPServer.builder()\n .name(\"weather_service\")\n .url(\"https://gemini-api-demos.uc.r.appspot.com/mcp\")\n .build();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(mcpTool))\n .input(\n InteractionsInput.of(\n \"Today is 12-05-2025, what is the temperature today in London?\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "mcp_server", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"os\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n mcpServer := gaos_interactions.MCPServer{\n Name: genai.Ptr(\"weather_service\"),\n URL: genai.Ptr(\"https://gemini-api-demos.uc.r.appspot.com/mcp\"),\n }\n tool := gaos_interactions.NewTool(mcpServer)\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Today is 12-05-2025, what is the temperature today in London?\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "McpServerToolCallDelta": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "server_name": { + "type": "string" + }, + "arguments": { + "type": "object", + "additionalProperties": { + "description": "Properties of the object." + } + }, + "type": { + "const": "mcp_server_tool_call" + } + }, + "required": [ + "arguments", + "name", + "server_name", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "McpServerToolCallStep": { + "description": "MCPServer tool call step.", + "type": "object", + "properties": { + "name": { + "description": "Required. The name of the tool which was called.", + "type": "string" + }, + "server_name": { + "description": "Required. The name of the used MCP server.", + "type": "string" + }, + "arguments": { + "description": "Required. The JSON object of arguments for the function.", + "type": "object", + "additionalProperties": { + "description": "Properties of the object." + } + }, + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "mcp_server_tool_call" + } + }, + "required": [ + "arguments", + "id", + "name", + "server_name", + "type" + ], + "examples": [ + { + "mcp_server_tool_call": { + "summary": "McpServerToolCallStep", + "value": { + "name": "calculate_tax", + "type": "mcp_server_tool_call", + "arguments": { + "income": 120000, + "state": "CA" + }, + "id": "mcp_call_29012", + "server_name": "financial_mcp_server" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "McpServerToolResultDelta": { + "type": "object", + "properties": { + "result": { + "oneOf": [ + { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ImageContent" + }, + { + "$ref": "#/components/schemas/TextContent" + } + ] + } + }, + { + "type": "object" + }, + { + "type": "string" + } + ] + }, + "type": { + "const": "mcp_server_tool_result" + }, + "name": { + "type": "string" + }, + "server_name": { + "type": "string" + } + }, + "required": [ + "result", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "McpServerToolResultStep": { + "description": "MCPServer tool result step.", + "type": "object", + "properties": { + "result": { + "description": "Required. The output from the MCP server call. Can be simple text or rich content.", + "oneOf": [ + { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ImageContent" + }, + { + "$ref": "#/components/schemas/TextContent" + } + ] + } + }, + { + "type": "object" + }, + { + "type": "string" + } + ] + }, + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "mcp_server_tool_result" + }, + "name": { + "description": "Name of the tool which is called for this specific tool call.", + "type": "string" + }, + "server_name": { + "description": "The name of the used MCP server.", + "type": "string" + } + }, + "required": [ + "call_id", + "result", + "type" + ], + "examples": [ + { + "mcp_server_tool_result": { + "summary": "McpServerToolResultStep", + "value": { + "name": "calculate_tax", + "type": "mcp_server_tool_result", + "call_id": "mcp_call_29012", + "result": { + "tax_due": 32400 + }, + "server_name": "financial_mcp_server" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "MediaProcessing": { + "oneOf": [ + { + "$ref": "#/components/schemas/StaticMediaProcessing" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "MediaResolution": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "ultra_high" + ], + "x-google-enum-descriptions": [ + "Low resolution.", + "Medium resolution.", + "High resolution.", + "Ultra high resolution." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ModalityTokens": { + "description": "The token count for a single response modality.", + "type": "object", + "properties": { + "modality": { + "description": "The modality associated with the token count.", + "$ref": "#/components/schemas/ResponseModality" + }, + "tokens": { + "description": "Number of tokens for the modality.", + "type": "integer", + "format": "int32" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ModelOption": { + "title": "Model", + "description": "The model that will complete your prompt.\\n\\nSee [models](https://ai.google.dev/gemini-api/docs/models) for additional details.", + "type": "string", + "enum": [ + "gemma-4-26b-a4b-it", + "gemma-4-31b-it", + "gemini-flash-latest", + "gemini-flash-lite-latest", + "gemini-pro-latest", + "gemini-2.5-flash", + "gemini-2.5-pro", + "gemini-2.5-flash-lite", + "gemini-3.5-flash-lite", + "gemini-2.5-flash-image", + "gemini-3-flash-preview", + "gemini-3.1-pro-preview", + "gemini-3.1-pro-preview-customtools", + "gemini-3.1-flash-lite", + "gemini-3.1-flash-lite-image", + "gemini-3-pro-image", + "nano-banana-pro-preview", + "gemini-3.1-flash-image", + "gemini-nano-banana-2.1", + "gemini-3.1-flash-tts-preview", + "gemini-3.5-flash", + "gemini-3.6-flash", + "gemini-3.7-flash", + "gemini-3.8-flash", + "gemini-3.8-flash-tts", + "gemini-3.8-flash-lite-tts", + "lyria-3-clip-preview", + "lyria-3-pro-preview", + "gemini-robotics-er-1.6-preview", + "gemini-robotics-er-2-preview", + "lyria-3.5", + "gemini-omni-1.1-flash", + "gemini-omni-flash-preview" + ], + "x-speakeasy-enum-descriptions": [ + "Gemma 4 26B A4B IT", + "Gemma 4 31B IT", + "Latest release of Gemini Flash", + "Latest release of Gemini Flash-Lite", + "Latest release of Gemini Pro", + "Our first hybrid reasoning model which supports a 1M token context window and has thinking budgets.", + "Our state-of-the-art multipurpose model, which excels at coding and complex reasoning tasks.", + "Our smallest and most cost effective model, built for at scale usage.", + "Gemini 3.5 Flash-Lite - Our fastest, most cost-effective 3.5 model for high-throughput execution.", + "Our native image generation model, optimized for speed, flexibility, and contextual understanding. Text input and output is priced the same as 2.5 Flash.", + "Our most intelligent model built for speed, combining frontier intelligence with superior search and grounding.", + "Our latest SOTA reasoning model with unprecedented depth and nuance, and powerful multimodal understanding and coding capabilities.", + "Gemini 3.1 Pro Preview optimized for custom tool usage", + "Our most cost-efficient model, optimized for high-volume agentic tasks, translation, and simple data processing.", + "Gemini 3.1 Flash Lite Image.", + "Gemini 3 Pro Image", + "Gemini 3 Pro Image Preview", + "Gemini 3.1 Flash Image.", + "Gemini Nano Banana 2.1.", + "Gemini 3.1 Flash TTS: Powerful, low-latency speech generation. Enjoy natural outputs, steerable prompts, and new expressive audio tags for precise narration control.", + "Gemini 3.5 Flash - Our earlier Flash model, built for speed and foundational performance across routine, high-throughput workloads.", + "Gemini 3.6 Flash - Our previous generation Flash model, balancing speed and multimodal capabilities across general agentic and everyday tasks.", + "Gemini 3.7 Flash - Our high-speed, efficient Flash model built for everyday coding, agentic tool use, and reliable multi-step execution.", + "Gemini 3.8 Flash - Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows.", + "Gemini 3.8 Flash TTS - Flagship TTS model for Voice Design and dual-speaker screenplay control. Prompt custom vocal personas, direct line-by-line delivery, and add vocal bursts.", + "Gemini 3.8 Flash Lite TTS - High-speed and cost-efficient, ideal for rapid dubbing, media localization, and high-throughput voice agents. Direct replacement for gemini-3.1-flash-tts-preview.", + "Our low-latency, music generation model optimized for high-fidelity audio clips and precise rhythmic control.", + "Our advanced, full-song generative model with deep compositional understanding, optimized for precise structural control and complex transitions across diverse musical styles.", + "Gemini Robotics-ER 1.6 Preview", + "Gemini Robotics Embodied Reasoning 2 Preview", + "Our flagship music generation model, optimized for full-length songs with complex structural coherence.", + "Our high-performance multimodal model designed for fast, conversational video generation, editing, and cinematic control.", + "Preview release of our multimodal model for conversational video generation, editing, and cinematic control." + ], + "x-speakeasy-enum-format": "union", + "x-speakeasy-exports": [ + { + "name": "model", + "group": "interactions" + }, + { + "name": "model_param", + "group": "interactions" + } + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "Model", + "x-speakeasy-unknown-values": "allow" + }, + "ModelOutputStep": { + "description": "Output generated by the model.", + "type": "object", + "properties": { + "type": { + "const": "model_output" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Content" + } + } + }, + "required": [ + "type" + ], + "examples": [ + { + "model_output": { + "summary": "ModelOutputStep", + "value": { + "type": "model_output", + "content": [ + { + "type": "text", + "text": "The capital of France is Paris." + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "OAuth2Config": { + "description": "Configuration for OAuth2 credentials with automatic token refresh.", + "type": "object", + "properties": { + "client_id": { + "description": "Required. OAuth2 client ID.", + "type": "string" + }, + "client_secret": { + "description": "Required. Input only. OAuth2 client secret. Write-only; never returned in responses.", + "type": "string", + "writeOnly": true + }, + "refresh_token": { + "description": "Required. Input only. OAuth2 refresh token. Write-only; never returned in responses.", + "type": "string", + "writeOnly": true + }, + "token_url": { + "description": "Required. OAuth2 token endpoint URL for refreshing access tokens.", + "type": "string" + }, + "id": { + "type": "string" + }, + "type": { + "const": "oauth2" + }, + "scopes": { + "description": "Optional. List of OAuth2 scopes.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "client_id", + "client_secret", + "id", + "refresh_token", + "token_url", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "OAuth2UpdateConfig": { + "description": "Configuration for updating OAuth2 credentials.", + "type": "object", + "properties": { + "type": { + "const": "oauth2" + }, + "client_id": { + "description": "Optional. OAuth2 client ID.", + "type": "string" + }, + "client_secret": { + "description": "Optional. Input only. OAuth2 client secret. Write-only; never returned in responses.", + "type": "string", + "writeOnly": true + }, + "refresh_token": { + "description": "Optional. Input only. OAuth2 refresh token. Write-only; never returned in responses.", + "type": "string", + "writeOnly": true + }, + "token_url": { + "description": "Optional. OAuth2 token endpoint URL for refreshing access tokens.", + "type": "string" + }, + "scopes": { + "description": "Optional. List of OAuth2 scopes.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "PingWebhookRequest": { + "description": "Request message for WebhookService.PingWebhook.", + "type": "object", + "properties": { + "id": { + "description": "Required. The ID of the webhook to ping.\nFormat: `{webhook_id}`", + "type": "string" + } + }, + "required": [ + "id" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "PingWebhookResponse": { + "description": "Response message for WebhookService.PingWebhook.", + "type": "object", + "x-speakeasy-model-namespace": "interactions" + }, + "Pitch": { + "type": "string", + "enum": [ + "low", + "medium", + "high" + ], + "x-google-enum-descriptions": [ + "Lower pitch voice.", + "Medium pitch voice.", + "Higher pitch voice." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "PlaceCitation": { + "description": "A place citation annotation.", + "type": "object", + "properties": { + "type": { + "const": "place_citation" + }, + "place_id": { + "description": "The ID of the place, in `places/{place_id}` format.", + "type": "string" + }, + "name": { + "description": "Title of the place.", + "type": "string" + }, + "url": { + "description": "URI reference of the place.", + "type": "string" + }, + "review_snippets": { + "description": "Snippets of reviews that are used to generate answers about the\nfeatures of a given place in Google Maps.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ReviewSnippet" + } + }, + "start_index": { + "description": "Start of segment of the response that is attributed to this source.\n\nIndex indicates the start of the segment, measured in bytes.", + "type": "integer", + "format": "int32" + }, + "end_index": { + "description": "End of the attributed segment, exclusive.", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Places": { + "type": "object", + "properties": { + "place_id": { + "description": "The ID of the place, in `places/{place_id}` format.", + "type": "string" + }, + "name": { + "description": "Title of the place.", + "type": "string" + }, + "url": { + "description": "URI reference of the place.", + "type": "string" + }, + "review_snippets": { + "description": "Snippets of reviews that are used to generate answers about the\nfeatures of a given place in Google Maps.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ReviewSnippet" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "ProcessingCallDelta": { + "description": "Streaming delta for a server-initiated media processing step.", + "type": "object", + "properties": { + "type": { + "const": "processing_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ProcessingCallStep": { + "description": "A server-initiated processing step for media analysis (e.g. video\nunderstanding).", + "type": "object", + "properties": { + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "processing_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "id", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ProcessingResultDelta": { + "description": "Streaming delta for the result of a server-initiated media processing step.", + "type": "object", + "properties": { + "type": { + "const": "processing_result" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ProcessingResultStep": { + "description": "The result of a server-initiated media processing step.", + "type": "object", + "properties": { + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "processing_result" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "call_id", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "PromptedVoice": { + "description": "Parameters for prompted voice generation.\nRequired in `CreateVoice` when `type` is `\"prompted\"`. Returned in\n`CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.", + "type": "object", + "properties": { + "input": { + "description": "Required. The natural-language prompt describing the desired voice, e.g.\n\"A deep, booming male voice of a massive evil ogre in his middle years.\"", + "type": "string" + }, + "base_voice": { + "description": "Optional. The name or ID of an existing base voice to edit or remix.\nUse the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for\npreviously created voices (e.g., `voice_abc123`). This can be any\nprompted or replicated voice that the user has access to.\nWhen present, `input` describes relative alterations to make to the base\nvoice.", + "type": "string" + } + }, + "required": [ + "input" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ReplicatedVoice": { + "description": "Input only. Parameters for replicated voice generation.\nRequired on input when `type` is `\"replicated\"`. Not returned in\nresponses.", + "type": "object", + "properties": { + "source_audio": { + "description": "Required. The reference audio sample of the speaker's voice to replicate.\nMust be an unmodified recording of an adult human voice.", + "$ref": "#/components/schemas/AudioData" + }, + "consent_audio": { + "description": "Required. Audio recording of the same speaker reading the required\nconsent phrase, confirming authorization to replicate the voice.", + "$ref": "#/components/schemas/AudioData" + } + }, + "required": [ + "consent_audio", + "source_audio" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ResponseFormat": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/AudioResponseFormat" + }, + { + "$ref": "#/components/schemas/ImageResponseFormat" + }, + { + "$ref": "#/components/schemas/TextResponseFormat" + }, + { + "$ref": "#/components/schemas/VideoResponseFormat" + }, + { + "type": "object", + "additionalProperties": true + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ResponseModality": { + "type": "string", + "enum": [ + "text", + "image", + "audio", + "video", + "document" + ], + "x-google-enum-descriptions": [ + "Indicates the model should return text.", + "Indicates the model should return images.", + "Indicates the model should return audio.", + "Indicates the model should return video.", + "Indicates the model should return documents." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ReviewSnippet": { + "description": "Encapsulates a snippet of a user review that answers a question about\nthe features of a specific place in Google Maps.", + "type": "object", + "properties": { + "title": { + "description": "Title of the review.", + "type": "string" + }, + "url": { + "description": "A link that corresponds to the user review on Google Maps.", + "type": "string" + }, + "review_id": { + "description": "The ID of the review snippet.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "RotateSigningSecretRequest": { + "description": "Request message for WebhookService.RotateSigningSecret.", + "type": "object", + "properties": { + "id": { + "description": "Required. The ID of the webhook for which to generate a signing secret.\nFormat: `{webhook_id}`", + "type": "string" + }, + "revocation_behavior": { + "description": "Optional. The revocation behavior for previous signing secrets.", + "type": "string", + "enum": [ + "revoke_previous_secrets_after_h24", + "revoke_previous_secrets_immediately" + ], + "x-google-enum-descriptions": [ + "Generate a new signing secret and revoke all previous secrets after 24\nhours. Default and safest option for migrations.", + "Revoke all previous secrets immediately. Use with caution as this can\ninterrupt ongoing notifications." + ] + } + }, + "required": [ + "id" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "RotateSigningSecretResponse": { + "description": "Response message for WebhookService.RotateSigningSecret.", + "type": "object", + "properties": { + "secret": { + "description": "Output only. The newly generated signing secret.", + "type": "string", + "readOnly": true + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "RunTriggerRequest": { + "description": "Request message for TriggerService.RunTrigger.", + "type": "object", + "properties": { + "id": { + "description": "Required. The ID of the trigger to run immediately.", + "type": "string" + } + }, + "required": [ + "id" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "SafetySetting": { + "description": "A safety setting that affects the safety-blocking behavior.\n\nA SafetySetting consists of a\nharm category and a\nthreshold for that\ncategory.", + "type": "object", + "properties": { + "type": { + "description": "Required. The type of harm category to be blocked.", + "$ref": "#/components/schemas/HarmCategory" + }, + "threshold": { + "description": "Required. The threshold for blocking content. If the harm probability\nexceeds this threshold, the content will be blocked.", + "type": "string", + "enum": [ + "block_low_and_above", + "block_medium_and_above", + "block_only_high", + "off" + ], + "x-google-enum-descriptions": [ + "Block content with a low harm probability or higher.", + "Block content with a medium harm probability or higher.", + "Block content with a high harm probability.", + "Turn off the safety filter entirely." + ] + }, + "method": { + "description": "Optional. The method for blocking content. If not specified, the default\nbehavior is to use the probability score.", + "type": "string", + "enum": [ + "severity", + "probability" + ], + "x-google-enum-descriptions": [ + "The harm block method uses both probability and severity scores.", + "The harm block method uses the probability score." + ] + } + }, + "required": [ + "threshold", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ServiceTier": { + "type": "string", + "enum": [ + "flex", + "standard", + "priority" + ], + "x-google-enum-descriptions": [ + "Flex service tier.", + "Standard service tier.", + "Priority service tier." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "SigningSecret": { + "description": "Represents a signing secret used to verify webhook payloads.", + "type": "object", + "properties": { + "truncated_secret": { + "description": "Output only. The truncated version of the signing secret.", + "type": "string", + "readOnly": true + }, + "expire_time": { + "description": "Output only. The expiration date of the signing secret.", + "type": "string", + "format": "date-time", + "readOnly": true + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "SmartTranscriptionMode": { + "description": "Configuration for smart transcription mode.", + "type": "object", + "properties": { + "type": { + "const": "smart" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Source": { + "description": "A source to be mounted into the environment.", + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "gcs", + "inline", + "repository" + ], + "x-google-enum-descriptions": [ + "A Cloud Storage bucket.", + "Inline content.", + "A generic repository. The protocol prefix in the source URL\nidentifies the provider (e.g., github://, gcs://)." + ] + }, + "source": { + "description": "The source of the environment.\nFor Cloud Storage, this is the Cloud Storage path.\nFor GitHub, this is the GitHub path.", + "type": "string" + }, + "target": { + "description": "Where the source should appear in the environment.", + "type": "string" + }, + "content": { + "description": "The inline content if `type` is `INLINE`.", + "type": "string" + }, + "encoding": { + "description": "Optional encoding for inline content (e.g. `base64`).", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "SpeakerConfig": { + "description": "Configuration for multi-speaker and speech generation.", + "type": "object", + "properties": { + "speakers": { + "description": "Individual speaker configurations.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SpeechConfig" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "SpeechAnnotation": { + "description": "Speech annotation for text content.", + "type": "object", + "properties": { + "type": { + "const": "speech_metadata" + }, + "speaker": { + "description": "The speaker to associate with this turn.", + "type": "string" + }, + "style": { + "description": "Style instruction for the speech synthesis.", + "type": "string" + }, + "start_index": { + "description": "Start of segment of the response that is attributed to this source.\n\nIndex indicates the start of the segment, measured in bytes.", + "type": "integer", + "format": "int32" + }, + "end_index": { + "description": "End of the attributed segment, exclusive.", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "SpeechConfig": { + "description": "The configuration for speech interaction.", + "type": "object", + "properties": { + "voice": { + "description": "The voice of the speaker.", + "type": "string" + }, + "language": { + "description": "The language of the speech.", + "type": "string" + }, + "speaker": { + "description": "The speaker's name, it should match the speaker name given in the prompt.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "StaticMediaProcessing": { + "type": "object", + "properties": { + "type": { + "const": "static" + }, + "start_offset": { + "description": "Optional. Segment start time. Specified as a decimal number of seconds followed\nby an 's' suffix, e.g., \"10.5s\". Must be non-negative.", + "type": "string", + "format": "google-duration" + }, + "end_offset": { + "description": "Optional. Segment end time. Specified as a decimal number of seconds followed\nby an 's' suffix, e.g., \"30s\". Must be non-negative and greater than\n`start_offset` if `start_offset` is set.", + "type": "string", + "format": "google-duration" + }, + "fps": { + "description": "Optional. Video frame-rate sampling density.", + "type": "number", + "format": "double" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Step": { + "description": "A step in the interaction.", + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/CodeExecutionCallStep" + }, + { + "$ref": "#/components/schemas/CodeExecutionResultStep" + }, + { + "$ref": "#/components/schemas/FileSearchCallStep" + }, + { + "$ref": "#/components/schemas/FileSearchResultStep" + }, + { + "$ref": "#/components/schemas/FunctionCallStep" + }, + { + "$ref": "#/components/schemas/FunctionResultStep" + }, + { + "$ref": "#/components/schemas/GoogleMapsCallStep" + }, + { + "$ref": "#/components/schemas/GoogleMapsResultStep" + }, + { + "$ref": "#/components/schemas/GoogleSearchCallStep" + }, + { + "$ref": "#/components/schemas/GoogleSearchResultStep" + }, + { + "$ref": "#/components/schemas/McpServerToolCallStep" + }, + { + "$ref": "#/components/schemas/McpServerToolResultStep" + }, + { + "$ref": "#/components/schemas/ModelOutputStep" + }, + { + "$ref": "#/components/schemas/ProcessingCallStep" + }, + { + "$ref": "#/components/schemas/ProcessingResultStep" + }, + { + "$ref": "#/components/schemas/ThoughtStep" + }, + { + "$ref": "#/components/schemas/UrlContextCallStep" + }, + { + "$ref": "#/components/schemas/UrlContextResultStep" + }, + { + "$ref": "#/components/schemas/UserInputStep" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "StepDelta": { + "type": "object", + "properties": { + "index": { + "type": "integer", + "format": "int32" + }, + "delta": { + "$ref": "#/components/schemas/StepDeltaData" + }, + "event_type": { + "const": "step.delta" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + }, + "metadata": { + "$ref": "#/components/schemas/StepDeltaMetadata" + } + }, + "required": [ + "delta", + "event_type", + "index" + ], + "examples": [ + { + "step_delta": { + "summary": "Step Delta", + "value": { + "delta": { + "type": "text", + "text": "Hello" + }, + "event_type": "step.delta", + "index": 0 + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "StepDeltaData": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/ArgumentsDelta" + }, + { + "$ref": "#/components/schemas/AudioDelta" + }, + { + "$ref": "#/components/schemas/CodeExecutionCallDelta" + }, + { + "$ref": "#/components/schemas/CodeExecutionResultDelta" + }, + { + "$ref": "#/components/schemas/DocumentDelta" + }, + { + "$ref": "#/components/schemas/FileSearchCallDelta" + }, + { + "$ref": "#/components/schemas/FileSearchResultDelta" + }, + { + "$ref": "#/components/schemas/FunctionResultDelta" + }, + { + "$ref": "#/components/schemas/GoogleMapsCallDelta" + }, + { + "$ref": "#/components/schemas/GoogleMapsResultDelta" + }, + { + "$ref": "#/components/schemas/GoogleSearchCallDelta" + }, + { + "$ref": "#/components/schemas/GoogleSearchResultDelta" + }, + { + "$ref": "#/components/schemas/ImageDelta" + }, + { + "$ref": "#/components/schemas/McpServerToolCallDelta" + }, + { + "$ref": "#/components/schemas/McpServerToolResultDelta" + }, + { + "$ref": "#/components/schemas/ProcessingCallDelta" + }, + { + "$ref": "#/components/schemas/ProcessingResultDelta" + }, + { + "$ref": "#/components/schemas/TextAnnotationDelta" + }, + { + "$ref": "#/components/schemas/TextDelta" + }, + { + "$ref": "#/components/schemas/ThoughtSignatureDelta" + }, + { + "$ref": "#/components/schemas/ThoughtSummaryDelta" + }, + { + "$ref": "#/components/schemas/UrlContextCallDelta" + }, + { + "$ref": "#/components/schemas/UrlContextResultDelta" + }, + { + "$ref": "#/components/schemas/VideoDelta" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "StepDeltaMetadata": { + "description": "Optional metadata accompanying ANY streamed event.", + "type": "object", + "properties": { + "total_usage": { + "description": "Statistics on the interaction request's token usage.", + "$ref": "#/components/schemas/Usage" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "StepStart": { + "type": "object", + "properties": { + "index": { + "type": "integer", + "format": "int32" + }, + "step": { + "$ref": "#/components/schemas/Step" + }, + "event_type": { + "const": "step.start" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + } + }, + "required": [ + "event_type", + "index", + "step" + ], + "examples": [ + { + "step_start": { + "summary": "Step Start", + "value": { + "event_type": "step.start", + "index": 0, + "step": { + "type": "model_output" + } + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "StepStop": { + "type": "object", + "properties": { + "index": { + "type": "integer", + "format": "int32" + }, + "event_type": { + "const": "step.stop" + }, + "usage": { + "description": "Cumulative model usage stats from the start of the session.", + "$ref": "#/components/schemas/Usage" + }, + "step_usage": { + "description": "Model usage stats for this specific step.", + "$ref": "#/components/schemas/Usage" + }, + "event_id": { + "description": "The event_id token to be used to resume the interaction stream, from\nthis event.", + "type": "string" + } + }, + "required": [ + "event_type", + "index" + ], + "examples": [ + { + "step_stop": { + "summary": "Step Stop", + "value": { + "event_type": "step.stop", + "index": 0 + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "TextAnnotationDelta": { + "type": "object", + "properties": { + "type": { + "const": "text_annotation_delta" + }, + "annotations": { + "description": "Citation information for model-generated content.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Annotation" + } + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "TextContent": { + "description": "A text content block.", + "type": "object", + "properties": { + "text": { + "description": "Required. The text content.", + "type": "string" + }, + "type": { + "const": "text" + }, + "annotations": { + "description": "Citation information for model-generated content.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Annotation" + } + } + }, + "required": [ + "text", + "type" + ], + "examples": [ + { + "text": { + "summary": "Text", + "value": { + "type": "text", + "text": "Hello, how are you?" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "TextDelta": { + "type": "object", + "properties": { + "text": { + "type": "string" + }, + "type": { + "const": "text" + } + }, + "required": [ + "text", + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "TextResponseFormat": { + "description": "Configuration for text output format.", + "type": "object", + "properties": { + "type": { + "const": "text" + }, + "mime_type": { + "description": "The MIME type of the text output.", + "type": "string", + "enum": [ + "application/json", + "text/plain" + ], + "x-google-enum-descriptions": [ + "JSON output format.", + "Plain text output format." + ] + }, + "schema": { + "description": "The JSON schema that the output should conform to. Only applicable when\nmime_type is application/json.\n\nSupports a subset of JSON Schema. `minLength`, `maxLength`,\n`minProperties`, `maxProperties`, `uniqueItems`, `contains`,\n`minContains`, and `maxContains` are ignored and not enforced; validate\nthese in your application. `minItems` and `maxItems` are enforced. Schemas\nthat are too complex to enforce (for example, large `maxItems` on nested\narrays) return a 400 INVALID_ARGUMENT error.", + "type": "object", + "additionalProperties": { + "description": "Properties of the object." + } + } + }, + "required": [ + "type" + ], + "examples": [ + { + "text_response_format": { + "summary": "Text Output (JSON Schema)", + "value": { + "type": "text", + "mime_type": "application/json", + "schema": { + "type": "object", + "properties": { + "ingredients": { + "type": "array", + "items": { + "type": "string" + } + }, + "recipe_name": { + "type": "string" + } + }, + "required": [ + "ingredients", + "recipe_name" + ] + } + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ThinkingLevel": { + "type": "string", + "enum": [ + "minimal", + "low", + "medium", + "high" + ], + "x-google-enum-descriptions": [ + "Little to no thinking.", + "Low thinking level.", + "Medium thinking level.", + "High thinking level." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ThinkingSummaries": { + "type": "string", + "enum": [ + "auto", + "none" + ], + "x-google-enum-descriptions": [ + "Auto thinking summaries.", + "No thinking summaries." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ThoughtSignatureDelta": { + "type": "object", + "properties": { + "type": { + "const": "thought_signature" + }, + "signature": { + "description": "Signature to match the backend source to be part of the generation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ThoughtStep": { + "description": "A thought step.", + "type": "object", + "properties": { + "type": { + "const": "thought" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "summary": { + "description": "A summary of the thought.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Content" + } + } + }, + "required": [ + "type" + ], + "examples": [ + { + "thought": { + "summary": "ThoughtStep", + "value": { + "type": "thought", + "signature": "thought_sig_abcd1234", + "summary": [ + { + "type": "text", + "text": "The model is searching Google for the capital of France." + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ThoughtSummaryContent": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/ImageContent" + }, + { + "$ref": "#/components/schemas/TextContent" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ThoughtSummaryDelta": { + "type": "object", + "properties": { + "type": { + "const": "thought_summary" + }, + "content": { + "description": "A new summary item to be added to the thought.", + "$ref": "#/components/schemas/Content" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Tool": { + "description": "A tool that can be used by the model.", + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/CodeExecution" + }, + { + "$ref": "#/components/schemas/ComputerUse" + }, + { + "$ref": "#/components/schemas/FileSearch" + }, + { + "$ref": "#/components/schemas/Function" + }, + { + "$ref": "#/components/schemas/GoogleMaps" + }, + { + "$ref": "#/components/schemas/GoogleSearch" + }, + { + "$ref": "#/components/schemas/McpServer" + }, + { + "$ref": "#/components/schemas/UrlContext" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "ToolChoiceConfig": { + "description": "The tool choice configuration containing allowed tools.", + "type": "object", + "properties": { + "allowed_tools": { + "description": "The allowed tools.", + "$ref": "#/components/schemas/AllowedTools" + } + }, + "example": { + "allowed_tools": { + "mode": "any", + "tools": [ + "my_tool" + ] + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "TranscriptionConfig": { + "description": "Configuration for speech recognition (transcription).", + "type": "object", + "properties": { + "mode": { + "description": "Discriminated transcription mode options or enum.", + "oneOf": [ + { + "$ref": "#/components/schemas/TranscriptionMode" + }, + { + "type": "string", + "enum": [ + "verbatim", + "smart" + ], + "x-google-enum-descriptions": [ + "Verbatim transcription mode.", + "Smart transcription mode." + ] + } + ] + }, + "language_codes": { + "description": "Optional. BCP-47 language codes providing hints about the languages present in the\naudio. If omitted or empty, defaults to automatic language detection.", + "type": "array", + "items": { + "type": "string" + } + }, + "custom_vocabulary": { + "description": "Optional. A list of custom vocabulary phrases to bias the speech recognition model\ntoward recognizing specific terms.", + "type": "array", + "items": { + "type": "string" + } + }, + "timestamp_granularities": { + "description": "Optional. The granularity of timestamps to include in the transcription output.\nSupported values: \"word\". If empty, no timestamps are generated.", + "type": "array", + "deprecated": true, + "items": { + "type": "string" + } + }, + "diarization_mode": { + "description": "Optional. Configures speaker diarization. Supported values: \"speaker\".", + "type": "string", + "deprecated": true + }, + "adaptation_phrases": { + "description": "Optional. A list of phrases to bias the ASR model towards.", + "type": "array", + "deprecated": true, + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "TranscriptionMode": { + "description": "Configuration for transcription mode.", + "oneOf": [ + { + "$ref": "#/components/schemas/SmartTranscriptionMode" + }, + { + "$ref": "#/components/schemas/VerbatimTranscriptionMode" + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Trigger": { + "description": "A trigger configuration that is scheduled to run an agent.", + "type": "object", + "properties": { + "schedule": { + "description": "Required. The cron schedule on which the trigger should run.\nStandard cron format.", + "type": "string" + }, + "time_zone": { + "description": "Required. Time zone in which the schedule should be interpreted.", + "type": "string" + }, + "interaction": { + "description": "Required. The interaction request template to be executed.", + "$ref": "#/components/schemas/CreateAgentInteractionParams" + }, + "id": { + "description": "Required. Output only. Identifier. The ID of the trigger.", + "type": "string", + "readOnly": true, + "x-google-identifier": true + }, + "display_name": { + "description": "Optional. The display name of the trigger.", + "type": "string" + }, + "environment_id": { + "description": "Optional. The environment ID for the trigger execution.", + "type": "string" + }, + "max_consecutive_failures": { + "description": "Optional. The maximum number of consecutive failures allowed before\nthe trigger is automatically paused (status becomes ERROR).", + "type": "integer", + "format": "int32" + }, + "execution_timeout_seconds": { + "description": "Optional. The execution timeout for the triggered interaction.", + "type": "integer", + "format": "int32" + }, + "consecutive_failure_count": { + "description": "Output only. The number of consecutive failures that have occurred\nsince the last successful execution.", + "type": "integer", + "format": "int32", + "readOnly": true + }, + "create_time": { + "description": "Output only. The time when the trigger was created.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "update_time": { + "description": "Output only. The time when the trigger was last updated.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "last_run_time": { + "description": "Output only. The time when the trigger was last run.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "next_run_time": { + "description": "Output only. The time when the trigger is scheduled to run next.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "last_pause_time": { + "description": "Output only. The time when the trigger was last paused.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "last_resume_time": { + "description": "Output only. The time when the trigger was last resumed.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "previous_interaction_id": { + "description": "Output only. The ID of the last interaction created by this trigger.", + "type": "string", + "readOnly": true + }, + "status": { + "description": "Output only. The current status of the trigger.", + "type": "string", + "enum": [ + "active", + "paused", + "error" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "The trigger is active and will fire on schedule.", + "The trigger is paused and will not fire.", + "The trigger has entered an error state due to consecutive failures." + ] + } + }, + "required": [ + "id", + "interaction", + "schedule", + "time_zone" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "TriggerExecution": { + "description": "An execution instance of a trigger.", + "type": "object", + "properties": { + "id": { + "description": "Required. Output only. Identifier. The ID of the trigger execution.", + "type": "string", + "readOnly": true, + "x-google-identifier": true + }, + "trigger_id": { + "description": "Required. Output only. Identifier. The ID of the trigger that created this execution.", + "type": "string", + "readOnly": true, + "x-google-identifier": true + }, + "scheduled_time": { + "description": "Output only. The time when the execution was scheduled to run.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "start_time": { + "description": "Output only. The time when the execution started.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "end_time": { + "description": "Output only. The time when the execution finished.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "status": { + "description": "Output only. The status of the execution.", + "type": "string", + "enum": [ + "in_progress", + "completed", + "failed", + "skipped", + "timed_out" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "The execution is currently in progress.", + "The execution completed successfully.", + "The execution failed.", + "The execution was skipped (e.g., previous execution still running).", + "The execution timed out." + ] + }, + "interaction_id": { + "description": "Output only. The ID of the interaction created by this execution, if any.", + "type": "string", + "readOnly": true + }, + "environment_id": { + "description": "Output only. The environment ID used for the execution.", + "type": "string", + "readOnly": true + }, + "error": { + "description": "Output only. The error message if the execution failed.", + "type": "string", + "readOnly": true + } + }, + "required": [ + "id", + "trigger_id" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "TriggerUpdate": { + "description": "Represents the fields of a Trigger that can be updated.", + "type": "object", + "properties": { + "status": { + "description": "Optional. The status of the trigger.", + "type": "string", + "enum": [ + "active", + "paused", + "error" + ], + "x-google-enum-descriptions": [ + "The trigger is active and will fire on schedule.", + "The trigger is paused and will not fire.", + "The trigger has entered an error state due to consecutive failures." + ] + }, + "display_name": { + "description": "Optional. The display name of the trigger.", + "type": "string" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "UpdateTriggerRequest": { + "description": "Request message for TriggerService.UpdateTrigger.", + "type": "object", + "properties": { + "trigger": { + "description": "Required. The trigger to update.", + "$ref": "#/components/schemas/TriggerUpdate" + }, + "id": { + "description": "Required. The ID of the trigger to update.", + "type": "string" + }, + "update_mask": { + "description": "Optional. The update mask applies to the resource.", + "type": "string", + "format": "google-fieldmask", + "pattern": "^(\\s*[^,\\s.]+(\\s*[,.]\\s*[^,\\s.]+)*)?$" + } + }, + "required": [ + "id", + "trigger" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "UpdateWebhookRequest": { + "description": "Request message for WebhookService.UpdateWebhook.", + "type": "object", + "properties": { + "webhook": { + "description": "Required. The webhook to update.", + "$ref": "#/components/schemas/WebhookUpdate" + }, + "id": { + "description": "Required. The ID of the webhook to update.", + "type": "string" + }, + "update_mask": { + "description": "Optional. The list of fields to update.", + "type": "string", + "format": "google-fieldmask", + "pattern": "^(\\s*[^,\\s.]+(\\s*[,.]\\s*[^,\\s.]+)*)?$" + } + }, + "required": [ + "id", + "webhook" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "UploadEnvironmentFileRequest": { + "description": "Request for `UploadEnvironmentFile`.", + "type": "object", + "properties": { + "overwrite": { + "description": "Optional. Whether to overwrite the destination file if it already exists.", + "type": "boolean" + }, + "extract": { + "description": "Optional. If true, treats the uploaded file as a tar/tar.gz archive and\nunpacks it into `path`.", + "type": "boolean" + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "UploadEnvironmentFileResponse": { + "description": "Response for `UploadEnvironmentFile`.", + "type": "object", + "properties": { + "files": { + "description": "List of files created or extracted in the environment.", + "type": "array", + "items": { + "$ref": "#/components/schemas/EnvironmentFile" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "UrlCitation": { + "description": "A URL citation annotation.", + "type": "object", + "properties": { + "type": { + "const": "url_citation" + }, + "url": { + "description": "The URL.", + "type": "string" + }, + "title": { + "description": "The title of the URL.", + "type": "string" + }, + "start_index": { + "description": "Start of segment of the response that is attributed to this source.\n\nIndex indicates the start of the segment, measured in bytes.", + "type": "integer", + "format": "int32" + }, + "end_index": { + "description": "End of the attributed segment, exclusive.", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLCitation" + }, + "UrlContext": { + "description": "A tool that can be used by the model to fetch URL context.", + "type": "object", + "properties": { + "type": { + "const": "url_context" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContext", + "x-codeSamples": [ + { + "label": "url_context", + "lang": "sh", + "source": "curl -X POST https://generativelanguage.googleapis.com/v1beta/interactions \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gemini-flash-latest\",\n \"tools\": [{\n \"type\": \"url_context\"\n }],\n \"input\": \"Summarize https://www.example.com\"\n }'\n" + }, + { + "label": "url_context", + "lang": "python", + "source": "from google import genai\n\nclient = genai.Client()\nresponse = client.interactions.create(\n model=\"gemini-flash-latest\",\n tools=[{\"type\": \"url_context\"}],\n input=\"Summarize https://www.example.com\",\n)\nprint(response.output_text)\n" + }, + { + "label": "url_context", + "lang": "javascript", + "source": "import {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({});\nconst interaction = await ai.interactions.create({\n model: 'gemini-flash-latest',\n tools: [{type: 'url_context'}],\n input: 'Summarize https://www.example.com',\n});\nconsole.log(interaction.output_text);\n" + }, + { + "label": "url_context", + "lang": "java", + "source": "import com.google.genai.Client;\nimport com.google.genai.gaos.models.operations.CreateInteractionRequestBody;\nimport com.google.genai.gaos.models.operations.CreateInteractionResponse;\nimport com.google.genai.gaos.models.interactions.CreateModelInteraction;\nimport com.google.genai.gaos.models.interactions.Interaction;\nimport com.google.genai.gaos.models.interactions.InteractionsInput;\nimport com.google.genai.gaos.models.interactions.URLContext;\n\nClient client = new Client();\nCreateModelInteraction params =\n CreateModelInteraction.builder()\n .model(\"gemini-flash-latest\")\n .tools(List.of(new URLContext()))\n .input(InteractionsInput.of(\"Summarize https://www.example.com\"))\n .build();\nCreateInteractionResponse response =\n client.interactions.create(CreateInteractionRequestBody.of(params));\nInteraction interaction =\n response.interaction().orElseThrow(() -> new RuntimeException(\"No interaction returned\"));\nSystem.out.println(interaction.outputText().orElse(\"\"));\n" + }, + { + "label": "url_context", + "lang": "go", + "source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"google.golang.org/genai\"\n gaos_interactions \"google.golang.org/genai/interactions/models/interactions\"\n \"google.golang.org/genai/interactions/models/operations\"\n)\n\nfunc main() {\n ctx := context.Background()\n client, err := genai.NewClient(ctx, nil)\n if err != nil {\n log.Fatal(err)\n }\n\n tool := gaos_interactions.NewTool(gaos_interactions.URLContext{})\n\n body := operations.NewCreateInteractionRequestBody(gaos_interactions.CreateModelInteraction{\n Model: gaos_interactions.Model(\"gemini-flash-latest\"),\n Input: genai.Ptr(gaos_interactions.NewInteractionsInput(\"Summarize https://www.example.com\")),\n Tools: []gaos_interactions.Tool{tool},\n })\n\n req := operations.CreateInteractionRequest{\n Body: body,\n }\n\n res, err := client.Interactions.Create(ctx, req)\n if err != nil {\n log.Fatal(err)\n }\n\n if res.Interaction != nil && res.Interaction.OutputText != nil {\n fmt.Println(*res.Interaction.OutputText)\n }\n}\n" + } + ] + }, + "UrlContextCallArguments": { + "description": "The arguments to pass to the URL context.", + "type": "object", + "properties": { + "urls": { + "description": "The URLs to fetch.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContextCallArguments" + }, + "UrlContextCallDelta": { + "type": "object", + "properties": { + "arguments": { + "$ref": "#/components/schemas/UrlContextCallArguments" + }, + "type": { + "const": "url_context_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "arguments", + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContextCallDelta" + }, + "UrlContextCallStep": { + "description": "URL context call step.", + "type": "object", + "properties": { + "arguments": { + "description": "Required. The arguments to pass to the URL context.", + "$ref": "#/components/schemas/UrlContextCallArguments" + }, + "id": { + "description": "Required. A unique ID for this specific tool call.", + "type": "string" + }, + "type": { + "const": "url_context_call" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "arguments", + "id", + "type" + ], + "examples": [ + { + "url_context_call": { + "summary": "UrlContextCallStep", + "value": { + "type": "url_context_call", + "arguments": { + "urls": [ + "https://www.example.com" + ] + }, + "id": "url_call_10219" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContextCallStep" + }, + "UrlContextResult": { + "description": "The result of the URL context.", + "type": "object", + "properties": { + "url": { + "description": "The URL that was fetched.", + "type": "string" + }, + "status": { + "description": "The status of the URL retrieval.", + "type": "string", + "enum": [ + "success", + "error", + "paywall", + "unsafe" + ], + "x-google-enum-descriptions": [ + "Url retrieval is successful.", + "Url retrieval is failed due to error.", + "Url retrieval is failed because the content is behind paywall.", + "Url retrieval is failed because the content is unsafe." + ] + } + }, + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContextResult" + }, + "UrlContextResultDelta": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UrlContextResult" + } + }, + "type": { + "const": "url_context_result" + }, + "is_error": { + "type": "boolean" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "result", + "type" + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContextResultDelta" + }, + "UrlContextResultStep": { + "description": "URL context result step.", + "type": "object", + "properties": { + "result": { + "description": "Required. The results of the URL context.", + "type": "array", + "items": { + "$ref": "#/components/schemas/UrlContextResult" + } + }, + "call_id": { + "description": "Required. ID to match the ID from the function call block.", + "type": "string" + }, + "type": { + "const": "url_context_result" + }, + "is_error": { + "description": "Whether the URL context resulted in an error.", + "type": "boolean" + }, + "signature": { + "description": "A signature hash for backend validation.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + } + }, + "required": [ + "call_id", + "result", + "type" + ], + "examples": [ + { + "url_context_result": { + "summary": "UrlContextResultStep", + "value": { + "type": "url_context_result", + "call_id": "url_call_10219", + "result": [ + { + "title": "Example Domain", + "url": "https://www.example.com", + "snippet": "This domain is for use in illustrative examples in documents." + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions", + "x-speakeasy-name-override": "URLContextResultStep" + }, + "Usage": { + "description": "Statistics on the interaction request's token usage.", + "type": "object", + "properties": { + "total_input_tokens": { + "description": "Number of tokens in the prompt (context).", + "type": "integer", + "format": "int32" + }, + "input_tokens_by_modality": { + "description": "A breakdown of input token usage by modality.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ModalityTokens" + } + }, + "total_cached_tokens": { + "description": "Number of tokens in the cached part of the prompt (the cached content).", + "type": "integer", + "format": "int32" + }, + "cached_tokens_by_modality": { + "description": "A breakdown of cached token usage by modality.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ModalityTokens" + } + }, + "total_output_tokens": { + "description": "Total number of tokens across all the generated responses.", + "type": "integer", + "format": "int32" + }, + "output_tokens_by_modality": { + "description": "A breakdown of output token usage by modality.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ModalityTokens" + } + }, + "total_tool_use_tokens": { + "description": "Number of tokens present in tool-use prompt(s).", + "type": "integer", + "format": "int32" + }, + "tool_use_tokens_by_modality": { + "description": "A breakdown of tool-use token usage by modality.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ModalityTokens" + } + }, + "total_thought_tokens": { + "description": "Number of tokens of thoughts for thinking models.", + "type": "integer", + "format": "int32" + }, + "total_tokens": { + "description": "Total token count for the interaction request (prompt + responses + other\ninternal tokens).", + "type": "integer", + "format": "int32" + }, + "grounding_tool_count": { + "description": "Grounding tool count.", + "type": "array", + "items": { + "$ref": "#/components/schemas/GroundingToolCount" + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "UserInputStep": { + "description": "Input provided by the user.", + "type": "object", + "properties": { + "type": { + "const": "user_input" + }, + "content": { + "title": "ContentList", + "type": "array", + "items": { + "$ref": "#/components/schemas/Content" + } + } + }, + "required": [ + "type" + ], + "examples": [ + { + "user_input": { + "summary": "UserInputStep", + "value": { + "type": "user_input", + "content": [ + { + "type": "text", + "text": "What is the capital of France?" + } + ] + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "VerbatimTranscriptionMode": { + "description": "Configuration for verbatim transcription mode.", + "type": "object", + "properties": { + "type": { + "const": "verbatim" + }, + "timestamp_granularities": { + "description": "Optional. The granularity of timestamps to include in the transcription output.\nSupported values: \"word\". If empty, no timestamps are generated.", + "type": "array", + "items": { + "type": "string" + } + }, + "diarization_mode": { + "description": "Optional. Configures speaker diarization. Supported values: \"speaker\".", + "type": "string" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "VideoConfig": { + "description": "Configuration options for video generation.", + "type": "object", + "properties": { + "task": { + "description": "Optional task mode for video generation. If not specified, the model\nautomatically determines the appropriate mode based on the provided text\nprompt and input media.", + "type": "string", + "enum": [ + "text_to_video", + "image_to_video", + "reference_to_video", + "edit", + "extend" + ], + "x-google-enum-descriptions": [ + "Generates video solely from a text prompt.", + "Generates video from one or two source images. The first image defines\nthe starting frame, and the optional second image defines the ending\nframe.", + "Generates video using reference media (such as images, audio, or video).", + "Modifies an existing input video.", + "Extends an existing input video." + ] + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "VideoContent": { + "description": "A video content block.", + "type": "object", + "properties": { + "type": { + "const": "video" + }, + "data": { + "description": "The video content.", + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "description": "The URI of the video.", + "type": "string" + }, + "processing": { + "description": "How the model processes this video for understanding.", + "oneOf": [ + { + "$ref": "#/components/schemas/MediaProcessing" + }, + { + "type": "string", + "enum": [ + "static", + "agentic" + ], + "x-google-enum-descriptions": [ + "Fixed-rate frame extraction. All frames placed in context.", + "Model-driven dynamic navigation." + ] + } + ] + }, + "resolution": { + "description": "The resolution of the media.", + "$ref": "#/components/schemas/MediaResolution" + }, + "name": { + "description": "A user-defined name for this content block. Can be referenced by the model\nin the final response.", + "type": "string" + }, + "mime_type": { + "description": "The mime type of the video.", + "type": "string", + "enum": [ + "video/mp4", + "video/mpeg", + "video/mpg", + "video/mov", + "video/avi", + "video/x-flv", + "video/webm", + "video/wmv", + "video/3gpp" + ], + "x-google-enum-descriptions": [ + "MP4 video format", + "MPEG video format", + "MPG video format", + "MOV video format", + "AVI video format", + "FLV video format", + "WebM video format", + "WMV video format", + "3GPP video format" + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "video": { + "summary": "Video", + "value": { + "type": "video", + "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "VideoDelta": { + "type": "object", + "properties": { + "type": { + "const": "video" + }, + "data": { + "type": "string", + "format": "byte", + "x-speakeasy-base64-input-mode": "file" + }, + "uri": { + "type": "string" + }, + "mime_type": { + "type": "string", + "enum": [ + "video/mp4", + "video/mpeg", + "video/mpg", + "video/mov", + "video/avi", + "video/x-flv", + "video/webm", + "video/wmv", + "video/3gpp", + "video/jpeg2000" + ], + "x-google-enum-descriptions": [ + "MP4 video format", + "MPEG video format", + "MPG video format", + "MOV video format", + "AVI video format", + "FLV video format", + "WebM video format", + "WMV video format", + "3GPP video format", + "JPEG 2000 video format" + ] + }, + "resolution": { + "description": "The resolution of the media.", + "$ref": "#/components/schemas/MediaResolution" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "VideoResponseFormat": { + "description": "Configuration for video output format.", + "type": "object", + "properties": { + "type": { + "const": "video" + }, + "delivery": { + "description": "The delivery mode for the video output.", + "type": "string", + "enum": [ + "inline", + "uri" + ], + "x-google-enum-descriptions": [ + "Video data is returned inline in the response.", + "Video data is returned as a URI." + ] + }, + "aspect_ratio": { + "description": "The aspect ratio for the video output.", + "type": "string", + "enum": [ + "16:9", + "9:16" + ], + "x-google-enum-descriptions": [ + "16:9 aspect ratio.", + "9:16 aspect ratio." + ] + }, + "duration": { + "description": "The duration for the video output.", + "type": "string", + "format": "google-duration" + }, + "resolution": { + "description": "The video output resolution. Defaults to 720p.", + "type": "string", + "enum": [ + "360p", + "720p", + "1080p", + "4k" + ], + "x-google-enum-descriptions": [ + "360p resolution.", + "720p resolution.", + "1080p resolution.", + "4K resolution." + ] + } + }, + "required": [ + "type" + ], + "examples": [ + { + "video_response_format": { + "summary": "Video Output", + "value": { + "type": "video", + "aspect_ratio": "16:9", + "delivery": "inline" + } + } + } + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Voice": { + "description": "A voice resource representing either a custom voice (created via\n`CreateVoice`) or a prebuilt system voice (returned by `ListVoices`).", + "type": "object", + "properties": { + "type": { + "description": "Required. The type of the voice. In `CreateVoice`, must be `\"replicated\"`\nor `\"prompted\"`. In `ListVoices` responses, may also be `\"prebuilt\"`.", + "$ref": "#/components/schemas/VoiceType" + }, + "id": { + "description": "Output only. The unique identifier of the voice.\n\n* For Google-managed custom voices (`store = true`), this is a generated ID\n with prefix `voice_` (for example, `voice_abc123def456`). Pass\n `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass\n `{id}` directly to `SpeechConfig.voice_config.voice` (or\n `SpeechConfig.voice`) during speech synthesis.\n* For prebuilt catalog voices (`\"prebuilt\"` returned by `ListVoices`), this\n is the speaker name (for example, `Puck` or `Charon`).\n* Unset when `CreateVoice` is called with `store = false`.", + "type": "string", + "readOnly": true + }, + "model": { + "description": "Optional. The model used to design or replicate the voice.\nIf omitted in `CreateVoice`, defaults to the latest supported voice design\nmodel. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses\nfor custom voices (`\"prompted\"` and `\"replicated\"`); unset for `\"prebuilt\"`\nvoices. Created voices can be synthesized across any supported TTS\nsynthesis model.", + "type": "string" + }, + "key": { + "description": "Output only. The client-managed voice replication key (with prefix\n`voicekey_`). Returned only by `CreateVoice` when `type` is `\"replicated\"`\nand `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice`\n(or `SpeechConfig.voice`) during speech synthesis.", + "type": "string", + "readOnly": true + }, + "replicated": { + "description": "Input only. Parameters for replicated voice generation.\nRequired on input when `type` is `\"replicated\"`. Not returned in\nresponses.", + "$ref": "#/components/schemas/ReplicatedVoice", + "writeOnly": true + }, + "expire_time": { + "description": "Output only. The timestamp at which a custom stored voice (`store = true`)\nor replicated voice key (`store = false`) expires. For custom stored voices\n(`store = true`), this expiration time is extended when the voice is used\nfor speech synthesis or as a `base_voice` in `CreateVoice`. Unset for\nprebuilt catalog voices (`\"prebuilt\"`), which do not expire.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "display_name": { + "description": "Optional. User-provided display name for a stored voice (`store = true`),\nor the catalog name for a prebuilt voice.", + "type": "string" + }, + "prompted": { + "description": "Parameters for prompted voice generation.\nRequired in `CreateVoice` when `type` is `\"prompted\"`. Returned in\n`CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices.", + "$ref": "#/components/schemas/PromptedVoice" + }, + "language_code": { + "description": "Optional. Primary BCP-47 language tag (e.g. \"en-US\", \"fr-FR\").", + "type": "string" + }, + "region_code": { + "description": "Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. \"US\",\n\"GB\", \"001\").", + "type": "string" + }, + "accent": { + "description": "Optional. Regional accent descriptor (e.g. \"American\", \"British\").", + "type": "string" + }, + "persona": { + "description": "Optional. Intended persona or character archetype (e.g. \"Warm, Friendly\",\n\"Narrator\").", + "type": "string" + }, + "context": { + "description": "Optional. Optimal usage context or domain (e.g. \"Conversational\",\n\"Audiobook\", \"News\").", + "type": "string" + }, + "gender": { + "description": "Optional. Perceived voice gender presentation (e.g. \"female\", \"male\",\n\"neutral\").", + "type": "string" + }, + "pitch": { + "description": "Optional. Voice pitch classification.", + "$ref": "#/components/schemas/Pitch" + }, + "description": { + "description": "Optional. Descriptive summary of vocal timbre, personality, and tone.", + "type": "string" + }, + "usage": { + "description": "Output only. Token usage statistics for the voice creation request.\nPopulated only in the response of `CreateVoice` when `type` is\n`\"prompted\"`; unset for `\"replicated\"` and in `GetVoice` and `ListVoices`\nresponses.", + "$ref": "#/components/schemas/Usage", + "readOnly": true + }, + "sample_audio": { + "description": "Output only. Sample audio (synthesizer prompt audio) generated for a\nprompted voice.\nPopulated only in `CreateVoice` and `GetVoice` responses when `type` is\n`\"prompted\"`; unset in `ListVoices` responses and for `\"replicated\"` or\n`\"prebuilt\"` voices.", + "$ref": "#/components/schemas/AudioData", + "readOnly": true + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "VoiceType": { + "type": "string", + "enum": [ + "replicated", + "prompted", + "prebuilt" + ], + "x-google-enum-descriptions": [ + "A custom voice replicated from a reference audio sample and speaker consent\nrecording.", + "A custom voice generated from a natural-language text prompt (optionally\nediting or remixing a `base_voice`).", + "A built-in system voice from Google's voice catalog (e.g., `Puck`,\n`Charon`). Returned in responses; cannot be specified as the type in\n`CreateVoice`." + ], + "x-speakeasy-model-namespace": "interactions" + }, + "Webhook": { + "description": "A Webhook resource.", + "type": "object", + "properties": { + "uri": { + "description": "Required. The URI to which webhook events will be sent.", + "type": "string" + }, + "subscribed_events": { + "description": "Required. The events that the webhook is subscribed to.\nAvailable events:\n- batch.succeeded\n- batch.expired\n- batch.failed\n- interaction.requires_action\n- interaction.completed\n- interaction.failed\n- video.generated", + "type": "array", + "items": { + "type": "string" + } + }, + "name": { + "description": "Optional. The user-provided name of the webhook.", + "type": "string" + }, + "create_time": { + "description": "Output only. The timestamp when the webhook was created.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "update_time": { + "description": "Output only. The timestamp when the webhook was last updated.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "signing_secrets": { + "description": "Output only. The signing secrets associated with this webhook.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SigningSecret" + }, + "readOnly": true + }, + "state": { + "description": "Output only. The state of the webhook.", + "type": "string", + "enum": [ + "enabled", + "disabled", + "disabled_due_to_failed_deliveries" + ], + "readOnly": true, + "x-google-enum-descriptions": [ + "The webhook is enabled.", + "The webhook is disabled by the user.", + "The webhook is disabled due to failed deliveries." + ] + }, + "new_signing_secret": { + "description": "Output only. The new signing secret for the webhook. Only populated on create.", + "type": "string", + "readOnly": true + }, + "id": { + "description": "Output only. The ID of the webhook.", + "type": "string", + "readOnly": true + } + }, + "required": [ + "subscribed_events", + "uri" + ], + "x-speakeasy-model-namespace": "interactions" + }, + "WebhookConfig": { + "description": "Message for configuring webhook events for a request.", + "type": "object", + "properties": { + "uris": { + "description": "Optional. If set, these webhook URIs will be used for webhook events instead of the\nregistered webhooks.", + "type": "array", + "items": { + "type": "string" + } + }, + "user_metadata": { + "description": "Optional. The user metadata that will be returned on each event emission to the\nwebhooks.", + "type": "object", + "additionalProperties": { + "description": "Properties of the object." + } + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "WebhookUpdate": { + "type": "object", + "properties": { + "name": { + "description": "Optional. The user-provided name of the webhook.", + "type": "string" + }, + "uri": { + "description": "Optional. The URI to which webhook events will be sent.", + "type": "string" + }, + "subscribed_events": { + "description": "Optional. The events that the webhook is subscribed to.\nAvailable events:\n- batch.succeeded\n- batch.expired\n- batch.failed\n- interaction.requires_action\n- interaction.completed\n- interaction.failed\n- video.generated", + "type": "array", + "items": { + "type": "string" + } + }, + "state": { + "description": "Optional. The state of the webhook.", + "type": "string", + "enum": [ + "enabled", + "disabled", + "disabled_due_to_failed_deliveries" + ], + "x-google-enum-descriptions": [ + "The webhook is enabled.", + "The webhook is disabled by the user.", + "The webhook is disabled due to failed deliveries." + ] + } + }, + "x-speakeasy-model-namespace": "interactions" + }, + "WordInfo": { + "description": "Word-level ASR annotation for transcription output.\nCarries the word text, optional timing, and optional speaker attribution.", + "type": "object", + "properties": { + "type": { + "const": "word_info" + }, + "text": { + "description": "The transcribed word.", + "type": "string" + }, + "start_offset": { + "description": "Start offset in time of the word relative to the start of the audio.\nPresent when timestamp_granularities contains \"word\".", + "type": "string", + "format": "google-duration" + }, + "end_offset": { + "description": "End offset in time of the word relative to the start of the audio.\nPresent when timestamp_granularities contains \"word\".", + "type": "string", + "format": "google-duration" + }, + "speaker": { + "description": "Optional. Speaker label for this word (e.g. \"spk_1\", \"spk_2\").\nPresent when diarization_mode is set in TranscriptionConfig.", + "type": "string" + }, + "start_index": { + "description": "Start of segment of the response that is attributed to this source.\n\nIndex indicates the start of the segment, measured in bytes.", + "type": "integer", + "format": "int32" + }, + "end_index": { + "description": "End of the attributed segment, exclusive.", + "type": "integer", + "format": "int32" + } + }, + "required": [ + "type" + ], + "x-speakeasy-model-namespace": "interactions" + } + }, + "securitySchemes": { + "googleGenAIAuth": { + "type": "http", + "scheme": "custom", + "x-speakeasy-custom-security-scheme": { + "schema": { + "type": "object", + "properties": { + "accessToken": { + "description": "OAuth access token sent as a bearer Authorization header.", + "type": "string" + }, + "apiKey": { + "description": "Gemini API key sent as x-goog-api-key.", + "type": "string" + }, + "defaultHeaders": { + "description": "Additional default headers to apply before request-specific headers and auth.", + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": [] + } + } + } + } + }, + "security": [ + { + "googleGenAIAuth": [] + } + ], + "x-speakeasy-globals": { + "parameters": [ + { + "$ref": "#/components/parameters/api_version" + }, + { + "$ref": "#/components/parameters/google_genai_user_project" + } + ] + }, + "x-speakeasy-retries": { + "backoff": { + "exponent": 2, + "initialInterval": 500, + "maxElapsedTime": 30000, + "maxInterval": 8000 + }, + "retryConnectionErrors": true, + "statusCodes": [ + 408, + 409, + 429, + "5XX" + ], + "strategy": "backoff" + } +} diff --git a/tests/unit/interactions/test_openapi_compliance.py b/tests/unit/interactions/test_openapi_compliance.py index 247d02298aa..b6cc92e0adc 100644 --- a/tests/unit/interactions/test_openapi_compliance.py +++ b/tests/unit/interactions/test_openapi_compliance.py @@ -1,41 +1,56 @@ """ OpenAPI compliance tests for Google Interactions API. -Validates that our SDK requests/responses match the OpenAPI spec at: -https://ai.google.dev/static/api/interactions.openapi.json +Validates that our SDK requests/responses match the OpenAPI spec snapshot in +interactions.openapi.json, taken from https://ai.google.dev/static/api/interactions.openapi.json +(litellm/types/interactions/README.md says how to refresh it). The scheduled +interactions-spec-canary workflow runs the same tests against the live spec by passing +--interactions-spec-url, so a change Google makes shows up there, not in every PR. Run with: pytest tests/unit/interactions/test_openapi_compliance.py -v """ import json -import os import re -from typing import Any, Dict +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +from typing import Any, Dict, Final, get_args from unittest.mock import MagicMock, patch import httpx import pytest from openapi_core import OpenAPI +from pydantic import BaseModel, TypeAdapter OPENAPI_SPEC_URL = "https://ai.google.dev/static/api/interactions.openapi.json" +OPENAPI_SPEC_SNAPSHOT: Final = Path(__file__).with_name("interactions.openapi.json") +SPEC_URL_OPTION: Final = TypeAdapter(str | None) -def _load_openapi_spec_dict() -> Dict[str, Any]: - """ - Load the OpenAPI spec JSON. +@dataclass(frozen=True, slots=True) +class LoadedSpec: + source: str + spec: Dict[str, Any] - In CI or offline environments, network access may not be available. - In that case, gracefully skip these tests instead of erroring. - """ - try: - response = httpx.get(OPENAPI_SPEC_URL, timeout=5.0) - response.raise_for_status() - return response.json() - except Exception as e: # pragma: no cover - defensive, env-dependent - pytest.skip( - f"Skipping Google Interactions OpenAPI compliance tests - " - f"unable to load spec from {OPENAPI_SPEC_URL}: {e}" - ) + +def _status_enum_of(model: type[BaseModel]) -> type[Enum]: + annotation: Final = model.model_fields["status"].annotation + candidates: Final = (annotation, *get_args(annotation)) + return next(candidate for candidate in candidates if isinstance(candidate, type) and issubclass(candidate, Enum)) + + +def _requested_spec_url(request: pytest.FixtureRequest) -> str | None: + return SPEC_URL_OPTION.validate_python(request.config.getoption("interactions_spec_url")) + + +def _load_openapi_spec(live_url: str | None) -> LoadedSpec: + if live_url is None: + return LoadedSpec(source=str(OPENAPI_SPEC_SNAPSHOT), spec=json.loads(OPENAPI_SPEC_SNAPSHOT.read_text())) + with httpx.Client(transport=httpx.HTTPTransport(retries=3), timeout=30.0) as client: + response: Final = client.get(live_url) + response.raise_for_status() + return LoadedSpec(source=str(response.url), spec=response.json()) def _model_create_request_schema(spec_dict: Dict[str, Any]) -> Dict[str, Any]: @@ -65,9 +80,13 @@ def _declared_type_value(variant_schema: Dict[str, Any]) -> Any: @pytest.fixture(scope="module") -def spec_dict() -> Dict[str, Any]: - """Load raw spec dict for manual validation.""" - return _load_openapi_spec_dict() +def loaded_spec(request: pytest.FixtureRequest) -> LoadedSpec: + return _load_openapi_spec(_requested_spec_url(request)) + + +@pytest.fixture(scope="module") +def spec_dict(loaded_spec: LoadedSpec) -> Dict[str, Any]: + return loaded_spec.spec @pytest.fixture(scope="module") @@ -76,6 +95,18 @@ def openapi_spec(spec_dict: Dict[str, Any]) -> OpenAPI: return OpenAPI.from_dict(spec_dict) +def test_spec_comes_from_the_requested_source(loaded_spec: LoadedSpec, request: pytest.FixtureRequest) -> None: + assert loaded_spec.source == (_requested_spec_url(request) or str(OPENAPI_SPEC_SNAPSHOT)) + + +def test_interaction_status_export_carries_the_interaction_models_statuses() -> None: + from litellm.types.interactions import InteractionStatus, generated + + exported: Final = frozenset(member.value for member in InteractionStatus) + modelled: Final = frozenset(member.value for member in _status_enum_of(generated.Interaction)) + assert exported == modelled, sorted(exported ^ modelled) + + class TestRequestCompliance: """Tests that our request bodies match the OpenAPI spec.""" @@ -249,27 +280,24 @@ class TestResponseCompliance: assert field in schema["properties"], f"Output field '{field}' not in spec" print(f"✓ Output field '{field}' exists in spec") - def test_status_enum_values(self, spec_dict): - """Verify status enum values match spec.""" - # `status` is an output-only field; validate against the response schema. - schema = spec_dict["components"]["schemas"]["Interaction"] - status_prop = schema["properties"]["status"] - # Google Interactions API uses lowercase status values (updated Feb 2026). - # Keep this an exact match: this test intentionally breaks CI when - # Google changes the live spec — that breakage is how we get notified - # to review the change. - expected_statuses = [ - "in_progress", - "requires_action", - "completed", - "failed", - "cancelled", - "incomplete", - "budget_exceeded", - "queued", - ] - assert status_prop["enum"] == expected_statuses - print(f"✓ Status enum values: {expected_statuses}") + @pytest.mark.parametrize( + "schema_name", + [ + "Interaction", + "InteractionStatusUpdate", + "CreateModelInteractionParams", + "CreateAgentInteractionParams", + "UrlContextResult", + ], + ) + def test_status_enum_values(self, spec_dict, schema_name): + from litellm.types.interactions import generated + + schema = spec_dict["components"]["schemas"][schema_name] + spec_statuses: Final = frozenset(schema["properties"]["status"]["enum"]) + parsed_statuses: Final = frozenset(member.value for member in _status_enum_of(getattr(generated, schema_name))) + assert spec_statuses + assert spec_statuses <= parsed_statuses, sorted(spec_statuses - parsed_statuses) def test_usage_schema(self, spec_dict): """Verify Usage schema fields.""" diff --git a/tests/unit/litellm_core_utils/test_exception_mapping_utils.py b/tests/unit/litellm_core_utils/test_exception_mapping_utils.py index 5ee14ff530d..9e8e9cf2a80 100644 --- a/tests/unit/litellm_core_utils/test_exception_mapping_utils.py +++ b/tests/unit/litellm_core_utils/test_exception_mapping_utils.py @@ -160,6 +160,12 @@ def test_api_base_line_keeps_an_at_sign_in_the_path(api_base: str) -> None: # Tuple format: (error_message, expected_result) context_window_test_cases = [ # Positive cases (should return True) + ( + '"{\n "error": {\n "message": "Your input exceeds the context window of this model. ' + 'Please adjust your input and try again.",\n "type": "invalid_request_error",\n' + ' "param": "input",\n "code": "context_length_exceeded"\n }\n}"', + True, + ), ( "An error occurred: The input exceeds the model's maximum context limit of 8192 tokens.", True, diff --git a/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_handler.py b/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_handler.py index 1f02b3aaa5a..f4920505722 100644 --- a/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_handler.py +++ b/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_handler.py @@ -2033,6 +2033,7 @@ async def test_anthropic_messages_with_extra_headers(): ], "model": "claude-haiku-4-5-20251001", "stop_reason": "end_turn", + "stop_sequence": None, "usage": {"input_tokens": 10, "output_tokens": 20}, } @@ -2096,6 +2097,7 @@ async def test_anthropic_messages_with_thinking(): ], "model": "claude-haiku-4-5-20251001", "stop_reason": "end_turn", + "stop_sequence": None, "usage": {"input_tokens": 10, "output_tokens": 20}, } @@ -2210,6 +2212,7 @@ async def test_anthropic_messages_bedrock_dynamic_region(): "content": [{"type": "text", "text": "This is a mock response"}], "model": "bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", "stop_reason": "end_turn", + "stop_sequence": None, "usage": {"input_tokens": 10, "output_tokens": 20}, } diff --git a/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_transformation.py b/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_transformation.py index 7fbec3ba12e..457d5d5e1c8 100644 --- a/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_transformation.py +++ b/tests/unit/llms/anthropic/pass_through/messages/test_anthropic_experimental_pass_through_messages_transformation.py @@ -1,17 +1,23 @@ from collections.abc import Mapping +from datetime import datetime, timezone from pathlib import Path from typing import Final from unittest.mock import patch +import httpx import pytest +from pydantic import JsonValue import litellm +from litellm.litellm_core_utils.litellm_logging import Logging from litellm.llms.anthropic.pass_through.messages.transformation import ( AnthropicMessagesConfig, ) from litellm.llms.anthropic.wif import get_anthropic_wif_token from litellm.llms.minimax.messages.transformation import MinimaxMessagesConfig +from litellm.llms.openai_like.messages.transformation import OpenAILikeAnthropicMessagesConfig from litellm.llms.tencent.messages.transformation import TencentAnthropicMessagesConfig +from litellm.types.llms.anthropic import AnthropicFinishReason from litellm.types.router import GenericLiteLLMParams from tests.unit.llms.anthropic.test_anthropic_wif import ( ScriptedPoster, @@ -27,6 +33,52 @@ _WIF_PARAMS: Final[dict] = { } +@pytest.mark.parametrize("config", (AnthropicMessagesConfig(), OpenAILikeAnthropicMessagesConfig()), ids=type) +@pytest.mark.parametrize( + ("stop_reason", "stop_fields", "expected_stop_sequence"), + ( + pytest.param("end_turn", {}, None, id="end_turn_missing"), + pytest.param("max_tokens", {}, None, id="max_tokens_missing"), + pytest.param("tool_use", {}, None, id="tool_use_missing"), + pytest.param("end_turn", {"stop_sequence": None}, None, id="explicit_null"), + pytest.param("stop_sequence", {"stop_sequence": ", 7"}, ", 7", id="matched_stop"), + ), +) +def test_native_response_defaults_stop_sequence_without_changing_other_fields( + config: AnthropicMessagesConfig, + stop_reason: AnthropicFinishReason, + stop_fields: Mapping[str, str | None], + expected_stop_sequence: str | None, +) -> None: + upstream: Final[dict[str, JsonValue]] = { + "id": "msg_test", + "type": "message", + "role": "assistant", + "model": "test-model", + "content": [{"type": "text", "text": "ok"}], + "stop_reason": stop_reason, + "usage": {"input_tokens": 19, "output_tokens": 42}, + **stop_fields, + } + logging_obj: Final = Logging( + model="test-model", + messages=[], + stream=False, + call_type="anthropic_messages", + start_time=datetime(2026, 1, 1, tzinfo=timezone.utc), + litellm_call_id="test-call", + function_id="test-function", + ) + response: Final = config.transform_anthropic_messages_response( + model="test-model", raw_response=httpx.Response(200, json=upstream), logging_obj=logging_obj + ) + + assert response == { + **upstream, + "stop_sequence": expected_stop_sequence, + } + + def test_workload_identity_allowed_for_anthropic() -> None: assert AnthropicMessagesConfig()._allows_workload_identity is True diff --git a/tests/unit/llms/anthropic/pass_through/messages/test_streaming_iterator.py b/tests/unit/llms/anthropic/pass_through/messages/test_streaming_iterator.py index fd9aa75be74..4ed9054f3d3 100644 --- a/tests/unit/llms/anthropic/pass_through/messages/test_streaming_iterator.py +++ b/tests/unit/llms/anthropic/pass_through/messages/test_streaming_iterator.py @@ -26,7 +26,9 @@ from litellm.llms.anthropic.pass_through.messages.streaming_iterator import ( is_provider_error_chunk, parse_anthropic_error_event, ) +from litellm.llms.anthropic.pass_through.messages.transformation import AnthropicMessagesConfig from litellm.llms.anthropic.pass_through.safeguards import SafeguardsEvaluator +from litellm.llms.openai_like.messages.transformation import OpenAILikeAnthropicMessagesConfig from litellm.types.utils import Choices, Message, ModelResponse @@ -1733,6 +1735,49 @@ async def _drained(stream: AsyncIterator[bytes]) -> list[bytes]: return [chunk async for chunk in stream] +@pytest.mark.asyncio +@pytest.mark.parametrize("config", (AnthropicMessagesConfig(), OpenAILikeAnthropicMessagesConfig()), ids=type) +@pytest.mark.parametrize("stop_sequence", (None, ", 7"), ids=("null", "matched_stop")) +async def test_native_stream_preserves_nullable_stop_fields_across_chunk_boundaries( + config: AnthropicMessagesConfig, stop_sequence: str | None +) -> None: + logging_obj: Final = _make_logging_obj("native_stream_stop_fields") + events: Final = ( + { + "type": "message_start", + "message": { + "id": "msg_test", + "type": "message", + "role": "assistant", + "model": logging_obj.model, + "content": [], + "stop_reason": None, + "stop_sequence": None, + "usage": {"input_tokens": 19, "output_tokens": 0}, + }, + }, + { + "type": "message_delta", + "delta": { + "stop_reason": "end_turn" if stop_sequence is None else "stop_sequence", + "stop_sequence": stop_sequence, + }, + "usage": {"output_tokens": 0}, + }, + {"type": "message_stop"}, + ) + upstream: Final = b"".join(f"event: {event['type']}\ndata: {json.dumps(event)}\n\n".encode() for event in events) + response: Final = httpx.Response(200, content=_chunked(upstream, 7)) + stream: Final = config.get_async_streaming_response_iterator( + model=logging_obj.model, + httpx_response=response, + request_body={"model": logging_obj.model}, + litellm_logging_obj=logging_obj, + ) + + assert b"".join(await _drained(stream)) == upstream + + def _data_events(frames: Sequence[bytes]) -> list[Mapping[str, object]]: return [ json.loads(line[len(b"data:") :]) for frame in frames for line in frame.splitlines() if line.startswith(b"data:") diff --git a/tests/unit/proxy/decisions_endpoints/test_endpoints.py b/tests/unit/proxy/decisions_endpoints/test_endpoints.py index 021eb289ad7..4384507e841 100644 --- a/tests/unit/proxy/decisions_endpoints/test_endpoints.py +++ b/tests/unit/proxy/decisions_endpoints/test_endpoints.py @@ -126,6 +126,51 @@ def test_proxy_decisions_route_returns_answers_and_cost( assert upstream.calls[0].request.headers["authorization"] == "Bearer test-key" +@pytest.mark.parametrize("endpoint", ("/v1/systemone", "/systemone")) +@pytest.mark.parametrize("question_count", (128, 129, 154)) +def test_proxy_systemone_preserves_large_question_batches( + client: TestClient, + respx_mock: respx.MockRouter, + endpoint: str, + question_count: int, +) -> None: + questions: Final = { + f"q{index}": {"type": "noul", "instructions": f"Question {index}?"} for index in range(question_count) + } + answers: Final = {f"q{index}": {"type": "noul", "noul": index / question_count} for index in range(question_count)} + upstream: Final = respx_mock.post("https://api.perplexity.ai/v1/decisions").respond( + json={**_RESPONSE, "answers": answers} + ) + + response: Final = client.post(endpoint, json={**_REQUEST, "questions": questions}) + + assert response.status_code == 200, response.text + assert json.loads(upstream.calls[0].request.content) == { + **_REQUEST, + "model": "pplx-decider-v1-27b", + "questions": questions, + } + assert response.json()["answers"] == answers + + +@pytest.mark.parametrize("endpoint", ("/v1/systemone", "/systemone")) +@pytest.mark.parametrize( + "questions", + ({}, {"": {"type": "noul", "instructions": "Is this a defect?"}}, {"is_defect": {"type": "noul"}}), + ids=("empty", "empty_name", "missing_instructions_or_criteria"), +) +def test_proxy_systemone_rejects_invalid_questions_before_http( + client: TestClient, + respx_mock: respx.MockRouter, + endpoint: str, + questions: Mapping[str, object], +) -> None: + response: Final = client.post(endpoint, json={**_REQUEST, "questions": questions}) + + assert response.status_code == 400, response.text + assert len(respx_mock.calls) == 0 + + def test_proxy_decisions_dispatches_typesafe_deployment( client: TestClient, monkeypatch: pytest.MonkeyPatch, diff --git a/tests/unit/proxy/management_endpoints/usage_endpoints/test_ai_usage_chat.py b/tests/unit/proxy/management_endpoints/usage_endpoints/test_ai_usage_chat.py deleted file mode 100644 index 4daddb89350..00000000000 --- a/tests/unit/proxy/management_endpoints/usage_endpoints/test_ai_usage_chat.py +++ /dev/null @@ -1,657 +0,0 @@ -""" -Tests for AI Usage Chat module. -""" - -import json -from collections.abc import AsyncIterator -from typing import Final -from unittest.mock import AsyncMock, MagicMock, patch - -import pytest -from fastapi import HTTPException - -from litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat import ( - TOOL_HANDLERS, - TOOLS_ADMIN, - TOOLS_BASE, - _build_system_prompt, - _summarise_entity_data, - _summarise_usage_data, - stream_usage_ai_chat, -) - - -SAMPLE_AGGREGATED_RESPONSE = { - "results": [ - { - "date": "2025-01-15", - "metrics": { - "spend": 50.25, - "prompt_tokens": 20000, - "completion_tokens": 10000, - "total_tokens": 30000, - "api_requests": 500, - "successful_requests": 480, - "failed_requests": 20, - "cache_read_input_tokens": 0, - "cache_creation_input_tokens": 0, - }, - "breakdown": { - "models": { - "gpt-4": { - "metrics": { - "spend": 40.0, - "api_requests": 300, - "total_tokens": 25000, - }, - "metadata": {}, - "api_key_breakdown": {}, - }, - }, - "providers": { - "openai": { - "metrics": {"spend": 50.25, "api_requests": 500}, - "metadata": {}, - "api_key_breakdown": {}, - }, - }, - "api_keys": { - "sk-test123": { - "metrics": {"spend": 50.25}, - "metadata": {"key_alias": "Production Key"}, - }, - }, - "model_groups": {}, - "mcp_servers": {}, - "entities": {}, - }, - }, - ], - "metadata": { - "total_spend": 50.25, - "total_api_requests": 500, - "total_successful_requests": 480, - "total_failed_requests": 20, - "total_tokens": 30000, - }, -} - -SAMPLE_TEAM_RESPONSE = { - "results": [ - { - "date": "2025-01-15", - "metrics": {"spend": 100.0, "api_requests": 1000, "total_tokens": 50000}, - "breakdown": { - "entities": { - "team-1": { - "metrics": { - "spend": 60.0, - "api_requests": 600, - "total_tokens": 30000, - }, - "metadata": {"alias": "Engineering"}, - "api_key_breakdown": {}, - }, - "team-2": { - "metrics": { - "spend": 40.0, - "api_requests": 400, - "total_tokens": 20000, - }, - "metadata": {"alias": "Marketing"}, - "api_key_breakdown": {}, - }, - }, - "models": {}, - "providers": {}, - "api_keys": {}, - "model_groups": {}, - "mcp_servers": {}, - }, - }, - ], - "metadata": {"total_spend": 100.0, "total_api_requests": 1000}, -} - - -class TestToolSchemas: - def test_admin_tools_include_all(self): - assert len(TOOLS_ADMIN) == 3 - names = {t["function"]["name"] for t in TOOLS_ADMIN} - assert "get_usage_data" in names - assert "get_team_usage_data" in names - assert "get_tag_usage_data" in names - - def test_base_tools_restricted_to_usage_only(self): - assert len(TOOLS_BASE) == 1 - assert TOOLS_BASE[0]["function"]["name"] == "get_usage_data" - - def test_admin_prompt_mentions_all_tools(self): - prompt = _build_system_prompt(is_admin=True) - assert "get_usage_data" in prompt - assert "get_team_usage_data" in prompt - assert "get_tag_usage_data" in prompt - - def test_non_admin_prompt_only_mentions_usage_tool(self): - prompt = _build_system_prompt(is_admin=False) - assert "get_usage_data" in prompt - assert "get_team_usage_data" not in prompt - assert "get_tag_usage_data" not in prompt - - def test_system_prompt_includes_todays_date(self): - from datetime import date - - prompt = _build_system_prompt(is_admin=True) - assert date.today().isoformat() in prompt - - -class TestSummariseUsageData: - def test_summarise_includes_totals(self): - summary = _summarise_usage_data(SAMPLE_AGGREGATED_RESPONSE) - assert "$50.25" in summary - assert "500" in summary - - def test_summarise_includes_models(self): - summary = _summarise_usage_data(SAMPLE_AGGREGATED_RESPONSE) - assert "gpt-4" in summary - - def test_summarise_includes_providers(self): - summary = _summarise_usage_data(SAMPLE_AGGREGATED_RESPONSE) - assert "openai" in summary - - def test_summarise_handles_empty_data(self): - empty = {"results": [], "metadata": {}} - summary = _summarise_usage_data(empty) - assert "no data" in summary.lower() - - -class TestSummariseEntityData: - def test_team_summary_includes_teams(self): - summary = _summarise_entity_data(SAMPLE_TEAM_RESPONSE, "Team") - assert "Engineering" in summary - assert "Marketing" in summary - assert "$60.0" in summary - assert "$40.0" in summary - - def test_team_summary_empty(self): - empty = {"results": [], "metadata": {}} - summary = _summarise_entity_data(empty, "Team") - assert "No Team usage data" in summary - - -class TestStreamUsageAiChat: - @pytest.mark.asyncio - async def test_stream_emits_status_events(self): - mock_tool_call = MagicMock() - mock_tool_call.id = "call_123" - mock_tool_call.function.name = "get_usage_data" - mock_tool_call.function.arguments = json.dumps( - { - "start_date": "2025-01-01", - "end_date": "2025-01-31", - } - ) - - mock_first_response = MagicMock() - mock_first_response.choices = [MagicMock()] - mock_first_response.choices[0].message.tool_calls = [mock_tool_call] - mock_first_response.choices[0].message.model_dump.return_value = { - "role": "assistant", - "content": None, - "tool_calls": [ - { - "id": "call_123", - "type": "function", - "function": { - "name": "get_usage_data", - "arguments": '{"start_date":"2025-01-01","end_date":"2025-01-31"}', - }, - } - ], - } - - async def mock_stream(): - chunk = MagicMock() - chunk.choices = [MagicMock()] - chunk.choices[0].delta.content = "Total spend is $50.25" - yield chunk - - with ( - patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.litellm" - ) as mock_litellm, - patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat._fetch_usage_data", - new_callable=AsyncMock, - ) as mock_fetch, - ): - mock_litellm.acompletion = AsyncMock( - side_effect=[ - mock_first_response, - mock_stream(), - ] - ) - mock_fetch.return_value = SAMPLE_AGGREGATED_RESPONSE - - events = [] - async for event in stream_usage_ai_chat( - messages=[{"role": "user", "content": "What is my total spend?"}], - model="gpt-4o-mini", - user_id="user-123", - is_admin=True, - ): - events.append(json.loads(event.replace("data: ", "").strip())) - - status_events = [e for e in events if e["type"] == "status"] - tool_call_events = [e for e in events if e["type"] == "tool_call"] - chunk_events = [e for e in events if e["type"] == "chunk"] - done_events = [e for e in events if e["type"] == "done"] - - assert len(status_events) >= 1 - assert "Thinking" in status_events[0]["message"] - assert len(tool_call_events) >= 1 - assert tool_call_events[0]["tool_name"] == "get_usage_data" - assert tool_call_events[0]["status"] in ("running", "complete") - assert len(chunk_events) >= 1 - assert len(done_events) == 1 - - @pytest.mark.asyncio - async def test_stream_handles_team_tool(self): - mock_tool_call = MagicMock() - mock_tool_call.id = "call_team" - mock_tool_call.function.name = "get_team_usage_data" - mock_tool_call.function.arguments = json.dumps( - { - "start_date": "2025-01-01", - "end_date": "2025-01-31", - } - ) - - mock_first_response = MagicMock() - mock_first_response.choices = [MagicMock()] - mock_first_response.choices[0].message.tool_calls = [mock_tool_call] - mock_first_response.choices[0].message.model_dump.return_value = { - "role": "assistant", - "content": None, - "tool_calls": [ - { - "id": "call_team", - "type": "function", - "function": { - "name": "get_team_usage_data", - "arguments": '{"start_date":"2025-01-01","end_date":"2025-01-31"}', - }, - } - ], - } - - async def mock_stream(): - chunk = MagicMock() - chunk.choices = [MagicMock()] - chunk.choices[0].delta.content = "Engineering is the top team." - yield chunk - - with ( - patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.litellm" - ) as mock_litellm, - patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat._fetch_team_usage_data", - new_callable=AsyncMock, - ) as mock_fetch, - ): - mock_litellm.acompletion = AsyncMock( - side_effect=[ - mock_first_response, - mock_stream(), - ] - ) - mock_fetch.return_value = SAMPLE_TEAM_RESPONSE - - events = [] - async for event in stream_usage_ai_chat( - messages=[{"role": "user", "content": "Which team spends the most?"}], - model="gpt-4o-mini", - is_admin=True, - ): - events.append(json.loads(event.replace("data: ", "").strip())) - - chunk_events = [e for e in events if e["type"] == "chunk"] - assert len(chunk_events) >= 1 - assert "Engineering" in chunk_events[0]["content"] - - @pytest.mark.asyncio - @pytest.mark.parametrize( - "reason", - [ - "end_date must be on or after start_date", - "start_date and end_date must be valid YYYY-MM-DD dates", - ], - ids=["reversed", "invalid-format"], - ) - @pytest.mark.parametrize( - "tool_name", ["get_usage_data", "get_team_usage_data", "get_tag_usage_data"] - ) - async def test_invalid_tool_dates_are_reported_to_the_model( - self, tool_name: str, reason: str - ) -> None: - fetch: Final = AsyncMock( - side_effect=HTTPException(status_code=400, detail={"error": reason}) - ) - - tool_message, statuses = await _run_one_tool( - tool_name, "2025-01-31", "2025-01-01", fetch - ) - - fetch.assert_awaited_once() - assert tool_message == f"Invalid date range: {reason}" - assert statuses == ["running", "complete"] - - @pytest.mark.asyncio - async def test_tool_dates_the_query_layer_accepts_are_queried_as_sent( - self, - ) -> None: - fetch: Final = AsyncMock(return_value=SAMPLE_AGGREGATED_RESPONSE) - - tool_message, statuses = await _run_one_tool( - "get_usage_data", "2025/01/01", "2025-01-31T00:00:00", fetch - ) - - fetch.assert_awaited_once_with( - start_date="2025/01/01", end_date="2025-01-31T00:00:00" - ) - assert tool_message.startswith("Total Spend: $") - assert statuses == ["running", "complete"] - - @pytest.mark.asyncio - @pytest.mark.parametrize( - "error", - [ - HTTPException(status_code=500, detail={"error": "db down"}), - HTTPException(status_code=400, detail="page and page_size must be >= 1"), - ], - ids=["server-error", "other-400"], - ) - async def test_other_tool_errors_stay_a_generic_fetch_error( - self, error: HTTPException - ) -> None: - tool_message, statuses = await _run_one_tool( - "get_team_usage_data", - "2025-01-01", - "2025-01-31", - AsyncMock(side_effect=error), - ) - - assert tool_message == "Error fetching team usage data. Please try again." - assert statuses == ["running", "error"] - - @pytest.mark.asyncio - async def test_stream_handles_error(self): - with patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.litellm" - ) as mock_litellm: - mock_litellm.acompletion = AsyncMock(side_effect=Exception("LLM error")) - - events = [] - async for event in stream_usage_ai_chat( - messages=[{"role": "user", "content": "test"}], - ): - events.append(json.loads(event.replace("data: ", "").strip())) - - error_events = [e for e in events if e["type"] == "error"] - assert len(error_events) == 1 - assert "internal error" in error_events[0]["message"].lower() - - @pytest.mark.asyncio - async def test_non_admin_enforces_user_id(self): - mock_tool_call = MagicMock() - mock_tool_call.id = "call_456" - mock_tool_call.function.name = "get_usage_data" - mock_tool_call.function.arguments = json.dumps( - { - "start_date": "2025-01-01", - "end_date": "2025-01-31", - "user_id": "other-user", - } - ) - - mock_first_response = MagicMock() - mock_first_response.choices = [MagicMock()] - mock_first_response.choices[0].message.tool_calls = [mock_tool_call] - mock_first_response.choices[0].message.model_dump.return_value = { - "role": "assistant", - "content": None, - "tool_calls": [ - { - "id": "call_456", - "type": "function", - "function": { - "name": "get_usage_data", - "arguments": '{"start_date":"2025-01-01","end_date":"2025-01-31","user_id":"other-user"}', - }, - } - ], - } - - async def mock_stream(): - chunk = MagicMock() - chunk.choices = [MagicMock()] - chunk.choices[0].delta.content = "Data." - yield chunk - - mock_fetch = AsyncMock(return_value=SAMPLE_AGGREGATED_RESPONSE) - - with ( - patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.litellm" - ) as mock_litellm, - patch.dict( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.TOOL_HANDLERS", - { - "get_usage_data": { - "fetch": mock_fetch, - "summarise": _summarise_usage_data, - "label": "global usage data", - } - }, - ), - ): - mock_litellm.acompletion = AsyncMock( - side_effect=[ - mock_first_response, - mock_stream(), - ] - ) - - events = [] - async for event in stream_usage_ai_chat( - messages=[{"role": "user", "content": "Show data"}], - model="gpt-4o-mini", - user_id="my-user-id", - is_admin=False, - ): - events.append(event) - - mock_fetch.assert_called_once_with( - start_date="2025-01-01", - end_date="2025-01-31", - user_id="my-user-id", - ) - - -class TestUsageAiChatServiceAccountGuard: - """ - Security regression: a non-admin caller with user_id=None (service-account - key) must be rejected at the endpoint boundary, before any tool dispatch. - """ - - @pytest.mark.asyncio - async def test_non_admin_with_user_id_none_is_rejected(self): - from fastapi import HTTPException - - from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth - from litellm.proxy.management_endpoints.usage_endpoints.endpoints import ( - ChatMessage, - UsageAIChatRequest, - usage_ai_chat, - ) - - service_account_key = UserAPIKeyAuth( - user_id=None, - user_role=LitellmUserRoles.INTERNAL_USER, - ) - request = MagicMock() - body = UsageAIChatRequest( - messages=[ChatMessage(role="user", content="hi")], - model="gpt-4o-mini", - ) - - with pytest.raises(HTTPException) as exc_info: - await usage_ai_chat( - data=body, - request=request, - user_api_key_dict=service_account_key, - ) - - assert exc_info.value.status_code == 403 - assert "Service-account keys" in str(exc_info.value.detail) - - def test_resolve_fetch_kwargs_tripwire_fires_on_none_user_id(self): - """ - Defense-in-depth: if a future endpoint forgets the entry guard and - a non-admin caller with user_id=None reaches _resolve_fetch_kwargs, - the tripwire must fire rather than issuing an unscoped query. - """ - from litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat import ( - _resolve_fetch_kwargs, - ) - - with pytest.raises(ValueError, match='Non-admin caller has user_id=None; refusing to issue an') as exc_info: - _resolve_fetch_kwargs( - fn_name="get_usage_data", - fn_args={"start_date": "2025-01-01", "end_date": "2025-01-31"}, - user_id=None, - is_admin=False, - ) - assert "Endpoint-level guard missing" in str(exc_info.value) - - -class TestUsageAiChatKeepalive: - async def _collect_endpoint_body(self, monkeypatch, interval, delay=0.3) -> tuple[list[bytes], dict]: - import asyncio - - import litellm - from fastapi.responses import StreamingResponse - from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth - from litellm.proxy.management_endpoints.usage_endpoints.endpoints import ( - ChatMessage, - UsageAIChatRequest, - usage_ai_chat, - ) - - monkeypatch.setattr(litellm, "sse_keepalive_ping_interval_seconds", interval) - - async def slow_acompletion(**kwargs): - await asyncio.sleep(delay) - response = MagicMock() - response.choices = [MagicMock()] - response.choices[0].message.tool_calls = None - response.choices[0].message.content = "Total spend is $50.25" - return response - - with patch( # test-quality-ok: the stream calls the module-level litellm.acompletion directly; no injection seam - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.litellm.acompletion", - new=AsyncMock(side_effect=slow_acompletion), - ): - response = await usage_ai_chat( - data=UsageAIChatRequest(messages=[ChatMessage(role="user", content="hi")], model="gpt-4o-mini"), - request=MagicMock(), - user_api_key_dict=UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN), - ) - assert isinstance(response, StreamingResponse) - chunks = [chunk if isinstance(chunk, bytes) else chunk.encode() async for chunk in response.body_iterator] - return chunks, dict(response.headers) - - @pytest.mark.asyncio - async def test_endpoint_pings_while_the_planning_completion_is_still_running(self, monkeypatch): - chunks, headers = await self._collect_endpoint_body(monkeypatch, interval=0.05) - - assert headers["content-type"].startswith("text/event-stream") - assert headers["cache-control"] == "no-cache" - assert headers["x-accel-buffering"] == "no" - assert chunks[0].startswith(b'data: {"type": "status"') - assert chunks[1] == b": ping\n\n" - assert chunks.count(b": ping\n\n") >= 3 - assert b'"content": "Total spend is $50.25"' in b"".join(chunks) - assert chunks[-1] == b'data: {"type": "done"}\n\n' - - @pytest.mark.asyncio - async def test_endpoint_stream_is_untouched_while_keepalives_are_unconfigured(self, monkeypatch): - chunks, _ = await self._collect_endpoint_body(monkeypatch, interval=None, delay=0.15) - - assert b": ping\n\n" not in chunks - assert chunks[0].startswith(b'data: {"type": "status"') - assert chunks[-1] == b'data: {"type": "done"}\n\n' - - -async def _run_one_tool( - tool_name: str, start_date: str, end_date: str, fetch: AsyncMock -) -> tuple[str, list[object]]: - """Runs one admin chat turn whose model calls `tool_name` with these dates; returns the - tool message the follow-up model call carried and the tool statuses streamed.""" - arguments: Final = json.dumps({"start_date": start_date, "end_date": end_date}) - mock_tool_call: Final = MagicMock() - mock_tool_call.id = "call_dates" - mock_tool_call.function.name = tool_name - mock_tool_call.function.arguments = arguments - - mock_first_response: Final = MagicMock() - mock_first_response.choices = [MagicMock()] - mock_first_response.choices[0].message.tool_calls = [mock_tool_call] - mock_first_response.choices[0].message.model_dump.return_value = { - "role": "assistant", - "content": None, - "tool_calls": [ - { - "id": "call_dates", - "type": "function", - "function": {"name": tool_name, "arguments": arguments}, - } - ], - } - - async def mock_stream() -> AsyncIterator[MagicMock]: - chunk: Final = MagicMock() - chunk.choices = [MagicMock()] - chunk.choices[0].delta.content = "Done." - yield chunk - - with ( - patch( - "litellm.proxy.management_endpoints.usage_endpoints.ai_usage_chat.litellm" - ) as mock_litellm, - patch.dict(TOOL_HANDLERS[tool_name], {"fetch": fetch}), - ): - mock_litellm.acompletion = AsyncMock( - side_effect=[mock_first_response, mock_stream()] - ) - events: Final[tuple[dict[str, object], ...]] = tuple( - [ - json.loads(event.replace("data: ", "").strip()) - async for event in stream_usage_ai_chat( - messages=[{"role": "user", "content": "How much did we spend?"}], - model="gpt-4o-mini", - is_admin=True, - ) - ] - ) - final_messages: Final = mock_litellm.acompletion.call_args_list[1].kwargs[ - "messages" - ] - - tool_messages: Final = [m for m in final_messages if m["role"] == "tool"] - assert len(tool_messages) == 1, tool_messages - assert tool_messages[0]["tool_call_id"] == "call_dates" - return str(tool_messages[0]["content"]), [ - e["status"] for e in events if e["type"] == "tool_call" - ] diff --git a/tests/unit/proxy/proxy_server/test_routes_config.py b/tests/unit/proxy/proxy_server/test_routes_config.py index a92986392e9..7d0a7f3f261 100644 --- a/tests/unit/proxy/proxy_server/test_routes_config.py +++ b/tests/unit/proxy/proxy_server/test_routes_config.py @@ -716,6 +716,53 @@ def test_config_list_exposes_config_reload_interval(client, auth_as, mock_prisma assert entry["field_default_value"] == 30 +@pytest.mark.parametrize("enabled", (True, False)) +def test_config_list_exposes_and_saves_wildcard_routes_toggle( + client: TestClient, + auth_as: Callable[..., contextlib.AbstractContextManager[object]], + mock_prisma: MagicMock, + monkeypatch: pytest.MonkeyPatch, + enabled: bool, +) -> None: + from pydantic import TypeAdapter + + from litellm.proxy import proxy_server as ps + from litellm.proxy._types import ConfigList, LitellmUserRoles + + table: Final = _install_litellm_config(mock_prisma) + monkeypatch.setattr(ps, "prisma_client", mock_prisma) + _seed_settings_store(monkeypatch, {}) + monkeypatch.setattr(ps, "general_settings", ps.proxy_config.settings) + entries: Final = TypeAdapter(list[ConfigList]) + + with auth_as(LitellmUserRoles.PROXY_ADMIN): + before: Final = client.get("/config/list", params={"config_type": "general_settings"}) + assert before.status_code == 200, before.text + toggle: Final = next( + entry for entry in entries.validate_json(before.content) if entry.field_name == "return_wildcard_routes" + ) + assert toggle.field_type == "Boolean" + assert toggle.field_value is None + assert toggle.editable is True + + saved: Final = client.post( + "/config/field/update", + json={"field_name": "return_wildcard_routes", "field_value": enabled, "config_type": "general_settings"}, + ) + assert saved.status_code == 200, saved.text + persisted: Final = TypeAdapter(dict[str, bool]).validate_json( + table.upsert.call_args.kwargs["data"]["create"]["param_value"] + ) + assert persisted == {"return_wildcard_routes": enabled} + + after: Final = client.get("/config/list", params={"config_type": "general_settings"}) + assert after.status_code == 200, after.text + updated: Final = next( + entry for entry in entries.validate_json(after.content) if entry.field_name == "return_wildcard_routes" + ) + assert updated.field_value is enabled + + def test_config_field_update_accepts_config_reload_interval(client, auth_as, mock_prisma, monkeypatch): """POST /config/field/update accepts proxy_config_reload_interval_seconds and persists it to the DB general_settings row for all pods to pick up.""" diff --git a/tests/unit/proxy/spend_tracking/test_spend_management_endpoints.py b/tests/unit/proxy/spend_tracking/test_spend_management_endpoints.py index 23bbe521670..8d53817f51e 100644 --- a/tests/unit/proxy/spend_tracking/test_spend_management_endpoints.py +++ b/tests/unit/proxy/spend_tracking/test_spend_management_endpoints.py @@ -5,19 +5,21 @@ import hashlib import json import re import sqlite3 +from collections.abc import Mapping from datetime import timezone -from typing import Final +from typing import Final, Literal from unittest.mock import AsyncMock, MagicMock, patch import prisma import pytest -from fastapi import HTTPException +from fastapi import HTTPException, Request from fastapi.testclient import TestClient import litellm import litellm.proxy.proxy_server as ps from litellm.proxy.auth.authorization import OwnedRows from litellm.proxy.auth.authorization_dependencies import get_log_team_lookup, load_permitted_log_team_ids +from litellm.proxy.auth.route_checks import RouteChecks def _default_date_range(): @@ -268,6 +270,8 @@ def make_ui_spend_logs_mock_prisma(mock_spend_logs, filter_fn, team_lookup_fn=No from litellm.constants import LITTELM_INTERNAL_HEALTH_SERVICE_ACCOUNT_NAME from litellm.proxy._types import ( + LiteLLM_TeamTable, + LiteLLM_UserTable, LitellmUserRoles, Member, ProxyException, @@ -1894,6 +1898,91 @@ async def test_ui_view_spend_logs_user_filter_intersects_permitted_team_scope(cl app.dependency_overrides.pop(ps.user_api_key_auth, None) +@pytest.mark.parametrize( + ("team_role", "selected_user", "expected_ids"), + ( + ("admin", None, ("member-in-team", "second-member-in-team")), + ("admin", "member", ("member-in-team",)), + ("admin", "caller", ()), + ("admin", "outsider", ()), + ("user", None, None), + (None, "member", None), + ), +) +def test_ui_client_usage_enforces_selected_team_and_member_scope( + client: TestClient, + monkeypatch: pytest.MonkeyPatch, + team_role: Literal["admin", "user"] | None, + selected_user: str | None, + expected_ids: tuple[str, ...] | None, +) -> None: + logs: Final = tuple( + { + "request_id": request_id, + "user": user_id, + "team_id": team_id, + "api_key": "shared-key", + "spend": 0.1, + "startTime": "2026-01-02T12:00:00+00:00", + "model": "test-model", + } + for request_id, user_id, team_id in ( + ("member-in-team", "member", "selected-team"), + ("same-member-other-team", "member", "other-team"), + ("second-member-in-team", "second-member", "selected-team"), + ("caller-personal", "caller", None), + ("outsider-request", "outsider", "other-team"), + ) + ) + team: Final = LiteLLM_TeamTable( + team_id="selected-team", + members_with_roles=([Member(user_id="caller", role=team_role)] if team_role else []) + + [Member(user_id="member", role="user"), Member(user_id="second-member", role="user")], + team_member_permissions=[], + ) + + async def team_lookup(where: Mapping[str, object]) -> LiteLLM_TeamTable | None: + return team if where.get("team_id") == team.team_id else None + + def filter_logs(where: Mapping[str, object]) -> tuple[dict[str, str | float | None], ...]: + return tuple( + row + for row in logs + if (where.get("team_id") is None or row["team_id"] == where["team_id"]) + and (where.get("user") is None or row["user"] == where["user"]) + ) + + auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER, user_id="caller") + RouteChecks.non_proxy_admin_allowed_routes_check( + user_obj=LiteLLM_UserTable(user_id="caller", user_role=LitellmUserRoles.INTERNAL_USER.value), + _user_role=LitellmUserRoles.INTERNAL_USER.value, + route="/spend/logs/ui", + request=Request({"type": "http", "method": "GET", "path": "/spend/logs/ui", "query_string": b""}), + valid_token=auth, + request_data={}, + ) + monkeypatch.setattr(ps, "prisma_client", make_ui_spend_logs_mock_prisma(logs, filter_logs, team_lookup)) + monkeypatch.setitem(app.dependency_overrides, ps.user_api_key_auth, lambda: auth) + response: Final = client.get( + "/spend/logs/ui", + params={ + "start_date": "2026-01-01 00:00:00", + "end_date": "2026-01-03 00:00:00", + "team_id": "selected-team", + "page_size": 1000, + "group_by_session": "false", + **({"user_id": selected_user} if selected_user else {}), + }, + headers={"Authorization": "Bearer sk-test"}, + ) + if expected_ids is None: + assert response.status_code == 403 + return + assert response.status_code == 200 + assert tuple(row["request_id"] for row in response.json()["data"]) == expected_ids + assert response.json()["total"] == len(expected_ids) + + @pytest.mark.asyncio async def test_ui_view_spend_logs_pagination(client, monkeypatch): mock_spend_logs = [ @@ -6524,7 +6613,6 @@ def test_ui_view_request_response_reads_from_cold_storage(client, monkeypatch): from litellm.proxy._types import ( LiteLLM_OrganizationMembershipTable, - LiteLLM_UserTable, LiteLLMRoutes, hash_token, ) diff --git a/tests/unit/proxy/test__lazy_features.py b/tests/unit/proxy/test__lazy_features.py index adc4de8c8fa..0749fc12ea9 100644 --- a/tests/unit/proxy/test__lazy_features.py +++ b/tests/unit/proxy/test__lazy_features.py @@ -93,6 +93,20 @@ def test_retired_roi_calculator_cannot_be_loaded_or_called( assert response.status_code == 404, f"{method} {path}: {response.text}" +@pytest.mark.parametrize("disable_lazy_routes", ("false", "true")) +@pytest.mark.parametrize("path", ("/lazy/warm/usage_ai", "/usage/ai/chat")) +def test_retired_usage_chat_cannot_be_loaded_or_called( + monkeypatch: pytest.MonkeyPatch, disable_lazy_routes: str, path: str +) -> None: + monkeypatch.setenv(FLAG, disable_lazy_routes) + app: Final = FastAPI() + attach_lazy_features(app) + + with TestClient(app) as client: + response: Final = client.post(path) + assert response.status_code == 404, f"{path}: {response.text}" + + @pytest.mark.parametrize("value", ("1", "true", "TRUE", "yes", "on")) def test_flag_registers_every_feature_at_startup(monkeypatch: pytest.MonkeyPatch, value: str) -> None: monkeypatch.setenv(FLAG, value) diff --git a/tests/unit/proxy/test_proxy_server.py b/tests/unit/proxy/test_proxy_server.py index f8ea1e5d075..a26a64c6fb0 100644 --- a/tests/unit/proxy/test_proxy_server.py +++ b/tests/unit/proxy/test_proxy_server.py @@ -3813,3 +3813,47 @@ def test_live_session_preserves_pretty_printed_start_frame( assert captured.route_type == "_arealtime" assert routed_data["model"] == "gpt-live-1" assert routed_data["live_session_start"] == expected_start + + +@pytest.mark.parametrize("scope", [None, "expand"]) +@pytest.mark.parametrize( + "general_settings, wildcard_query, wildcard_listed", + [ + ({}, None, False), + ({"return_wildcard_routes": False}, None, False), + ({"return_wildcard_routes": True}, None, True), + ({"return_wildcard_routes": "true"}, None, False), + ({"return_wildcard_routes": True}, False, False), + ({"return_wildcard_routes": False}, True, True), + ({}, True, True), + ], +) +@pytest.mark.asyncio +async def test_model_list_return_wildcard_routes_defaults_to_general_setting( + monkeypatch: pytest.MonkeyPatch, + general_settings: dict[str, object], + wildcard_query: bool | None, + wildcard_listed: bool, + scope: str | None, +) -> None: + router: Final = litellm.Router( + model_list=[ + {"model_name": "gpt-6.1-sol", "litellm_params": {"model": "openai/gpt-6.1-sol", "api_key": "sk-fake"}}, + {"model_name": "openai/*", "litellm_params": {"model": "openai/*", "api_key": "sk-fake"}}, + ] + ) + monkeypatch.setattr(litellm.proxy.proxy_server, "llm_router", router) + monkeypatch.setattr(litellm.proxy.proxy_server, "llm_model_list", router.model_list) + monkeypatch.setattr(litellm.proxy.proxy_server, "prisma_client", None) + monkeypatch.setattr(litellm.proxy.proxy_server, "user_model", None) + monkeypatch.setattr(litellm.proxy.proxy_server, "general_settings", general_settings) + + response: Final = await litellm.proxy.proxy_server.model_list( + user_api_key_dict=UserAPIKeyAuth(api_key="sk-test", user_role=LitellmUserRoles.PROXY_ADMIN), + return_wildcard_routes=wildcard_query, + scope=scope, + ) + listed: Final = [model["id"] for model in response["data"]] + + assert "gpt-6.1-sol" in listed, listed + assert ("openai/*" in listed) is wildcard_listed, listed diff --git a/tests/unit/proxy/ui_crud_endpoints/test_latest_release_endpoints.py b/tests/unit/proxy/ui_crud_endpoints/test_latest_release_endpoints.py index 25f1301dd9d..d5139263dc3 100644 --- a/tests/unit/proxy/ui_crud_endpoints/test_latest_release_endpoints.py +++ b/tests/unit/proxy/ui_crud_endpoints/test_latest_release_endpoints.py @@ -12,10 +12,11 @@ from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth from litellm.proxy.auth.user_api_key_auth import user_api_key_auth from litellm.proxy.proxy_server import app from litellm.proxy.ui_crud_endpoints.latest_release_endpoints import ( + CHANGELOG_FEED_URL, + CHANGELOG_URL, LATEST_RELEASE_CACHE_KEY, LATEST_RELEASE_CACHE_TTL_SECONDS, LATEST_RELEASE_UNAVAILABLE_CACHE_TTL_SECONDS, - LATEST_RELEASE_URL, RELEASE_BY_TAG_URL, LatestReleaseInfo, LatestReleaseUnavailable, @@ -49,37 +50,68 @@ SAMPLE_RELEASE: Final = { "html_url": "https://github.com/BerriAI/litellm/releases/tag/v1.102.0", "body": SAMPLE_BODY, } + + +def _changelog_page(folder: str) -> str: + return f"{CHANGELOG_URL}{folder}/{folder.removeprefix('v').replace('.', '-')}" + + +def _feed(*folders: str) -> httpx.Response: + items: Final = "".join( + f"{folder}{_changelog_page(folder)}" for folder in folders + ) + return httpx.Response(200, content=f'{items}'.encode()) + + EXPECTED_INFO: Final = { "version": "1.102.0", "new_features": 2, "bug_fixes": 2, "other_updates": 4, - "release_url": SAMPLE_RELEASE["html_url"], + "release_url": _changelog_page("v1.102.0"), } -class _RecordingClient: - def __init__(self, outcomes: list[httpx.Response | Exception]) -> None: - self._outcomes = outcomes - self.calls: list[tuple[str, float | None]] = [] - - async def get(self, url: str, *, timeout: float | None = None) -> httpx.Response: - self.calls.append((url, timeout)) - outcome = self._outcomes[min(len(self.calls) - 1, len(self._outcomes) - 1)] - if isinstance(outcome, Exception): - raise outcome - return outcome - - def _github_response(status: int = 200, payload: object = SAMPLE_RELEASE) -> httpx.Response: return httpx.Response(status, content=json.dumps(payload).encode()) +def _tag_url(tag: str) -> str: + return RELEASE_BY_TAG_URL.format(tag=tag) + + +class _ByUrl: + """Answers each URL from a fixed map; unknown URLs are 404, like a tag with no release.""" + + def __init__(self, routes: dict[str, httpx.Response | Exception]) -> None: + self._routes = routes + self.calls: list[tuple[str, float | None]] = [] + + async def get(self, url: str, *, timeout: float | None = None) -> httpx.Response: + self.calls.append((url, timeout)) + outcome = self._routes.get(url, httpx.Response(404, content=b"{}")) + if isinstance(outcome, Exception): + raise outcome + return outcome + + @property + def urls(self) -> list[str]: + return [url for url, _ in self.calls] + + +def _minor_release_routes(**overrides: httpx.Response | Exception) -> dict[str, httpx.Response | Exception]: + return {CHANGELOG_FEED_URL: _feed("v1.102.0"), _tag_url("v1.102.0"): _github_response(), **overrides} + + +def _minor_release(**overrides: httpx.Response | Exception) -> _ByUrl: + return _ByUrl(_minor_release_routes(**overrides)) + + def _fresh_cache() -> InMemoryCache: return InMemoryCache(max_size_in_memory=1, default_ttl=LATEST_RELEASE_CACHE_TTL_SECONDS) -def _override_dependencies(client: _RecordingClient, cache: InMemoryCache, role: LitellmUserRoles) -> None: +def _override_dependencies(client: _ByUrl, cache: InMemoryCache, role: LitellmUserRoles) -> None: async def auth() -> UserAPIKeyAuth: return UserAPIKeyAuth(api_key="sk-test", user_id="test-user", user_role=role) @@ -127,35 +159,68 @@ class TestCountReleaseBullets: class TestGetLatestReleaseInfo: @pytest.mark.asyncio - async def test_fetches_and_parses_github_release(self): - client = _RecordingClient([_github_response()]) + async def test_announces_the_changelog_release_and_links_its_changelog_page(self): + client = _minor_release() result = await get_latest_release_info(client=client, cache=_fresh_cache(), fetch_lock=asyncio.Lock()) assert isinstance(result, LatestReleaseInfo) assert result.model_dump() == EXPECTED_INFO - assert client.calls == [(LATEST_RELEASE_URL, 5)] + assert client.calls == [(CHANGELOG_FEED_URL, 5), (_tag_url("v1.102.0"), 5)] + + @pytest.mark.asyncio + async def test_github_release_missing_from_the_changelog_is_not_announced(self): + automated: Final = _github_response(payload=_release("v1.103.0", "* feat(proxy): automated release\n")) + result = await _info(_minor_release(**{_tag_url("v1.103.0"): automated})) + assert isinstance(result, LatestReleaseInfo) + assert result.model_dump() == EXPECTED_INFO + + @pytest.mark.asyncio + async def test_highest_stable_version_wins_regardless_of_feed_order(self): + client = _minor_release(**{CHANGELOG_FEED_URL: _feed("v1.101.6", "v1.103.0rc1", "v1.102.0", "v1.100.9")}) + result = await _info(client) + assert isinstance(result, LatestReleaseInfo) + assert result.model_dump() == EXPECTED_INFO + + @pytest.mark.asyncio + @pytest.mark.parametrize( + "feed", + [ + httpx.Response(503, content=_feed("v1.102.0").content), + httpx.Response(200, content=b"not a feed"), + _feed("v1.103.0rc1", "v1.103.0-dev.1"), + httpx.Response( + 200, + content=f"https://example.com/?{_changelog_page('v9.0.0')}" + "https://example.com/release_notes/v9.0.0/x".encode(), + ), + ], + ids=["server_error", "not_xml", "only_prereleases", "foreign_links"], + ) + async def test_bad_changelog_feeds_are_unavailable(self, feed: httpx.Response): + client = _minor_release(**{CHANGELOG_FEED_URL: feed}) + result = await _info(client) + assert isinstance(result, LatestReleaseUnavailable) + assert client.urls == [CHANGELOG_FEED_URL] @pytest.mark.asyncio async def test_second_call_within_ttl_does_not_refetch(self): - client = _RecordingClient([_github_response()]) + client = _minor_release() cache = _fresh_cache() fetch_lock = asyncio.Lock() first = await get_latest_release_info(client=client, cache=cache, fetch_lock=fetch_lock) second = await get_latest_release_info(client=client, cache=cache, fetch_lock=fetch_lock) assert first == second - assert len(client.calls) == 1 + assert len(client.calls) == 2 @pytest.mark.asyncio async def test_success_is_cached_for_the_full_ttl(self): cache = _fresh_cache() - await get_latest_release_info( - client=_RecordingClient([_github_response()]), cache=cache, fetch_lock=asyncio.Lock() - ) + await get_latest_release_info(client=_minor_release(), cache=cache, fetch_lock=asyncio.Lock()) remaining = await cache.async_get_ttl(LATEST_RELEASE_CACHE_KEY) - time.time() assert LATEST_RELEASE_CACHE_TTL_SECONDS - 5 < remaining <= LATEST_RELEASE_CACHE_TTL_SECONDS @pytest.mark.asyncio async def test_failure_is_cached_briefly_so_github_is_not_hammered(self): - client = _RecordingClient([httpx.ConnectError("boom")]) + client = _ByUrl({CHANGELOG_FEED_URL: httpx.ConnectError("boom")}) cache = _fresh_cache() fetch_lock = asyncio.Lock() first = await get_latest_release_info(client=client, cache=cache, fetch_lock=fetch_lock) @@ -172,30 +237,29 @@ class TestGetLatestReleaseInfo: @pytest.mark.parametrize( "response", [ + _github_response(status=404, payload={"message": "Not Found"}), _github_response(status=403, payload={"message": "rate limited"}), _github_response(status=500, payload={}), _github_response(payload={"tag_name": "v1.0.0"}), httpx.Response(200, content=b"not json"), + httpx.ConnectError("boom"), ], - ids=["rate_limited", "server_error", "missing_fields", "not_json"], + ids=["no_release_for_tag", "rate_limited", "server_error", "missing_fields", "not_json", "unreachable"], ) - async def test_bad_github_responses_are_unavailable(self, response: httpx.Response): - result = await get_latest_release_info( - client=_RecordingClient([response]), cache=_fresh_cache(), fetch_lock=asyncio.Lock() - ) + async def test_bad_github_responses_are_unavailable(self, response: httpx.Response | Exception): + result = await _info(_minor_release(**{_tag_url("v1.102.0"): response})) assert isinstance(result, LatestReleaseUnavailable) @pytest.mark.asyncio async def test_concurrent_misses_share_one_fetch(self): event = asyncio.Event() - class _BlockingClient(_RecordingClient): + class _BlockingClient(_ByUrl): async def get(self, url: str, *, timeout: float | None = None) -> httpx.Response: - self.calls.append((url, timeout)) await event.wait() - return _github_response() + return await super().get(url, timeout=timeout) - client = _BlockingClient([]) + client = _BlockingClient(_minor_release_routes()) cache = _fresh_cache() fetch_lock = asyncio.Lock() tasks = [ @@ -208,19 +272,19 @@ class TestGetLatestReleaseInfo: results = await asyncio.gather(*tasks) expected: Final = LatestReleaseInfo.model_validate(EXPECTED_INFO) assert results == [expected] * 5 - assert len(client.calls) == 1 + assert len(client.calls) == 2 @pytest.mark.asyncio async def test_failure_under_lock_is_also_coalesced(self): event = asyncio.Event() - class _FailingBlockingClient(_RecordingClient): + class _FailingBlockingClient(_ByUrl): async def get(self, url: str, *, timeout: float | None = None) -> httpx.Response: self.calls.append((url, timeout)) await event.wait() raise httpx.ConnectError("boom") - client = _FailingBlockingClient([]) + client = _FailingBlockingClient({}) cache = _fresh_cache() fetch_lock = asyncio.Lock() tasks = [ @@ -245,40 +309,23 @@ def _release(tag: str, body: str | None, *, prerelease: bool = False) -> dict[st } -def _tag_url(tag: str) -> str: - return RELEASE_BY_TAG_URL.format(tag=tag) - - -class _GitHubByUrl: - """Answers each GitHub URL from a fixed map; unknown URLs are 404, like a tag with no release.""" - - def __init__(self, routes: dict[str, httpx.Response | Exception]) -> None: - self._routes = routes - self.urls: list[str] = [] - - async def get(self, url: str, *, timeout: float | None = None) -> httpx.Response: - self.urls.append(url) - outcome = self._routes.get(url, httpx.Response(404, content=b"{}")) - if isinstance(outcome, Exception): - raise outcome - return outcome - - PATCH_RELEASE: Final = _release("v1.102.2", "* fix(proxy): second backport by @k in https://x/pull/10\n") FIRST_PATCH: Final = _release("v1.102.1", "* fix(proxy): first backport by @k in https://x/pull/9\n") -def _minor_line(**overrides: httpx.Response | Exception) -> dict[str, httpx.Response | Exception]: - routes: dict[str, httpx.Response | Exception] = { - LATEST_RELEASE_URL: _github_response(payload=PATCH_RELEASE), - _tag_url("v1.102.0"): _github_response(payload=SAMPLE_RELEASE), - _tag_url("v1.102.1"): _github_response(payload=FIRST_PATCH), - } - routes.update({_tag_url(tag): outcome for tag, outcome in overrides.items()}) - return routes +def _minor_line(**overrides: httpx.Response | Exception) -> _ByUrl: + return _ByUrl( + { + CHANGELOG_FEED_URL: _feed("v1.102.2", "v1.101.6"), + _tag_url("v1.102.2"): _github_response(payload=PATCH_RELEASE), + _tag_url("v1.102.0"): _github_response(payload=SAMPLE_RELEASE), + _tag_url("v1.102.1"): _github_response(payload=FIRST_PATCH), + **{_tag_url(tag): outcome for tag, outcome in overrides.items()}, + } + ) -async def _info(client: _GitHubByUrl) -> LatestReleaseInfo | LatestReleaseUnavailable: +async def _info(client: _ByUrl) -> LatestReleaseInfo | LatestReleaseUnavailable: return await get_latest_release_info(client=client, cache=_fresh_cache(), fetch_lock=asyncio.Lock()) @@ -289,7 +336,7 @@ class TestPatchReleaseAggregatesMinorLine: @pytest.mark.asyncio async def test_patch_release_counts_include_every_earlier_patch_on_its_line(self): - client = _GitHubByUrl(_minor_line()) + client = _minor_line() result = await _info(client) assert isinstance(result, LatestReleaseInfo) assert result.model_dump() == { @@ -297,23 +344,11 @@ class TestPatchReleaseAggregatesMinorLine: "new_features": 2, "bug_fixes": 4, "other_updates": 4, - "release_url": PATCH_RELEASE["html_url"], + "release_url": _changelog_page("v1.102.2"), } - assert sorted(client.urls) == sorted([LATEST_RELEASE_URL, _tag_url("v1.102.0"), _tag_url("v1.102.1")]) - - @pytest.mark.asyncio - async def test_minor_release_makes_a_single_request(self): - client = _RecordingClient([_github_response()]) - await get_latest_release_info(client=client, cache=_fresh_cache(), fetch_lock=asyncio.Lock()) - assert client.calls == [(LATEST_RELEASE_URL, 5)] - - @pytest.mark.asyncio - async def test_non_semver_latest_tag_counts_only_its_own_notes(self): - client = _GitHubByUrl({LATEST_RELEASE_URL: _github_response(payload=_release("v1.102.1-hotfix", "* fix: x\n"))}) - result = await _info(client) - assert isinstance(result, LatestReleaseInfo) - assert (result.new_features, result.bug_fixes, result.other_updates) == (0, 1, 0) - assert client.urls == [LATEST_RELEASE_URL] + assert sorted(client.urls) == sorted( + [CHANGELOG_FEED_URL, _tag_url("v1.102.2"), _tag_url("v1.102.0"), _tag_url("v1.102.1")] + ) @pytest.mark.asyncio @pytest.mark.parametrize( @@ -326,15 +361,13 @@ class TestPatchReleaseAggregatesMinorLine: ids=["never_published", "prerelease", "null_body"], ) async def test_missing_prerelease_or_empty_patch_adds_nothing(self, skipped: httpx.Response): - result = await _info(_GitHubByUrl(_minor_line(**{"v1.102.1": skipped}))) + result = await _info(_minor_line(**{"v1.102.1": skipped})) assert isinstance(result, LatestReleaseInfo) assert (result.new_features, result.bug_fixes, result.other_updates) == (2, 3, 4) @pytest.mark.asyncio async def test_latest_release_with_null_body_still_counts_its_line(self): - routes = _minor_line() - routes[LATEST_RELEASE_URL] = _github_response(payload=_release("v1.102.2", None)) - result = await _info(_GitHubByUrl(routes)) + result = await _info(_minor_line(**{"v1.102.2": _github_response(payload=_release("v1.102.2", None))})) assert isinstance(result, LatestReleaseInfo) assert (result.new_features, result.bug_fixes, result.other_updates) == (2, 3, 4) @@ -349,31 +382,50 @@ class TestPatchReleaseAggregatesMinorLine: ids=["unreachable", "rate_limited", "not_json"], ) async def test_earlier_patch_failure_is_unavailable(self, outcome: httpx.Response | Exception): - result = await _info(_GitHubByUrl(_minor_line(**{"v1.102.0": outcome}))) + result = await _info(_minor_line(**{"v1.102.0": outcome})) assert isinstance(result, LatestReleaseUnavailable) class TestLatestReleaseInfoEndpoint: def test_returns_release_stats_for_authenticated_user(self, http_client): - _override_dependencies(_RecordingClient([_github_response()]), _fresh_cache(), LitellmUserRoles.INTERNAL_USER) + _override_dependencies(_minor_release(), _fresh_cache(), LitellmUserRoles.INTERNAL_USER) response = http_client.get("/get/latest_release_info") assert response.status_code == 200 assert response.json() == EXPECTED_INFO - def test_returns_null_when_github_is_unreachable(self, http_client): + def test_returns_null_when_the_changelog_is_unreachable(self, http_client): _override_dependencies( - _RecordingClient([httpx.ConnectError("boom")]), _fresh_cache(), LitellmUserRoles.PROXY_ADMIN + _ByUrl({CHANGELOG_FEED_URL: httpx.ConnectError("boom")}), _fresh_cache(), LitellmUserRoles.PROXY_ADMIN ) response = http_client.get("/get/latest_release_info") assert response.status_code == 200 assert response.json() is None + @pytest.mark.parametrize( + ("flag", "expected_body", "expected_urls"), + [ + ("true", None, []), + (" TRUE ", None, []), + ("false", EXPECTED_INFO, [CHANGELOG_FEED_URL, _tag_url("v1.102.0")]), + ], + ) + def test_disable_flag_skips_every_outbound_request( + self, http_client, monkeypatch, flag, expected_body, expected_urls + ): + monkeypatch.setenv("LITELLM_DISABLE_LATEST_RELEASE_CHECK", flag) + client = _minor_release() + _override_dependencies(client, _fresh_cache(), LitellmUserRoles.PROXY_ADMIN) + response = http_client.get("/get/latest_release_info") + assert response.status_code == 200 + assert response.json() == expected_body + assert client.urls == expected_urls + def test_repeated_requests_reuse_cache(self, http_client): - client = _RecordingClient([_github_response()]) + client = _minor_release() _override_dependencies(client, _fresh_cache(), LitellmUserRoles.PROXY_ADMIN) assert http_client.get("/get/latest_release_info").json() == EXPECTED_INFO assert http_client.get("/get/latest_release_info").json() == EXPECTED_INFO - assert len(client.calls) == 1 + assert len(client.calls) == 2 def test_rejects_unauthenticated_requests(self, monkeypatch): monkeypatch.setattr("litellm.proxy.proxy_server.master_key", MASTER_KEY) diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py index cdff03af3b4..ad069aa987b 100644 --- a/tests/unit/test_utils.py +++ b/tests/unit/test_utils.py @@ -90,7 +90,6 @@ from litellm.utils import ( get_llm_provider, get_optional_params_embeddings, ProviderConfigManager, - TextCompletionStreamWrapper, _check_provider_match, get_potential_model_names, _is_litellm_router_call, @@ -2528,41 +2527,6 @@ def test_priced_router_deployment_id_stays_out_of_wildcard_model_listing(): assert litellm.model_cost[deployment_id]["input_cost_per_token"] == 0.000001 -def test_reasoning_content_preserved_in_text_completion_wrapper(): - """Ensure reasoning_content is copied from delta to text_choices.""" - chunk = ModelResponseStream( - id="test-id", - created=1234567890, - model="test-model", - object="chat.completion.chunk", - choices=[ - StreamingChoices( - finish_reason=None, - index=0, - delta=Delta( - content="Some answer text", - role="assistant", - reasoning_content="Here's my chain of thought...", - ), - ) - ], - ) - - wrapper = TextCompletionStreamWrapper( - completion_stream=None, # Not used in convert_to_text_completion_object - model="test-model", - stream_options=None, - ) - - transformed = wrapper.convert_to_text_completion_object(chunk) - - assert "choices" in transformed - assert len(transformed["choices"]) == 1 - choice = transformed["choices"][0] - assert choice["text"] == "Some answer text" - assert choice["reasoning_content"] == "Here's my chain of thought..." - - def test_anthropic_claude_4_invoke_chat_provider_config(): """Test that the Anthropic Claude 4 Invoke chat provider config is correct.""" from litellm.llms.bedrock.chat.invoke_transformations.anthropic_claude3_transformation import ( diff --git a/tests/unit/text_completions/__init__.py b/tests/unit/text_completions/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/unit/text_completions/test_streaming_iterator.py b/tests/unit/text_completions/test_streaming_iterator.py new file mode 100644 index 00000000000..b7edffc0753 --- /dev/null +++ b/tests/unit/text_completions/test_streaming_iterator.py @@ -0,0 +1,144 @@ +from collections.abc import AsyncIterator, Iterator +from typing import Final + +import pytest + +from litellm.exceptions import APIConnectionError +from litellm.text_completions.streaming_iterator import TextCompletionStreamWrapper +from litellm.types.utils import Choices, Delta, ModelResponseStream, StreamingChoices, Usage + + +def test_reasoning_content_preserved_in_text_completion_wrapper(): + """Ensure reasoning_content is copied from delta to text_choices.""" + chunk = ModelResponseStream( + id="test-id", + created=1234567890, + model="test-model", + object="chat.completion.chunk", + choices=[ + StreamingChoices( + finish_reason=None, + index=0, + delta=Delta( + content="Some answer text", + role="assistant", + reasoning_content="Here's my chain of thought...", + ), + ) + ], + ) + + wrapper = TextCompletionStreamWrapper( + completion_stream=None, # Not used in convert_to_text_completion_object + model="test-model", + stream_options=None, + ) + + transformed = wrapper.convert_to_text_completion_object(chunk) + + assert "choices" in transformed + assert len(transformed["choices"]) == 1 + choice = transformed["choices"][0] + assert choice["text"] == "Some answer text" + assert choice["reasoning_content"] == "Here's my chain of thought..." + + +@pytest.mark.asyncio +@pytest.mark.parametrize("async_stream", (False, True)) +@pytest.mark.parametrize("empty_choices", (False, True)) +@pytest.mark.parametrize("stream_options", (None, {}, {"include_usage": False}, {"include_usage": True})) +@pytest.mark.parametrize("usage", (None, Usage(prompt_tokens=7, completion_tokens=2, total_tokens=9), Usage())) +async def test_text_completion_stream_usage_is_opt_in( + async_stream: bool, empty_choices: bool, stream_options: dict[str, bool] | None, usage: Usage | None +) -> None: + chunk: Final = ModelResponseStream( + id="test-id", + created=1234567890, + model="test-model", + choices=[] if empty_choices else [StreamingChoices(index=0, delta=Delta(content="Hello"))], + usage=usage, + ) + + async def chunks() -> AsyncIterator[ModelResponseStream]: + yield chunk + + wrapper: Final = TextCompletionStreamWrapper( + completion_stream=chunks() if async_stream else iter((chunk,)), + model="test-model", + stream_options=stream_options, + ) + responses: Final = [response async for response in wrapper] if async_stream else list(wrapper) + expected_usage: Final = ( + {"usage": usage.model_dump(exclude_none=True)} + if stream_options and stream_options.get("include_usage") is True and usage is not None + else {} + ) + assert [response.model_dump(exclude_none=True) for response in responses] == [ + { + "id": "test-id", + "object": "text_completion", + "created": 1234567890, + "model": "test-model", + "choices": [] if empty_choices else [{"index": 0, "text": "Hello"}], + **expected_usage, + } + ] + + +def test_text_completion_conversion_rejects_non_streaming_choices() -> None: + chunk: Final = Choices() + wrapper: Final = TextCompletionStreamWrapper(completion_stream=None, model="test-model") + + with pytest.raises(Exception, match="Error occurred converting to text completion object") as error: + wrapper.convert_to_text_completion_object(chunk) + + assert str(chunk) in str(error.value) + + +@pytest.mark.parametrize("chunk", (None, "None")) +def test_sync_text_completion_stream_rejects_invalid_chunks(chunk: str | None) -> None: + wrapper: Final = TextCompletionStreamWrapper( + completion_stream=iter((chunk,)), model="test-model", custom_llm_provider="openai" + ) + + with pytest.raises(APIConnectionError, match="OpenAIException") as error: + next(wrapper) + + assert (error.value.model, error.value.llm_provider) == ("test-model", "openai") + + +@pytest.mark.asyncio +@pytest.mark.parametrize("chunk", (None, "None")) +async def test_async_text_completion_stream_rejects_invalid_chunks(chunk: str | None) -> None: + async def chunks() -> AsyncIterator[str | None]: + yield chunk + + wrapper: Final = TextCompletionStreamWrapper(completion_stream=chunks(), model="test-model") + + with pytest.raises(Exception, match=r"^$") as error: + await anext(wrapper) + + assert not isinstance(error.value, StopAsyncIteration) + + +def test_sync_text_completion_stream_maps_upstream_failure_after_content() -> None: + chunk: Final = ModelResponseStream( + id="test-id", + created=1234567890, + model="test-model", + choices=[StreamingChoices(index=0, delta=Delta(content="Hello"))], + ) + + def chunks() -> Iterator[ModelResponseStream]: + yield chunk + raise RuntimeError("upstream disconnected") + + wrapper: Final = TextCompletionStreamWrapper( + completion_stream=chunks(), model="test-model", custom_llm_provider="openai" + ) + assert next(wrapper).choices[0].text == "Hello" + + with pytest.raises(APIConnectionError, match="upstream disconnected") as error: + next(wrapper) + + assert (error.value.model, error.value.llm_provider) == ("test-model", "openai") diff --git a/ui/litellm-dashboard/eslint-suppressions.json b/ui/litellm-dashboard/eslint-suppressions.json index 4802aa057c6..38d4c435e9a 100644 --- a/ui/litellm-dashboard/eslint-suppressions.json +++ b/ui/litellm-dashboard/eslint-suppressions.json @@ -1098,14 +1098,6 @@ "count": 1 } }, - "src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.tsx": { - "no-nested-ternary": { - "count": 1 - }, - "react-hooks/immutability": { - "count": 1 - } - }, "src/app/(dashboard)/usage/_components/components/UsagePageView.tsx": { "react-hooks/purity": { "count": 1 @@ -1767,16 +1759,16 @@ "count": 1 }, "max-params": { - "count": 15 + "count": 14 }, "no-nested-ternary": { "count": 5 }, "no-restricted-syntax": { - "count": 140 + "count": 139 }, "prefer-const": { - "count": 29 + "count": 28 } }, "src/components/object_permissions_view.tsx": { @@ -1798,9 +1790,6 @@ }, "prefer-const": { "count": 2 - }, - "react-hooks/set-state-in-effect": { - "count": 4 } }, "src/components/organization/organization_view.tsx": { diff --git a/ui/litellm-dashboard/package-lock.json b/ui/litellm-dashboard/package-lock.json index 944455721cd..add749c88cb 100644 --- a/ui/litellm-dashboard/package-lock.json +++ b/ui/litellm-dashboard/package-lock.json @@ -28,7 +28,7 @@ "jwt-decode": "4.0.0", "lucide-react": "0.513.0", "moment": "2.31.0", - "next": "16.3.8", + "next": "16.4.1", "next-themes": "^0.4.6", "nuqs": "^2.9.4", "openai": "6.49.0", @@ -69,8 +69,8 @@ "@types/react-copy-to-clipboard": "5.0.7", "@types/react-dom": "19.2.4", "@types/react-syntax-highlighter": "15.5.13", - "@vitest/coverage-v8": "4.1.11", - "@vitest/ui": "4.1.11", + "@vitest/coverage-v8": "4.1.12", + "@vitest/ui": "4.1.12", "eslint": "9.39.2", "eslint-config-next": "16.3.3", "eslint-config-prettier": "10.1.8", @@ -87,7 +87,7 @@ "typescript": "5.9.3", "typescript-eslint": "8.60.1", "vite": "7.3.7", - "vitest": "4.1.11" + "vitest": "4.1.12" }, "engines": { "node": ">=24.14.1", @@ -2153,9 +2153,9 @@ } }, "node_modules/@next/env": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/env/-/env-16.3.8.tgz", - "integrity": "sha512-Al9zqHVV7TJv0eFuOU4U7Lvv74PTih4Ch63sk2xCIpSTkE3udFnaOcnzP2lQVymiL7yS9Cj2iClUXlR3EQ5sEw==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/env/-/env-16.4.1.tgz", + "integrity": "sha512-5sUUrrSvs/2/2LnLoesybMGx12EtPB46fdZ6RhAw0XDGSPxU2LFyQBB7yuEiOFFJPKmBY6+q2jTr1/AMbnp0/g==", "license": "MIT" }, "node_modules/@next/eslint-plugin-next": { @@ -2170,9 +2170,9 @@ } }, "node_modules/@next/swc-darwin-arm64": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.3.8.tgz", - "integrity": "sha512-2JPRMh2nmQG5CiL7cXGL9AGwnPWJQ//cTtAUCT+w511QHk79SYz3LGv/pc5X643B/WEO0rvu3Yww0hqwt3kgeA==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.4.1.tgz", + "integrity": "sha512-U+hQ5Gj3fpzf4fveTIF3dpUFYhaSW8vHhdAnbiIomzXzg7boreYFgBqprepXFtW4sw+aTttiNmg0gew/iFNhbg==", "cpu": [ "arm64" ], @@ -2186,9 +2186,9 @@ } }, "node_modules/@next/swc-darwin-x64": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.3.8.tgz", - "integrity": "sha512-GZtCCOBKJ4leVIT/Th0llWKhD1ca92lzbQiS5R5ON9QkoiFnilFsebDae1JU2a3HWoKMEmEZWGs1AGLavVM72Q==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.4.1.tgz", + "integrity": "sha512-/hqC3V1XLUjhMASf/WridKdO9FXoEgN3HBWmtKbj00MPgnltutfraWJ3bYTpCRIgEIpbjJyOVLpYgAhh/BkdcQ==", "cpu": [ "x64" ], @@ -2202,9 +2202,9 @@ } }, "node_modules/@next/swc-linux-arm64-gnu": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.3.8.tgz", - "integrity": "sha512-O659ygeQYqneJ1fBKMpFxIFqYkYswu8IAS1OCKK/4f3ZgJJm1dRz4fVJZRi/kLLWjnBKnebOePA4WNv+sV1pVA==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.4.1.tgz", + "integrity": "sha512-GHzncHbcaS9g95kcvTNtKQW3aCLoR+xc3Jm7qrkpk1R+D2BjMHIPyvQGRPKCdMX95BsH/421jBUK06q9tEwzjw==", "cpu": [ "arm64" ], @@ -2221,9 +2221,9 @@ } }, "node_modules/@next/swc-linux-arm64-musl": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.3.8.tgz", - "integrity": "sha512-dSjKSyWpzxoO1d3DIZZcP4XJcNaKeLmxQMFOiYl5vuBRMmweIqnAhty8tAmRsvTss779cK1FtYnDMj40e4TQlg==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.4.1.tgz", + "integrity": "sha512-1SuJyDxW/PR9dHJat/ZRgcYLhuSZ+1psP4DlKb2tKIuXbjygqpLrJWRSq+onZQBv8LcmU67EIrmb6c3XTaJLjw==", "cpu": [ "arm64" ], @@ -2240,9 +2240,9 @@ } }, "node_modules/@next/swc-linux-x64-gnu": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.3.8.tgz", - "integrity": "sha512-lbqOuz3RPRcv+o9msNsJw5x4+Y1ZwPTs6vmL6DCf7i0fZfvng/F59wyeDwqHIvV0mK//RBy/jJkZ+nCKsSMXjQ==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.4.1.tgz", + "integrity": "sha512-Istng1hMGp9TGO4lUqeKLd70MPN/OOkucVTP2Nmj+gLkwBgmPqUw8CJYBCC7nbl/B/23bBCcjCI5Hsh6hazC1A==", "cpu": [ "x64" ], @@ -2259,9 +2259,9 @@ } }, "node_modules/@next/swc-linux-x64-musl": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.3.8.tgz", - "integrity": "sha512-+316WswI8ScVgZeUd+1KGaXkHhaYQzCjvH/05TZSpJ8zBizb1a4G7DtO7F12jcBIqMOtsz9ji1t48fmKtzqsGA==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.4.1.tgz", + "integrity": "sha512-aSC9wMNiZRRFVpPkPWBzRwLQxIGm/CiQcXyFF1XNcgodb+uMxdk7aSSGGpDXCbnvZdf4itjHxpOd5h7i7zaiYw==", "cpu": [ "x64" ], @@ -2278,9 +2278,9 @@ } }, "node_modules/@next/swc-win32-arm64-msvc": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.3.8.tgz", - "integrity": "sha512-ji0gd4kMYUxO+1fJBIbiBVRCjzG/lloiyCccnlebvb1ZJ5qXCPZqYg4Jl1DrrixnWNMKylzgpmMWx0yNDYXlzw==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.4.1.tgz", + "integrity": "sha512-t/myvwFDlypMUjRvbBf8qLPyuaB0iXYYdBtwMt6DM6f+60wtGr4bSYholdPqNeV5VUXZhrpMwfza829kmhS3iA==", "cpu": [ "arm64" ], @@ -2294,9 +2294,9 @@ } }, "node_modules/@next/swc-win32-x64-msvc": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.3.8.tgz", - "integrity": "sha512-WcTlaKt/TWkh5kUjdJcUmB1XgZ+1c6fz4Y9fDHL73YNSdGaUWjceeWrrlwF0nv19iABYWC4iAq1oX1w4Bn0vfg==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.4.1.tgz", + "integrity": "sha512-6ICqPo9awCkrtYNPhwkx1uU7rlFWrZRrIboDHS2LU+jv088UBYQtmJ25h6pCp27/+FZjF6BQ4Te4ErugyMeuBg==", "cpu": [ "x64" ], @@ -4490,14 +4490,14 @@ ] }, "node_modules/@vitest/coverage-v8": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.11.tgz", - "integrity": "sha512-8MVGEFnJIcdGjcbfKmeq8z0pZHH0JlVtoVZH9Q/qwUp6wyFnEJUBMrw9DCaj+ra3vShGmhavjalMIhPNxZAUcw==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.12.tgz", + "integrity": "sha512-6S7/iVknKglLAxMFxQGNppBI0iqJS2NgM6FBxavitj7KaDq/vywOWGf6dGu7F2L1Qy0G6S3uTp7aGshHrzK8JA==", "dev": true, "license": "MIT", "dependencies": { "@bcoe/v8-coverage": "^1.0.2", - "@vitest/utils": "4.1.11", + "@vitest/utils": "4.1.12", "ast-v8-to-istanbul": "^1.0.0", "istanbul-lib-coverage": "^3.2.2", "istanbul-lib-report": "^3.0.1", @@ -4511,8 +4511,8 @@ "url": "https://opencollective.com/vitest" }, "peerDependencies": { - "@vitest/browser": "4.1.11", - "vitest": "4.1.11" + "@vitest/browser": "4.1.12", + "vitest": "4.1.12" }, "peerDependenciesMeta": { "@vitest/browser": { @@ -4521,16 +4521,16 @@ } }, "node_modules/@vitest/expect": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz", - "integrity": "sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.12.tgz", + "integrity": "sha512-vFlTt+YEu9WBpNjdGayNmlMVzrWPi1+sv853/7t2FU7hpO5gAFBKHzQmkCq5Xjpr+evegF2994LQT3hF3mRlqQ==", "dev": true, "license": "MIT", "dependencies": { "@standard-schema/spec": "^1.1.0", "@types/chai": "^5.2.2", - "@vitest/spy": "4.1.11", - "@vitest/utils": "4.1.11", + "@vitest/spy": "4.1.12", + "@vitest/utils": "4.1.12", "chai": "^6.2.2", "tinyrainbow": "^3.1.0" }, @@ -4539,13 +4539,13 @@ } }, "node_modules/@vitest/mocker": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.11.tgz", - "integrity": "sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.12.tgz", + "integrity": "sha512-fKShNpKZzupWZuY0z7egydvL0sqW4INEZBEExMBMAa6izlENEVHwoXgdaTCaBZ5fwlr4xf2o1wXC83n9RpO+NA==", "dev": true, "license": "MIT", "dependencies": { - "@vitest/spy": "4.1.11", + "@vitest/spy": "4.1.12", "estree-walker": "^3.0.3", "magic-string": "^0.30.21" }, @@ -4566,9 +4566,9 @@ } }, "node_modules/@vitest/pretty-format": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz", - "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.12.tgz", + "integrity": "sha512-XW9O8+Mxx4VpCtkYdMJLZQQwsVryP9wk7cPKDxtXFfwSak6yRh5+2fep/Y0XF/ElBvJHq8bcYdi6aeuai0opZA==", "dev": true, "license": "MIT", "dependencies": { @@ -4579,13 +4579,13 @@ } }, "node_modules/@vitest/runner": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz", - "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.12.tgz", + "integrity": "sha512-NKlVKCr5QnCe8jijdMnmkpHHU+WTqiLFR6G0pHji9uRjXK9xJl1k1nTw6F3pOOj2PDcsDt2GKQMI7wIsaT491w==", "dev": true, "license": "MIT", "dependencies": { - "@vitest/utils": "4.1.11", + "@vitest/utils": "4.1.12", "pathe": "^2.0.3" }, "funding": { @@ -4593,14 +4593,14 @@ } }, "node_modules/@vitest/snapshot": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz", - "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.12.tgz", + "integrity": "sha512-ko1y1Qgb/slzQ9mr+b89Cuqud8WG1TKtsPD8r7ZUBdvVOGt85Af2HwCqHujrhwJq95hs/9RM7fcAPg57o1vlzw==", "dev": true, "license": "MIT", "dependencies": { - "@vitest/pretty-format": "4.1.11", - "@vitest/utils": "4.1.11", + "@vitest/pretty-format": "4.1.12", + "@vitest/utils": "4.1.12", "magic-string": "^0.30.21", "pathe": "^2.0.3" }, @@ -4609,9 +4609,9 @@ } }, "node_modules/@vitest/spy": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.11.tgz", - "integrity": "sha512-apNa/prQy2qCeywhnixOHPRCgGNhvg7T4Dapfl1GahLp/R+uhBm5cPyFoNVyqsNd2h1nJxL6BqqdIjiABL60YA==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.12.tgz", + "integrity": "sha512-RGq9x4JNGNTZHEJxvN0oSiJjeSCExm0n2gZKKJZHY9cX5AVA6M7VJILBT3ZJ/tJ/0J9uWT7fETV9/btoi//vSg==", "dev": true, "license": "MIT", "funding": { @@ -4619,13 +4619,13 @@ } }, "node_modules/@vitest/ui": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.1.11.tgz", - "integrity": "sha512-r/rwyKoev21mWdRGSEkZOqkQ2BYy68mwjihg9M90nNRbf4NGrgzZ4cj6JNCEwlOGJkbKeMgsjlykvwKUbRr7gw==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.1.12.tgz", + "integrity": "sha512-eYUTHtsp52Fu6YGUw9T9173bba7YUr9j/Xj9CdhUaOb8AppLKcknHUaiZQeqJ8MiJ8C2VyKiZuUGSKdvPIKQKA==", "dev": true, "license": "MIT", "dependencies": { - "@vitest/utils": "4.1.11", + "@vitest/utils": "4.1.12", "fflate": "^0.8.2", "flatted": "^3.4.2", "pathe": "^2.0.3", @@ -4637,17 +4637,17 @@ "url": "https://opencollective.com/vitest" }, "peerDependencies": { - "vitest": "4.1.11" + "vitest": "4.1.12" } }, "node_modules/@vitest/utils": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz", - "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.12.tgz", + "integrity": "sha512-Q3awXrwOfEV+qc3WmO5ONyE0yO7Q1gQ9/oyHxGLZ/pl7N3NO/ZztqQwKLuwMkV+CA1JYSIeO3gkHnRDIo4AVaA==", "dev": true, "license": "MIT", "dependencies": { - "@vitest/pretty-format": "4.1.11", + "@vitest/pretty-format": "4.1.12", "convert-source-map": "^2.0.0", "tinyrainbow": "^3.1.0" }, @@ -9710,12 +9710,12 @@ "license": "MIT" }, "node_modules/next": { - "version": "16.3.8", - "resolved": "https://registry.npmjs.org/next/-/next-16.3.8.tgz", - "integrity": "sha512-U7QEZaTini6wKrb8A8hqLLqYQyCetegKjCpJOyxk642vWoMoU1x5PyZCJFvgYgiptA8xc5j/9xYlZFO7w9Sjmw==", + "version": "16.4.1", + "resolved": "https://registry.npmjs.org/next/-/next-16.4.1.tgz", + "integrity": "sha512-uc657V62E34fOI6W5NtG9IzwsPcms0Z60grz2MJGtglgD+pTFnNt4Yw2PzaU622tfX4vhrDgLZzicE2YlhI20Q==", "license": "MIT", "dependencies": { - "@next/env": "16.3.8", + "@next/env": "16.4.1", "@swc/helpers": "0.5.23", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", @@ -9729,15 +9729,15 @@ "node": ">=20.9.0" }, "optionalDependencies": { - "@next/swc-darwin-arm64": "16.3.8", - "@next/swc-darwin-x64": "16.3.8", - "@next/swc-linux-arm64-gnu": "16.3.8", - "@next/swc-linux-arm64-musl": "16.3.8", - "@next/swc-linux-x64-gnu": "16.3.8", - "@next/swc-linux-x64-musl": "16.3.8", - "@next/swc-win32-arm64-msvc": "16.3.8", - "@next/swc-win32-x64-msvc": "16.3.8", - "sharp": "^0.35.4" + "@next/swc-darwin-arm64": "16.4.1", + "@next/swc-darwin-x64": "16.4.1", + "@next/swc-linux-arm64-gnu": "16.4.1", + "@next/swc-linux-arm64-musl": "16.4.1", + "@next/swc-linux-x64-gnu": "16.4.1", + "@next/swc-linux-x64-musl": "16.4.1", + "@next/swc-win32-arm64-msvc": "16.4.1", + "@next/swc-win32-x64-msvc": "16.4.1", + "sharp": "^0.35.5" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", @@ -12512,19 +12512,19 @@ } }, "node_modules/vitest": { - "version": "4.1.11", - "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz", - "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==", + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.12.tgz", + "integrity": "sha512-5eWdz2yb3ajxWF3C8C4TjkXl7FGm3n2E/VlazALrQHzK7nYMSGFnCZto0bbPNl77AwkOZVLk0YnBAejUu0NiWA==", "dev": true, "license": "MIT", "dependencies": { - "@vitest/expect": "4.1.11", - "@vitest/mocker": "4.1.11", - "@vitest/pretty-format": "4.1.11", - "@vitest/runner": "4.1.11", - "@vitest/snapshot": "4.1.11", - "@vitest/spy": "4.1.11", - "@vitest/utils": "4.1.11", + "@vitest/expect": "4.1.12", + "@vitest/mocker": "4.1.12", + "@vitest/pretty-format": "4.1.12", + "@vitest/runner": "4.1.12", + "@vitest/snapshot": "4.1.12", + "@vitest/spy": "4.1.12", + "@vitest/utils": "4.1.12", "es-module-lexer": "^2.0.0", "expect-type": "^1.3.0", "magic-string": "^0.30.21", @@ -12552,12 +12552,12 @@ "@edge-runtime/vm": "*", "@opentelemetry/api": "^1.9.0", "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0", - "@vitest/browser-playwright": "4.1.11", - "@vitest/browser-preview": "4.1.11", - "@vitest/browser-webdriverio": "4.1.11", - "@vitest/coverage-istanbul": "4.1.11", - "@vitest/coverage-v8": "4.1.11", - "@vitest/ui": "4.1.11", + "@vitest/browser-playwright": "4.1.12", + "@vitest/browser-preview": "4.1.12", + "@vitest/browser-webdriverio": "^4.1.11", + "@vitest/coverage-istanbul": "4.1.12", + "@vitest/coverage-v8": "4.1.12", + "@vitest/ui": "4.1.12", "happy-dom": "*", "jsdom": "*", "vite": "^6.0.0 || ^7.0.0 || ^8.0.0" diff --git a/ui/litellm-dashboard/package.json b/ui/litellm-dashboard/package.json index f2a1a5e4e7f..8160836515f 100644 --- a/ui/litellm-dashboard/package.json +++ b/ui/litellm-dashboard/package.json @@ -45,7 +45,7 @@ "jwt-decode": "4.0.0", "lucide-react": "0.513.0", "moment": "2.31.0", - "next": "16.3.8", + "next": "16.4.1", "next-themes": "^0.4.6", "nuqs": "^2.9.4", "openai": "6.49.0", @@ -86,8 +86,8 @@ "@types/react-copy-to-clipboard": "5.0.7", "@types/react-dom": "19.2.4", "@types/react-syntax-highlighter": "15.5.13", - "@vitest/coverage-v8": "4.1.11", - "@vitest/ui": "4.1.11", + "@vitest/coverage-v8": "4.1.12", + "@vitest/ui": "4.1.12", "eslint": "9.39.2", "eslint-config-next": "16.3.3", "eslint-config-prettier": "10.1.8", @@ -104,7 +104,7 @@ "typescript": "5.9.3", "typescript-eslint": "8.60.1", "vite": "7.3.7", - "vitest": "4.1.11" + "vitest": "4.1.12" }, "overrides": { "prismjs": "1.30.0", @@ -117,7 +117,10 @@ "axios": "1.13.6", "postcss": "8.5.23", "esbuild": "0.28.1", - "sharp": "^0.35.5" + "sharp": "^0.35.5", + "@litellm/lens-ui": { + "next": "$next" + } }, "engines": { "node": ">=24.14.1", diff --git a/ui/litellm-dashboard/public/assets/aria-agent.png b/ui/litellm-dashboard/public/assets/aria-agent.png new file mode 100644 index 00000000000..870773933e3 Binary files /dev/null and b/ui/litellm-dashboard/public/assets/aria-agent.png differ diff --git a/ui/litellm-dashboard/public/assets/logos/claude.svg b/ui/litellm-dashboard/public/assets/logos/claude.svg new file mode 100644 index 00000000000..ede30652b25 --- /dev/null +++ b/ui/litellm-dashboard/public/assets/logos/claude.svg @@ -0,0 +1,27 @@ + +Claude diff --git a/ui/litellm-dashboard/src/app/(dashboard)/home/_components/HomePage.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/home/_components/HomePage.integration.test.tsx index b957393be64..edde511d1cd 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/home/_components/HomePage.integration.test.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/home/_components/HomePage.integration.test.tsx @@ -141,7 +141,7 @@ describe("HomePage", () => { expect(screen.queryByRole("link", { name: /create new virtual key/i })).not.toBeInTheDocument(); }); - it("offers LiteAdmin on Home inside the dashboard frame", async () => { + it("should offer Aria Agent on Home inside the dashboard frame", async () => { render( @@ -149,7 +149,7 @@ describe("HomePage", () => { , ); - const entry = screen.getByRole("region", { name: "Ask LiteAdmin" }); + const entry = screen.getByRole("region", { name: "Ask Aria Agent" }); expect(await within(entry).findByPlaceholderText("What would you like to do?")).toBeInTheDocument(); expect(within(entry).getByRole("button", { name: "Send message" })).toBeDisabled(); expect(await screen.findByText("$501.74")).toBeInTheDocument(); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsagePanel.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsagePanel.integration.test.tsx new file mode 100644 index 00000000000..0fff919de4d --- /dev/null +++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsagePanel.integration.test.tsx @@ -0,0 +1,407 @@ +import { useState, type ComponentProps } from "react"; +import userEvent from "@testing-library/user-event"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { uiSpendLogsCall, userListCall, dailyActivityExportCall, type UserInfo } from "@/components/networking"; +import type { DailyData, SpendMetrics } from "@/components/UsagePage/types"; +import { + chooseSelectOption, + renderWithProviders, + screen, + testQueryClient, + waitFor, + within, +} from "../../../../../../tests/test-utils"; +import ClientUsagePanel from "./ClientUsagePanel"; +import { UsageClient, type AgentRow } from "./overview/agentCatalog"; + +vi.mock("@/components/networking", async (importOriginal) => ({ + ...(await importOriginal()), + uiSpendLogsCall: vi.fn(), + dailyActivityExportCall: vi.fn(), + userListCall: vi.fn(), +})); + +const desktopTag = "User-Agent: claude-cli/2.1.263 (external, claude-desktop-3p)"; +const agent: AgentRow = { + id: "claude-desktop", + label: "Claude Desktop", + description: "Desktop assistant", + kind: "agent", + logo: null, + spend: 12.5, + tokens: 9000, + requests: 3, + users: 2, + tags: [desktopTag], +}; +const metrics: SpendMetrics = { + spend: 12.5, + total_tokens: 9000, + prompt_tokens: 8000, + completion_tokens: 1000, + cache_read_input_tokens: 5000, + cache_creation_input_tokens: 1000, + api_requests: 3, + successful_requests: 3, + failed_requests: 0, +}; +const daily: DailyData[] = [ + { + date: "2026-10-22", + metrics, + breakdown: { + models: {}, + model_groups: {}, + providers: {}, + api_keys: {}, + mcp_servers: {}, + entities: { [desktopTag]: { metrics, metadata: {}, api_key_breakdown: {} } }, + }, + }, +]; +const defaultProps: ComponentProps = { + client: UsageClient.ClaudeDesktop, + userId: null, + canChooseUser: true, + onUserChange: vi.fn(), + onClose: vi.fn(), + accessToken: "test-token", + startTime: new Date("2026-10-22T00:00:00Z"), + endTime: new Date("2026-10-22T23:59:59.999Z"), + dateValue: { from: new Date("2026-10-22T00:00:00Z"), to: new Date("2026-10-22T23:59:59.999Z") }, + presetShortLabel: null, + onDateChange: vi.fn(), + agent, + daily: [], + loading: false, +}; +const personLog = { + request_id: "request-1", + user: "person-1", + startTime: "2026-10-22T12:00:00Z", + model: "test-model", + spend: 3, + total_tokens: 1000, + prompt_tokens: 800, + completion_tokens: 200, + status: "success", + request_tags: [desktopTag], + metadata: {}, +}; +const person: UserInfo = { + user_id: "person-1", + user_email: "person@example.com", + user_alias: null, + allowed_cache_controls: [], + key_count: 0, + model_max_budget: {}, + model_spend: {}, + models: [], + policies: [], + spend: 0, + teams: [], +}; + +describe("ClientUsagePanel", () => { + beforeEach(() => { + testQueryClient.clear(); + vi.clearAllMocks(); + vi.stubGlobal("requestIdleCallback", (callback: IdleRequestCallback) => { + callback({ didTimeout: false, timeRemaining: () => 50 }); + return 1; + }); + const userPage = { + users: [person], + total: 1, + page: 1, + page_size: 50, + total_pages: 1, + }; + const requestPage = { + data: [personLog], + total: 1, + page: 1, + total_pages: 1, + total_is_capped: false, + }; + const exportedRows = [ + { + date: "2026-10-22", + entity_id: desktopTag, + model: "test-model", + spend: 12.5, + flat_cost: 0, + prompt_tokens: 8000, + completion_tokens: 1000, + api_requests: 3, + successful_requests: 3, + failed_requests: 0, + cache_read_input_tokens: 5000, + cache_creation_input_tokens: 1000, + }, + ]; + vi.mocked(dailyActivityExportCall).mockResolvedValue( + Object.assign(new Blob([JSON.stringify(exportedRows)], { type: "application/json" }), { + text: async () => JSON.stringify(exportedRows), + }), + ); + vi.mocked(userListCall).mockResolvedValue(userPage); + vi.mocked(uiSpendLogsCall).mockResolvedValue(requestPage); + }); + + afterEach(() => vi.unstubAllGlobals()); + + it("should immediately show the clicked all-users summary and logo without requiring a person", () => { + renderWithProviders(); + + const panel = screen.getByRole("dialog", { name: "Claude Desktop" }); + expect(within(panel).getByRole("img", { name: "Claude Desktop logo" })).toBeInTheDocument(); + expect(panel).toHaveTextContent("All users"); + expect(panel).toHaveTextContent(/Spend\s*\$12\.50/); + expect(panel).toHaveTextContent(/Total tokens\s*9K/); + expect(panel).toHaveTextContent(/Requests\s*3/); + expect(screen.queryByRole("status", { name: "Loading client usage" })).not.toBeInTheDocument(); + expect(screen.queryByText(/Select a user to/)).not.toBeInTheDocument(); + expect(uiSpendLogsCall).not.toHaveBeenCalled(); + }); + + it("should filter to a person inside the open panel and keep absent cache details unavailable", async () => { + const user = userEvent.setup(); + const onUserChange = vi.fn(); + const onClose = vi.fn(); + function ControlledPanel() { + const [userId, setUserId] = useState(null); + return ( + { + setUserId(id); + onUserChange(id); + }} + /> + ); + } + renderWithProviders(); + + await chooseSelectOption(user, screen.getByRole("combobox", { name: "Filter by person" }), /person@example.com/); + expect(onUserChange).toHaveBeenCalledWith("person-1"); + expect(onClose).not.toHaveBeenCalled(); + await waitFor(() => + expect(uiSpendLogsCall).toHaveBeenCalledWith( + expect.objectContaining({ + params: expect.objectContaining({ user_id: "person-1" }), + }), + ), + ); + const panel = screen.getByRole("dialog", { name: "Claude Desktop" }); + await waitFor(() => expect(panel).toHaveTextContent(/Spend\s*\$3\.00/)); + expect(panel).toHaveTextContent("Selected user"); + expect(panel).toHaveTextContent(/Cache reads\s*Unavailable/); + expect(panel).toHaveTextContent(/Cache writes\s*Unavailable/); + expect(panel).toHaveTextContent(/Uncached input\s*Unavailable/); + expect(panel).toHaveTextContent(/Output\s*200/); + + await user.click(screen.getByRole("button", { name: "All users" })); + expect(onUserChange).toHaveBeenLastCalledWith(null); + expect(onClose).not.toHaveBeenCalled(); + expect(screen.getByRole("dialog", { name: "Claude Desktop" })).toHaveTextContent(/Spend\s*\$12\.50/); + }); + + it.each(["Back to Usage", "Close"])("should return to the overview through %s", async (button) => { + const user = userEvent.setup(); + const onClose = vi.fn(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: button })); + expect(onClose).toHaveBeenCalledOnce(); + }); + + it("should preserve summary totals and mark partial model details unavailable", async () => { + const partialAgent = { ...agent, spend: 25, tokens: 18000, requests: 6 }; + renderWithProviders(); + + const panel = screen.getByRole("dialog", { name: "Claude Desktop" }); + expect(panel).toHaveTextContent(/Spend\s*\$25\.00/); + expect(within(panel).getAllByText("Unavailable")).toHaveLength(4); + expect(await screen.findByText(/Model usage does not match these client totals yet/)).toBeInTheDocument(); + expect(screen.queryByRole("heading", { name: "Daily usage" })).not.toBeInTheDocument(); + expect(screen.queryByText("5,000")).not.toBeInTheDocument(); + }); + + it("should not expose a cached all-users summary without a permitted user scope", () => { + renderWithProviders(); + + expect(screen.getByRole("alert")).toHaveTextContent("Sign in to view your client usage"); + expect(screen.queryByText("$12.50")).not.toBeInTheDocument(); + expect(screen.queryByText("Total tokens")).not.toBeInTheDocument(); + expect(screen.queryByRole("combobox", { name: "Filter by person" })).not.toBeInTheDocument(); + expect(screen.queryByRole("heading", { name: "Daily usage" })).not.toBeInTheDocument(); + expect(uiSpendLogsCall).not.toHaveBeenCalled(); + expect(screen.queryByRole("button", { name: "Try again" })).not.toBeInTheDocument(); + }); + + it("should show a failed summary as an error and retry without closing or showing stale totals", async () => { + const user = userEvent.setup(); + const onRetry = vi.fn(); + const onClose = vi.fn(); + renderWithProviders(); + + expect(screen.getByRole("alert")).toHaveTextContent("Could not load client totals"); + expect(screen.queryByText("$12.50")).not.toBeInTheDocument(); + expect(screen.queryByText("No Claude Desktop usage recorded in this date range.")).not.toBeInTheDocument(); + await user.click(screen.getByRole("button", { name: "Try again" })); + expect(onRetry).toHaveBeenCalledOnce(); + expect(onClose).not.toHaveBeenCalled(); + }); + it("should change the panel time range through the existing picker without closing", async () => { + const user = userEvent.setup(); + const onDateChange = vi.fn(); + const onClose = vi.fn(); + renderWithProviders(); + await user.click(screen.getByRole("button", { name: /22 Oct/ })); + await user.click(screen.getByRole("button", { name: /Last 7 days/ })); + await user.click(screen.getByRole("button", { name: "Apply" })); + expect(onDateChange).toHaveBeenCalledWith( + expect.objectContaining({ from: expect.any(Date), to: expect.any(Date) }), + "7d", + ); + expect(onClose).not.toHaveBeenCalled(); + expect(screen.getByRole("dialog", { name: "Claude Desktop" })).toBeInTheDocument(); + }); + + it("should show the client model breakdown using the overview controls", async () => { + renderWithProviders(); + expect(await screen.findByText("test-model")).toBeInTheDocument(); + expect(screen.getByRole("heading", { name: "Daily usage" })).toBeInTheDocument(); + expect(screen.getByRole("radiogroup", { name: "Metric" })).toBeInTheDocument(); + expect(screen.getByRole("radio", { name: "Tokens" })).toBeInTheDocument(); + expect(screen.getByRole("radio", { name: "Weekly" })).toBeInTheDocument(); + }); + + it("should show personal client usage without loading the global user list or all-user export", async () => { + renderWithProviders(); + + const panel = screen.getByRole("dialog", { name: "Claude Desktop" }); + await waitFor(() => expect(panel).toHaveTextContent(/Spend\s*\$3\.00/)); + expect(panel).toHaveTextContent("My usage"); + expect(screen.queryByRole("combobox", { name: "Filter by person" })).not.toBeInTheDocument(); + expect(userListCall).not.toHaveBeenCalled(); + expect(dailyActivityExportCall).not.toHaveBeenCalled(); + expect(uiSpendLogsCall).toHaveBeenCalledWith( + expect.objectContaining({ params: expect.objectContaining({ user_id: "person-1" }) }), + ); + expect(vi.mocked(uiSpendLogsCall).mock.lastCall?.[0].params).not.toHaveProperty("team_id"); + }); + + it("should keep team and member filters intersected inside the open panel without fetching global users", async () => { + const user = userEvent.setup(); + const onClose = vi.fn(); + const onTeamChange = vi.fn(); + const onUserChange = vi.fn(); + const teamOptions = [{ value: "engineering", label: "Engineering" }]; + const memberOptions = [ + { value: "person-1", label: "John" }, + { value: "person-2", label: "Maya" }, + ]; + const johnLog = { ...personLog, team_id: "engineering" }; + const mayaLog = { ...johnLog, request_id: "request-2", user: "person-2", spend: 7 }; + vi.mocked(uiSpendLogsCall).mockImplementation(async (request) => { + const logs = [johnLog, mayaLog].filter((log) => !request.params?.user_id || log.user === request.params.user_id); + return { data: logs, total: logs.length, page: 1, total_pages: 1, total_is_capped: false }; + }); + function TeamPanel() { + const [teamId, setTeamId] = useState(null); + const [userId, setUserId] = useState("person-1"); + const changeTeam = (id: string | null) => { + setTeamId(id); + setUserId(id ? null : "person-1"); + onTeamChange(id); + }; + return ( + { + setUserId(id); + onUserChange(id); + }} + /> + ); + } + renderWithProviders(); + + await chooseSelectOption(user, screen.getByRole("combobox", { name: "Usage scope" }), "Engineering"); + expect(onTeamChange).toHaveBeenCalledWith("engineering"); + const panel = screen.getByRole("dialog", { name: "Claude Desktop" }); + await waitFor(() => expect(panel).toHaveTextContent(/Spend\s*\$10\.00/)); + expect(panel).toHaveTextContent("Engineering · All members"); + expect(uiSpendLogsCall).toHaveBeenLastCalledWith( + expect.objectContaining({ params: expect.objectContaining({ team_id: "engineering" }) }), + ); + expect(vi.mocked(uiSpendLogsCall).mock.lastCall?.[0].params).not.toHaveProperty("user_id"); + + await user.click(screen.getByRole("combobox", { name: "Team member" })); + expect(await screen.findByRole("option", { name: "Maya" })).toBeInTheDocument(); + expect(screen.getByRole("option", { name: "John" })).toBeInTheDocument(); + expect(screen.queryByRole("option", { name: "Outside user" })).not.toBeInTheDocument(); + await user.click(screen.getByRole("option", { name: "Maya" })); + expect(onUserChange).toHaveBeenCalledWith("person-2"); + await waitFor(() => expect(panel).toHaveTextContent(/Spend\s*\$7\.00/)); + expect(panel).toHaveTextContent("Engineering · Maya"); + expect(uiSpendLogsCall).toHaveBeenLastCalledWith( + expect.objectContaining({ params: expect.objectContaining({ team_id: "engineering", user_id: "person-2" }) }), + ); + + await chooseSelectOption(user, screen.getByRole("combobox", { name: "Team member" }), "All members"); + expect(onUserChange).toHaveBeenLastCalledWith(null); + await waitFor(() => expect(panel).toHaveTextContent(/Spend\s*\$10\.00/)); + expect(onClose).not.toHaveBeenCalled(); + expect(userListCall).not.toHaveBeenCalled(); + expect(dailyActivityExportCall).not.toHaveBeenCalled(); + }); + + it.each([ + [null, "Choose an administered team before viewing another member's usage"], + ["engineering", "Choose a member of the selected team"], + ])("should block requests and cached summaries for an invalid scope in team %s", (teamId, scopeError) => { + renderWithProviders( + , + ); + + expect(screen.getByRole("alert")).toHaveTextContent(scopeError); + expect(screen.queryByText("$12.50")).not.toBeInTheDocument(); + expect(screen.queryByText("Total tokens")).not.toBeInTheDocument(); + expect(screen.queryByRole("heading", { name: "Daily usage" })).not.toBeInTheDocument(); + expect(uiSpendLogsCall).not.toHaveBeenCalled(); + expect(dailyActivityExportCall).not.toHaveBeenCalled(); + expect(userListCall).not.toHaveBeenCalled(); + }); + it("should recover a newer model export by refreshing the cached summary on retry", async () => { + const user = userEvent.setup(); + function StaleSummaryPanel() { + const [summary, setSummary] = useState({ ...agent, spend: 12 }); + return setSummary(agent)} />; + } + renderWithProviders(); + expect(await screen.findByText(/Model usage does not match these client totals/)).toBeInTheDocument(); + await user.click(screen.getByRole("button", { name: "Retry model breakdown" })); + expect(await screen.findByText("test-model")).toBeInTheDocument(); + }); +}); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsagePanel.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsagePanel.tsx new file mode 100644 index 00000000000..3ca8f2e038d --- /dev/null +++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsagePanel.tsx @@ -0,0 +1,362 @@ +"use client"; + +import { useMemo } from "react"; +import { ArrowLeft, Coins } from "lucide-react"; +import { useTagSummary } from "@/app/(dashboard)/hooks/tags/useTagSummary"; +import AdvancedDatePicker from "@/components/shared/advanced_date_picker"; +import type { DateRangePickerValue } from "@/components/shared/date_picker_types"; +import UserDropdown from "@/components/common_components/UserDropdown"; +import { SearchSelect } from "@/components/shared/SearchSelect"; +import type { ClientUsageScopeOption } from "../hooks/clientUsageScope"; +import { stackedUsageColor } from "@/components/shared/charts"; +import { Button } from "@/components/ui/button"; +import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "@/components/ui/sheet"; +import { Skeleton } from "@/components/ui/skeleton"; +import { EMPTY_DAILY_ACTIVITY_METADATA, toDailyData } from "@/components/UsagePage/dailyActivityApi"; +import type { DailyData } from "@/components/UsagePage/types"; +import claudeLogo from "../../../../../../public/assets/logos/claude.svg"; +import type { UsageClient } from "../hooks/clientUsageData"; +import { useClientUsage } from "../hooks/useClientUsage"; +import { topAgents, type AgentRow } from "./overview/agentCatalog"; +import { useClientAgentModels } from "../hooks/useClientAgentModels"; +import UsageBreakdownChart from "./overview/UsageBreakdownChart"; +import { clientAgentDetail, type ClientAgentDetail } from "./overview/clientAgentDetail"; +import { modelColorMap, formatCompact, formatUsd, overviewTotals } from "./overview/overviewData"; +import { reconciledTokenBreakdown } from "./overview/tokenBreakdown"; +import { Panel, Stat } from "./overview/Primitives"; +import { AgentMark } from "./overview/TopAgents"; + +interface ClientUsagePanelProps { + client: UsageClient; + userId: string | null; + canChooseUser: boolean; + teamId?: string | null; + scopeError?: string | null; + teams?: readonly ClientUsageScopeOption[]; + members?: readonly ClientUsageScopeOption[]; + defaultScopeLabel?: string; + onTeamChange?: (teamId: string | null) => void; + onUserChange: (userId: string | null) => void; + onClose: () => void; + accessToken: string | null; + startTime: Date | null; + endTime: Date | null; + dateValue: DateRangePickerValue; + presetShortLabel: string | null; + onDateChange: (value: DateRangePickerValue, preset: string | null) => void; + colorSource?: readonly DailyData[]; + agent: AgentRow | null; + daily: readonly DailyData[]; + loading: boolean; + summaryFailed?: boolean; + onRetry?: () => void; +} + +const dateLabel = (date: Date | null) => date?.toLocaleDateString("en-US", { month: "short", day: "numeric" }) ?? "—"; +const countLabel = (value: number | null) => (value === null ? "Unavailable" : value.toLocaleString()); + +export default function ClientUsagePanel({ + client, + userId, + canChooseUser, + teamId = null, + scopeError: accessError = null, + teams = [], + members = [], + defaultScopeLabel = "All users", + onTeamChange, + onUserChange, + onClose, + accessToken, + startTime, + endTime, + dateValue, + presetShortLabel, + onDateChange, + colorSource, + agent, + daily, + loading, + summaryFailed = false, + onRetry, +}: ClientUsagePanelProps) { + const label = client === "claude-desktop" ? "Claude Desktop" : "Claude Code"; + const scopedRequest = Boolean(userId || teamId) && !accessError; + const personRequest = { + accessToken, + startTime, + endTime, + userId, + teamId, + client: scopedRequest ? client : null, + }; + const personUsage = useClientUsage(personRequest); + const allUsersEnabled = canChooseUser && !scopedRequest && !accessError; + const teamLabel = teams.find((team) => team.value === teamId)?.label ?? teamId; + const personLabel = members.find((member) => member.value === userId)?.label ?? "Selected user"; + const selectedScopeLabel = (() => { + if (teamId) return `${teamLabel} · ${userId ? personLabel : "All members"}`; + if (!canChooseUser) return "My usage"; + return userId ? "Selected user" : "All users"; + })(); + const summaryQuery = useTagSummary(startTime, endTime, allUsersEnabled && agent === null); + const activeAgent = useMemo( + () => agent ?? topAgents(summaryQuery.data ?? []).find((row) => row.id === client) ?? null, + [summaryQuery.data, agent, client], + ); + const modelRequest = { accessToken, startTime, endTime, agent: activeAgent, enabled: allUsersEnabled }; + const agentModels = useClientAgentModels(modelRequest); + const agentDaily = agentModels.results.length > 0 ? agentModels.results : daily; + const agentDetail = useMemo( + () => (activeAgent ? clientAgentDetail(activeAgent, agentDaily) : null), + [activeAgent, agentDaily], + ); + const colorByModel = useMemo(() => (colorSource ? modelColorMap(colorSource) : undefined), [colorSource]); + const personTotals = overviewTotals(personUsage.data.metadata ?? EMPTY_DAILY_ACTIVITY_METADATA, null); + const pending = + !accessError && (scopedRequest ? personUsage.loading : (loading || summaryQuery.isLoading) && activeAgent === null); + const summaryError = summaryQuery.isError || summaryFailed ? "Could not load client totals" : null; + const scopeError = + accessError ?? (!canChooseUser && !scopedRequest ? "Sign in to view your client usage" : summaryError); + const error = accessError ?? (scopedRequest ? personUsage.error : scopeError); + const summary = scopedRequest ? personTotals : agentDetail?.summary; + const rawBreakdown = scopedRequest + ? { + inputTokens: personTotals.inputTokens, + outputTokens: personTotals.outputTokens, + cacheReadTokens: personUsage.cacheAvailable ? personTotals.cacheReadTokens : null, + cacheWriteTokens: personUsage.cacheAvailable ? personTotals.cacheWriteTokens : null, + } + : agentDetail?.tokenBreakdown; + const breakdown = rawBreakdown && summary ? reconciledTokenBreakdown(summary.tokens, rawBreakdown) : undefined; + const modelResults = scopedRequest ? toDailyData(personUsage.data) : agentModels.results; + const chartLoading = scopedRequest ? personUsage.loading : agentModels.loading; + const chartError = scopedRequest ? personUsage.error : agentModels.error; + + const canFilterPerson = canChooseUser && !teamId && !accessError; + const canRetry = !accessError && (scopedRequest || canChooseUser); + const ready = !pending && !error; + const retryModels = () => { + void summaryQuery.refetch(); + onRetry?.(); + agentModels.reload(); + }; + + return ( + { + if (!open) onClose(); + }} + > + + + +
+ +
+ {label} + + {dateLabel(startTime)} – {dateLabel(endTime)} · {selectedScopeLabel} + +
+
+ +
+
+ +
+ {teams.length > 0 && onTeamChange && ( +
+ + ({ ...team, value: `team:${team.value}` })), + ]} + allowClear={false} + onValueChange={(value) => onTeamChange(value?.startsWith("team:") ? value.slice(5) : null)} + /> +
+ )} + {teamId && ( +
+ + ({ ...member, value: `user:${member.value}` })), + ]} + allowClear={false} + onValueChange={(value) => onUserChange(value?.startsWith("user:") ? value.slice(5) : null)} + /> +
+ )} + {canFilterPerson && ( +
+
+ + {userId && ( + + )} +
+ +
+ )} + {pending && ( +
+ +
+ )} + {error && ( +
+

Could not load client usage

+

{error}

+ {canRetry && ( + + )} +
+ )} + {ready && !summary && ( +

No {label} usage recorded in this date range.

+ )} + {ready && summary && ( + <> +
+ + + +
+ {summary.requests === 0 ? ( +

+ No {label} requests in the selected range. Try another date range. + {(canChooseUser || teamId) && " You can also choose another person."} +

+ ) : ( + <> + {!chartError && ( + + )} + {chartError && ( +
+

+ {chartError} +

+ +
+ )} + {breakdown && } + + )} +

+ {scopedRequest + ? "Based on retained request logs within the exact selected time range." + : "All-user totals use UTC daily aggregates for the selected dates. Filtering by person uses the exact selected times. Cache values are reported counts."}{" "} + Spend is the cost recorded by LiteLLM. +

+ + )} +
+ + + ); +} + +function SummaryStat({ label, value }: { label: string; value: string }) { + return ( +
+ +
+ ); +} + +function TokenExplanation({ total, breakdown }: { total: number; breakdown: ClientAgentDetail["tokenBreakdown"] }) { + const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } = breakdown; + const freshInput = + inputTokens !== null && cacheReadTokens !== null && cacheWriteTokens !== null + ? inputTokens - cacheReadTokens - cacheWriteTokens + : null; + const rows = [ + { label: "Cache reads", value: cacheReadTokens, color: stackedUsageColor(0) }, + { label: "Cache writes", value: cacheWriteTokens, color: stackedUsageColor(1) }, + { label: "Uncached input", value: freshInput, color: stackedUsageColor(2) }, + { label: "Output", value: outputTokens, color: stackedUsageColor(3) }, + ]; + const complete = rows.every((row) => row.value !== null); + return ( + + {complete && total > 0 && ( + + )} + {cacheReadTokens !== null && total > 0 && ( +

+ {((cacheReadTokens / total) * 100).toFixed(1)}% of these tokens are cache reads. +

+ )} +
+ {rows.map((row) => ( +
+
+ + {row.label} +
+
{countLabel(row.value)}
+
+ ))} +
+

+ Total tokens include input, cached input and output. Cached input is priced differently, so token count alone + does not explain spend. Compare the same person and dates when checking the count shown by a client. +

+ + ); +} diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsageSelect.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsageSelect.tsx new file mode 100644 index 00000000000..d0b0c7750d6 --- /dev/null +++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/ClientUsageSelect.tsx @@ -0,0 +1,25 @@ +import { SearchSelect } from "@/components/shared/SearchSelect"; +import { parseUsageClient, UsageClient } from "./overview/agentCatalog"; + +const CLIENT_OPTIONS = [ + { value: UsageClient.ClaudeDesktop, label: "Claude Desktop" }, + { value: UsageClient.ClaudeCode, label: "Claude Code" }, +]; + +export default function ClientUsageSelect({ + value, + onChange, +}: { + value: UsageClient | null; + onChange: (client: UsageClient | null) => void; +}) { + return ( + onChange(parseUsageClient(client))} + /> + ); +} diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.test.tsx deleted file mode 100644 index d971f5d0506..00000000000 --- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.test.tsx +++ /dev/null @@ -1,83 +0,0 @@ -import { screen } from "@testing-library/react"; -import { beforeAll, describe, expect, it, vi } from "vitest"; -import { renderWithProviders } from "@/../tests/test-utils"; -import UsageAIChatPanel from "./UsageAIChatPanel"; - -beforeAll(() => { - if (typeof window !== "undefined" && !window.ResizeObserver) { - window.ResizeObserver = class ResizeObserver { - observe() {} - unobserve() {} - disconnect() {} - } as any; - } -}); - -vi.mock("@/components/networking", () => ({ - modelHubCall: vi.fn().mockResolvedValue({ - data: [{ model_group: "gpt-4" }, { model_group: "claude-3-opus" }], - }), - usageAiChatStream: vi.fn(), -})); - -const defaultProps = { - open: true, - onClose: vi.fn(), - accessToken: "test-token", -}; - -describe("UsageAIChatPanel", () => { - it("should render the panel when open", () => { - renderWithProviders(); - - expect(screen.getByText("Ask AI")).toBeInTheDocument(); - expect(screen.getByText("Ask about your spend, models, keys, and trends")).toBeInTheDocument(); - }); - - it("should render model selector", () => { - renderWithProviders(); - - // One library paints the prompt as its own text node and the other leaves it on the input's - // placeholder attribute, so either one means the user is being told what to pick. - const prompt = "Select a model (optional, defaults to gpt-4o-mini)"; - expect(screen.queryAllByText(prompt).length + screen.queryAllByPlaceholderText(prompt).length).toBeGreaterThan(0); - }); - - it("should render empty state message when no conversation", () => { - renderWithProviders(); - - expect(screen.getByText("Ask a question about your usage")).toBeInTheDocument(); - }); - - it("should render the send button", () => { - renderWithProviders(); - - expect(screen.getByText("Send")).toBeInTheDocument(); - }); - - it("should render input placeholder", () => { - renderWithProviders(); - - expect(screen.getByPlaceholderText("Ask about your usage...")).toBeInTheDocument(); - }); - - it("should render clear chat button", () => { - renderWithProviders(); - - expect(screen.getByText("Clear chat")).toBeInTheDocument(); - }); - - it("should have the panel element even when closed (just off-screen)", () => { - renderWithProviders(); - - expect(screen.getByTestId("usage-ai-chat-panel")).toBeInTheDocument(); - expect(screen.getByTestId("usage-ai-chat-panel")).toHaveClass("translate-x-full"); - }); - - it("should not have translate-x-full class when open", () => { - renderWithProviders(); - - expect(screen.getByTestId("usage-ai-chat-panel")).not.toHaveClass("translate-x-full"); - expect(screen.getByTestId("usage-ai-chat-panel")).toHaveClass("translate-x-0"); - }); -}); diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.tsx deleted file mode 100644 index dc4291d25e1..00000000000 --- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsageAIChatPanel.tsx +++ /dev/null @@ -1,385 +0,0 @@ -import React, { useEffect, useRef, useState } from "react"; -import ReactMarkdown from "react-markdown"; -import { MessageSquare, Sparkles, X } from "lucide-react"; -import { Button } from "@/components/ui/button"; -import { - Combobox, - ComboboxContent, - ComboboxEmpty, - ComboboxInput, - ComboboxItem, - ComboboxList, -} from "@/components/ui/combobox"; -import { Textarea } from "@/components/ui/textarea"; -import { UiLoadingSpinner } from "@/components/ui/ui-loading-spinner"; -import { modelHubCall, usageAiChatStream, UsageAiToolCallEvent } from "@/components/networking"; - -interface ToolCallStep { - tool_name: string; - tool_label: string; - arguments: Record; - status: "running" | "complete" | "error"; - error?: string; -} - -interface ChatMessage { - role: "user" | "assistant"; - content: string; - toolCalls?: ToolCallStep[]; -} - -interface UsageAIChatPanelProps { - open: boolean; - onClose: () => void; - accessToken: string | null; -} - -const TOOL_ICONS: Record = { - get_usage_data: "📊", - get_team_usage_data: "👥", - get_tag_usage_data: "🏷️", -}; - -const ToolCallDisplay: React.FC<{ step: ToolCallStep }> = ({ step }) => { - const icon = TOOL_ICONS[step.tool_name] || "🔧"; - const args = step.arguments; - const dateRange = args.start_date && args.end_date ? `${args.start_date} → ${args.end_date}` : ""; - const filter = args.team_ids || args.tags || args.user_id || ""; - - return ( -
- - {step.status === "running" ? ( - - ) : step.status === "error" ? ( - ✗ - ) : ( - ✓ - )} - -
-
- {icon} {step.tool_label} -
- {dateRange &&
{dateRange}
} - {filter &&
Filter: {filter}
} - {step.status === "error" && step.error &&
{step.error}
} -
-
- ); -}; - -const MarkdownContent: React.FC<{ content: string }> = ({ content }) => ( -

{children}

, - strong: ({ children }) => {children}, - ul: ({ children }) =>
    {children}
, - ol: ({ children }) =>
    {children}
, - li: ({ children }) =>
  • {children}
    • , - h1: ({ children }) =>

    {children}

    , - h2: ({ children }) =>

    {children}

    , - h3: ({ children }) =>

    {children}

    , - code: ({ children, className }) => { - const isBlock = className?.includes("language-"); - return isBlock ? ( - 
    -            {children}
-
    - ) : ( - {children} - ); - }, - table: ({ children }) => ( -
    - {children}
    -
    - ), - th: ({ children }) => ( - {children} - ), - td: ({ children }) => {children}, - }} - > - {content} -     -); - -const UsageAIChatPanel: React.FC = ({ open, onClose, accessToken }) => { - const [messages, setMessages] = useState([]); - const [inputText, setInputText] = useState(""); - const [isLoading, setIsLoading] = useState(false); - const [selectedModel, setSelectedModel] = useState(undefined); - const [availableModels, setAvailableModels] = useState([]); - const [isLoadingModels, setIsLoadingModels] = useState(false); - const [streamingContent, setStreamingContent] = useState(""); - const [statusMessage, setStatusMessage] = useState(null); - const [activeToolCalls, setActiveToolCalls] = useState([]); - const messagesEndRef = useRef(null); - const abortControllerRef = useRef(null); - - useEffect(() => { - if (open && availableModels.length === 0) { - loadModels(); - } - }, [open]); - - useEffect(() => { - if (typeof messagesEndRef.current?.scrollIntoView === "function") { - messagesEndRef.current.scrollIntoView({ behavior: "smooth" }); - } - }, [messages, streamingContent, activeToolCalls, statusMessage]); - - const loadModels = async () => { - if (!accessToken) return; - setIsLoadingModels(true); - try { - const fetchedModels = await modelHubCall(accessToken); - if (fetchedModels?.data?.length > 0) { - const models = fetchedModels.data.map((item: any) => item.model_group as string).sort(); - setAvailableModels(models); - } - } catch (error) { - console.error("Failed to load models:", error); - } finally { - setIsLoadingModels(false); - } - }; - - const handleSend = async () => { - if (!accessToken || !inputText.trim() || isLoading) return; - - const userMessage: ChatMessage = { role: "user", content: inputText.trim() }; - const updatedMessages = [...messages, userMessage]; - setMessages(updatedMessages); - setInputText(""); - setIsLoading(true); - setStreamingContent(""); - setStatusMessage(null); - setActiveToolCalls([]); - - const abortController = new AbortController(); - abortControllerRef.current = abortController; - - let accumulated = ""; - const toolCalls: ToolCallStep[] = []; - - try { - await usageAiChatStream( - accessToken, - updatedMessages.slice(-20).map((m) => ({ role: m.role, content: m.content })), - selectedModel || "", - (content: string) => { - setStatusMessage(null); - accumulated += content; - setStreamingContent(accumulated); - }, - () => { - setStatusMessage(null); - setActiveToolCalls([]); - setMessages((prev) => [ - ...prev, - { role: "assistant", content: accumulated, toolCalls: toolCalls.length > 0 ? [...toolCalls] : undefined }, - ]); - setStreamingContent(""); - }, - (errorMsg: string) => { - setStatusMessage(null); - setActiveToolCalls([]); - setMessages((prev) => [...prev, { role: "assistant", content: `Error: ${errorMsg}` }]); - setStreamingContent(""); - }, - (status: string) => { - setStatusMessage(status); - }, - (event: UsageAiToolCallEvent) => { - const idx = toolCalls.findIndex((tc) => tc.tool_name === event.tool_name); - if (idx >= 0) { - toolCalls[idx] = { ...event }; - } else { - toolCalls.push({ ...event }); - } - setActiveToolCalls([...toolCalls]); - }, - abortController.signal, - ); - } catch (error: any) { - if (error?.name === "AbortError" || abortController.signal.aborted) { - return; - } - const errorMsg = error?.message || "Failed to get response. Please try again."; - setMessages((prev) => [...prev, { role: "assistant", content: `Error: ${errorMsg}` }]); - setStreamingContent(""); - } finally { - setIsLoading(false); - abortControllerRef.current = null; - } - }; - - const handleKeyDown = (e: React.KeyboardEvent) => { - if (e.key === "Enter" && !e.shiftKey) { - e.preventDefault(); - handleSend(); - } - }; - - const handleClose = () => { - if (abortControllerRef.current) { - abortControllerRef.current.abort(); - } - onClose(); - }; - - const handleClear = () => { - setMessages([]); - setStreamingContent(""); - setActiveToolCalls([]); - setStatusMessage(null); - }; - - return ( -
    - {/* Header */} -
    -
    -

    -

    -

    Ask about your spend, models, keys, and trends

    -
    - -
    - - {/* Model selector */} -
    - setSelectedModel(value ?? undefined)} - > - - - {isLoadingModels ? "Loading models…" : "No models found"} - - {(model: string) => ( - - {model} - - )} - - - -
    - - {/* Chat messages */} -
    - {messages.length === 0 && !streamingContent && !isLoading && ( -
    -
    - )} - - {messages.map((msg, idx) => ( -
    - {msg.role === "user" ? ( -
    -
    - {msg.content} -
    -
    - ) : ( -
    - {/* Tool calls for this message */} - {msg.toolCalls && msg.toolCalls.length > 0 && ( -
    - {msg.toolCalls.map((tc, tcIdx) => ( - - ))} -
    - )} - {/* Response */} -
    - -
    -
    - )} -
    - ))} - - {/* Active tool calls (in-progress) */} - {isLoading && activeToolCalls.length > 0 && ( -
    - {activeToolCalls.map((tc, idx) => ( - - ))} -
    - )} - - {/* Status / spinner */} - {isLoading && !streamingContent && ( -
    - - {statusMessage || "Thinking..."} -
    - )} - - {/* Streaming response */} - {streamingContent && ( -
    - -
    - )} - -
    -
    - - {/* Input area */} -
    -
    -