Skip to content

api-contract.md

Latest commit

 

History

History
266 lines (195 loc) · 18.6 KB

api-contract.md

File metadata and controls

266 lines (195 loc) · 18.6 KB
Raw

API Contract and Endpoint Classification

This document serves as the authoritative reference for maintainers and contributors regarding the project's API architecture, lifecycle guarantees, and persistence semantics.

1. Purpose

WebAI-to-API exposes multiple API surfaces to balance standard compatibility, legacy support, and specialized integration needs.

  • Primary APIs: The core surface intended for all new integrations. Adheres to industry standards (OpenAI).
  • Compatibility APIs: Bridges designed to emulate specific third-party protocols (e.g., Google Generative AI).
  • Legacy APIs: Original endpoints maintained for backward compatibility with early versions of the project.
  • Specialized APIs: Target-specific endpoints designed for a particular consumer (e.g., browser extensions).

2. Endpoint Classification Matrix

Endpoint Category Recommended Persistence Streaming Notes
/v1/chat/completions Primary Yes Provider/backend-dependent Yes Authoritative OpenAI-compatible surface.
/v1/temporary/chat/completions Specialized No Gemini WebAPI temporary Yes OpenAI-compatible Gemini-only temporary endpoint; no durable conversation continuation.
/v1/conversations Primary Yes Lists/deletes Gemini WebAPI snapshots No GET lists local snapshots; DELETE bulk-deletes Gemini WebAPI conversations.
/v1/conversations/{conversation_id} Primary Yes Deletes Gemini WebAPI snapshots No Gemini WebAPI-only conversation deletion.
/v1/models Primary Yes N/A No Discovery endpoint for registered providers and their available model IDs.
/v1/auth/status Primary Yes N/A No Real-time auth state and health diagnostics.
/v1/auth/login Primary Yes N/A No Trigger for browser-based login workflows.
/v1beta/models/{model} Compatibility No N/A Yes Google Generative AI compatibility bridge.
/gemini Legacy No Stateless Yes Original MVP endpoint. No session state.
/gemini-chat Legacy No In-memory Yes Simple session state; does not survive restarts.
/translate Specialized No Stateless temporary No Independent Gemini WebAPI requests through the shared authenticated client; no conversation state or Gemini history persistence.
/v1/gems Utilities Yes N/A No Gemini "Gems" enumeration.

3. Primary Contract: /v1/chat/completions

The /v1/chat/completions endpoint is the authoritative API surface of the project. All maintainers must prioritize its stability and feature parity with the OpenAI Chat Completion spec.

  • Schema: Follows the OpenAI request/response format plus documented provider-scoped request options.
  • Streaming: Supported via Server-Sent Events (SSE).
  • Provider Routing: Requests are routed through the ProviderFactory.
  • Persistence: Provider/backend-dependent. The selected provider and adapter define whether conversation_id maps to local snapshots, provider-side conversation URLs, or no persisted state.
  • Isolation: Every request is isolated by its conversation_id.

Provider Options

Requests may use typed provider-scoped options:

{
  "provider_options": {
    "gemini": {
      "extended_thinking": true
    }
  }
}

gemini.extended_thinking applies to Gemini WebAPI and Playwright models. Effective value is resolved on every request: an explicit request value takes precedence over [Gemini].extended_thinking, which falls back to false when the key is missing. The value accepts only case-insensitive, trimmed true or false; config stores canonical lowercase values. The option is request-scoped and is not part of session identity or persisted snapshots, so reused conversations may switch values between turns. Omitted Playwright request options do not inherit UI state from a reused PersistentTab. Atlas rejects the option with HTTP 400. Unknown namespaces, unknown Gemini options, and invalid value types fail schema validation with HTTP 422. Extended thinking is not declared equivalent to reasoning_effort.

For Gemini WebAPI, the resolved boolean applies to buffered generation, progressive streaming, tool-call buffered generation, and generation retry, and is passed through to upstream chat generation.

3.1 Multimodal Content Parts

messages[].content supports both plain strings and OpenAI-style content-part arrays.

  • Text: { "type": "text", "text": "..." }
  • File: { "type": "file", "file": { "filename": "...", "file_data": "data:...;base64,..." } }

Current MVP rules:

  • Plain string content remains fully supported.
  • Text parts are accepted and flattened into provider-specific prompt text.
  • File parts are supported only for the Gemini WebAPI backend.
  • File parts are request-scoped only. They are staged to server-owned temporary files for the current request and are not persisted in SQLite snapshots.
  • Gemini Playwright and Atlas must reject file parts with a clear capability error.
  • Remote URLs, filesystem paths, file_id, and unsupported content-part types are rejected.
  • The currently verified file format list is maintained in docs/api.md.
  • For Gemini WebAPI, text content parts are concatenated into one prompt and file parts are passed as attachments, so exact text/file interleaving order is not preserved.

3.2 Generated Output Artifacts

Gemini WebAPI may return generated artifacts alongside text output.

  • Buffered Responses: Gemini WebAPI responses may include choices[0].artifacts while message.content remains text-only.
  • Streaming Responses: Gemini WebAPI may emit one final SSE chunk before [DONE] that carries choices[0].delta = {} and choices[0].artifacts = [...].
  • Provider Scope: Generated output artifacts are Gemini WebAPI-specific. Playwright and Atlas do not expose this response shape.
  • Thoughts: Model thoughts remain hidden by default and are not exposed through the public API response shape.
  • Persistence: Artifact blobs are not persisted in local snapshots or conversation state.
  • Metadata Semantics: Artifact URLs are provider metadata only. Clients must not assume they are permanent, public, or stable download handles.

4. Conversation Contract

conversation_id

  • Creation: If not provided, a cryptographically secure 16-byte opaque token is generated.
  • Reuse: Providing a valid conversation_id instructs the selected provider/backend to attempt continuation according to its own recovery mechanism.
  • Recovery: Recovery depends on the provider/backend:
    • Gemini WebAPI: Uses SQLite-backed session snapshots through SessionRegistry and SQLiteConversationRepository.
    • Gemini Playwright: Uses Gemini provider-side conversation URLs (https://gemini.google.com/app/{conversation_id}) and reuses in-memory PersistentTab instances when available. It does not use SQLite conversation snapshots.
    • Atlas: Stateless pass-through provider. It does not consume or persist conversation_id.
    • Temporary Gemini WebAPI: /v1/temporary/chat/completions rejects conversation_id and always starts a fresh temporary request with no continuation token.

reused_conversation

A boolean field injected into the response metadata:

  • Gemini WebAPI:
    • true: An existing or restored ChatSession was reused.
    • false: A new ChatSession was bootstrapped.
  • Gemini Playwright:
    • true: An in-memory PersistentTab for the conversation was reused.
    • false: No in-memory tab was reused. The backend may still resume the provider-side Gemini thread by navigating to the conversation URL.
  • Stateless providers: This field may be absent or provider-defined because no local conversation state is maintained and no continuation can be guaranteed.

Listing

GET /v1/conversations lists Gemini WebAPI conversations persisted in local SQLite snapshots only.

  • Gemini WebAPI: The runtime reads SQLite snapshots through SessionRegistry and SQLiteConversationRepository, validates snapshot schema and provider-owned session_state, and returns public local metadata such as conversation_id, updated_at, model_name, gem_id, provider, backend, and schema version.
  • No Remote Calls: Listing does not restore ChatSession objects and does not call Gemini remote APIs.
  • Metadata Privacy: Raw Gemini continuation metadata and remote Gemini chat IDs are not exposed.
  • Gemini Playwright: Not included because Playwright conversations are provider-side URL-backed and not SQLite-backed WebAPI snapshots.
  • Atlas: Not included because Atlas requests are stateless in this runtime.

Bulk Deletion

DELETE /v1/conversations best-effort deletes all locally persisted Gemini WebAPI conversations.

  • Gemini WebAPI: The runtime lists SQLite snapshots through SessionRegistry, reserves each conversation with the per-conversation deletion tombstone, extracts the remote Gemini chat ID from session_state.metadata[0], calls the Gemini WebAPI delete operation, then removes the local SessionManager and SQLite snapshot.
  • Best Effort: The operation is not atomic. Individual active, remote-failed, or cleanup-failed conversations are reported per item while the endpoint continues processing remaining snapshots.
  • Status Semantics: The endpoint returns 200 OK whenever it can produce a bulk report, including partial failures. It does not use 207 Multi-Status.
  • Concurrency: Active or already deleting conversations are skipped with per-item status skipped_active; they are not force deleted and the endpoint does not wait for them.
  • Metadata Privacy: Raw Gemini continuation metadata and remote Gemini chat IDs are not exposed in the response.
  • Gemini Playwright and Atlas: Not supported by this endpoint.

Single Deletion

DELETE /v1/conversations/{conversation_id} deletes Gemini WebAPI conversations only.

  • Gemini WebAPI: The runtime reads the SQLite snapshot, extracts the remote Gemini chat ID from session_state.metadata[0], calls the Gemini WebAPI delete operation, removes the in-memory SessionManager, and deletes the SQLite snapshot.
  • Gemini Playwright: Not supported by this endpoint. Playwright conversation IDs are provider-side URL identifiers and are not SQLite-backed WebAPI snapshots.
  • Atlas: Not supported because Atlas requests are stateless in this runtime.
  • Concurrency: Active or already deleting conversations return 409 Conflict.

5. Persistence Guarantees

Persistence semantics vary significantly across endpoints and across /v1/chat/completions providers/backends. They must be clearly communicated to users.

Endpoint / Backend Restart Safe Persistence Type Recovery Mechanism
/v1/chat/completions - Gemini WebAPI Yes SQLite-backed snapshots Serialized ChatSession restoration via repository.
/v1/temporary/chat/completions - Gemini WebAPI No Temporary only Requests use temporary=True and are never written to Gemini history or SQLite snapshots.
/v1/chat/completions - Gemini Playwright Provider-dependent Provider-side URL-backed Navigate to https://gemini.google.com/app/{conversation_id}; reuse PersistentTab when still in memory.
/v1/chat/completions - Atlas No Stateless No local conversation persistence; requests are forwarded independently.
/gemini-chat No In-memory only Volatile; lost on server shutdown or crash.
/translate No Stateless temporary No conversation state; requests use temporary=True and execute independently.
/gemini N/A Stateless Every request is a fresh, isolated session.

6. Compatibility Layer Contract

/v1beta/models/{model}

This endpoint is a compatibility bridge, not a full implementation of the Google Generative AI specification.

  • Goal: Provide a Google Generative AI–style compatibility layer for integrations expecting Google-style request and response formats.
  • Non-Goal: 100% protocol parity, full SDK compatibility, or complete metadata support.
  • Limitation: Error codes and fine-grained metadata may not match official Google behavior.

7. Legacy Endpoint Policy

/gemini and /gemini-chat

  • Status: Deprecated.
  • Role: Retained to avoid breaking early adopter scripts and simple integrations.
  • Maintenance: Minimal. These endpoints should not receive new features (e.g., Tool Calling) unless they are trivial to pass through.
  • Migration: All documentation and responses should guide users toward /v1/chat/completions.

8. Specialized Endpoint Policy

/translate

  • Status: Supported (Specialized).
  • Execution: Uses stateless per-request Gemini WebAPI calls through the shared authenticated client.
  • Conversation State: Requests do not share conversation state and are not persisted in Gemini history.
  • Temporary Requests: Gemini WebAPI requests use temporary=True.
  • Concurrency: Independent requests can execute concurrently at the application layer. Dependency, network, and Gemini remote limits still apply.
  • Retention: Maintained as long as the "Translate It!" extension remains a primary project use case.

/v1/temporary/chat/completions

  • Status: Supported (Specialized).
  • Scope: Gemini WebAPI only. Playwright and Atlas models/providers are rejected.
  • Schema: OpenAI-compatible request/response shape.
  • Persistence: Requests use temporary=True, do not persist in Gemini history, and do not write SQLite conversation snapshots.
  • Conversation IDs: conversation_id is rejected to avoid implying durable continuation.

9. Authentication Contract

Authentication is a decoupled lifecycle managed via AuthManager and specialized endpoints.

  • Status Monitoring: /v1/auth/status provides a unified view of provider health.
  • Login Flow: /v1/auth/login is a non-blocking trigger that initiates a browser-based workflow. It returns 202 Accepted to indicate the process has started.
  • Recovery: Authentication state is checked by providers at the start of each request. If auth is missing, providers must raise a 503 Service Unavailable with a clear instruction to log in.

Authentication source handling is intentionally split by responsibility:

  • AuthLoader discovers available auth material.
  • Provider auth strategies define source priority and fallback sequencing for their provider.
  • AuthManager owns cached status returned by /v1/auth/status and coordinates login, status refresh, and provider-specific post-login recovery.

9.1 Conversation ID Semantics

conversation_id tokens are treated as opaque tokens that instruct the selected backend to attempt continuation using its native recovery mechanism.

  • Token Format: All tokens generated by the system are cryptographically secure opaque strings. Implementation details (e.g., backend identity) are not encoded into the public ID.
  • WebAPI Continuity: Identifies a locally persisted ChatSession snapshot in the SQLite repository.
  • Browser-native Continuity: Uses provider-side conversation identifiers and URL-backed recovery mechanisms to attempt continuation of existing browser-native conversations.
  • Ownership Validation: To prevent cross-backend routing errors, the system performs internal ownership validation:
    • If a conversation_id is found in the SQLite repository, it is strictly owned by the WebAPI backend.
    • Using a WebAPI-owned ID with a browser-native provider will return a 400 Bad Request.
    • IDs not present in SQLite are not considered WebAPI-owned and are therefore eligible for browser-native continuation attempts.

Cross-backend conversation continuity between WebAPI and browser-native providers is not supported due to incompatible underlying state formats.

10. Provider Routing Contract

The architecture enforces a "Thin Gateway" pattern with an encapsulated strategy layer:

/v1/chat/completions
        ↓
ProviderFactory (Resolves logical identity, e.g., "gemini", "atlas")
        ↓
Provider (Logical Identity - e.g., GeminiProvider)
        ↓
Adapter (Execution Strategy - e.g., Playwright or WebAPI)
  • Ownership: The endpoint handler is responsible for high-level routing via the factory.
  • Identity: The Provider class represents the logical LLM vendor and owns all shared logic (e.g., tool parsing, prompt transformation) common to that vendor across different backends.
  • Strategy: The Adapter encapsulates the technical implementation details of a specific execution backend (e.g., driving a browser via Playwright vs. using a REST API).
  • Transparency: The gateway remains agnostic of whether a request is fulfilled via a browser-native runtime or a direct API client.
  • Browser-Native Routing: Browser-native providers are selected through provider-aware model namespaces such as playwright/<provider>/<model>. Legacy Gemini browser routes using playwright/<gemini-model> remain supported for backward compatibility.

11. Future Evolution Policy

  1. Prioritize /v1: All major architectural improvements must target the /v1 namespace.
  2. Stability: Legacy and Specialized endpoints must remain stable even if their underlying implementation is refactored.
  3. Contracts over Wrappers: The structural API contracts defined here take precedence over any convenience wrappers or documentation summaries.
  4. Deprecation: Removal of public endpoints should follow a documented deprecation process.

12. System and Runtime Endpoints

The system exposes dedicated endpoints for health monitoring and runtime observability.

/health (Liveness)

  • Purpose: Indicates if the Python process is alive and responsive.
  • Semantics: Returns 200 OK if the app is running and not in a terminal shutdown state.
  • Safety: Strictly side-effect-free. Does not bootstrap the BrowserEngine.

/ready (Readiness)

  • Purpose: Indicates if the structural runtime is capable of accepting and processing browser-native requests.
  • Semantics: Returns 200 OK if the BrowserEngine is initialized, the browser process is connected, and at least one ProviderSession is structurally alive.
  • Exclusion: Does not validate authentication. A node is considered structurally ready even if authentication is expired.
  • Safety: Side-effect-free. Does not trigger recovery or browser launches.

/v1/runtime/status (Diagnostics)

  • Purpose: Provides deep observability into the hardened runtime's internal state.
  • Payload: Includes engine generation, browser connectivity, active lease counts, registry sizes, and cached authentication summary.
  • Safety: Strictly side-effect-free. Does not refresh authentication or trigger recovery.