codex_quota_client

ChatGPT-quota inference adapter backed by the official Codex Python SDK.

exception codex_quota_client.CodexQuotaUnavailable

Bases: RuntimeError

A safe operational error for the admin-facing GPT route.

effects_possible records whether the failure could have left provider side effects behind. A Codex turn is effect-capable — its built-in shell/filesystem/web/MCP work can change real state — so the durable turn checkpoint must fail closed on an unknown crash. It defaults to True for exactly that reason: an unmarked failure is treated as if it might have run something. CodexQuotaClient.complete() clears it for failures raised before the Codex turn is started, which provably cannot have caused an effect. See _checkpointed_provider_decision.

effects_possible: bool = True
exception codex_quota_client.CodexQuotaExhausted(message, *, fallback_safe=False)

Bases: CodexQuotaUnavailable

The linked ChatGPT account reported a definite usage-limit exhaustion.

Parameters:

  • message (str)

  • fallback_safe (bool)

Return type:

None

class codex_quota_client.CodexDeviceAuthorization(subject, account_id, login_id, verification_url, user_code)

Bases: object

One private device-code challenge bound to a canonical Star user.

Parameters:

  • subject (str)

  • account_id (str)

  • login_id (str)

  • verification_url (str)

  • user_code (str)

subject: str
account_id: str
login_id: str
verification_url: str
user_code: str
class codex_quota_client.CodexAccountStatus(account_id, plan_type)

Bases: object

Non-secret status for one linked ChatGPT-backed Codex account.

Parameters:

  • account_id (str)

  • plan_type (str)

account_id: str
plan_type: str
class codex_quota_client.CodexServiceTier(id, name, description)

Bases: object

One model service tier advertised by the linked Codex account.

Parameters:
id: str
name: str
description: str
class codex_quota_client.CodexModelCapability(model, id, supported_efforts, default_effort, service_tiers, default_service_tier, is_default)

Bases: object

Non-secret model capability data retained from the live catalog.

Parameters:
model: str
id: str
supported_efforts: frozenset[str]
default_effort: str | None
service_tiers: tuple[CodexServiceTier, ...]
default_service_tier: str | None
is_default: bool
class codex_quota_client.CodexStreamEvent(kind, delta, sequence, user_visible=False, turn_id='', item_id='', phase=None)

Bases: object

One decoded, user-presentable delta from a live Codex turn.

Parameters:
kind: str
delta: str
sequence: int
user_visible: bool
turn_id: str
item_id: str
phase: str | None
class codex_quota_client.CodexQuotaClient(*, client_factory=None)

Bases: object

Account-isolated ChatGPT quota bridge backed by Codex app-server.

Concurrent generations for one account share one SDK/app-server process. Idle account processes stay warm for a bounded TTL, while different accounts always use different private homes and processes. Device login keeps its process alive only until that one attempt succeeds, fails, times out, or is cancelled.

Parameters:

client_factory (Callable[..., Any | Awaitable[Any]] | None)

validate_storage()

Validate the complete persistent identity boundary synchronously.

The inference owner calls this during construction, before it can report readiness. Missing records for otherwise valid legacy credentials are created, while missing/replaced keys, tampered records, unsafe account directories, and orphan identity records fail closed.

Return type:

None

async begin_device_login(subject)

Start one private ChatGPT device-code login for subject.

Return type:

CodexDeviceAuthorization

Parameters:

subject (str)

async has_pending_login(subject)
Return type:

bool

Parameters:

subject (str)

async finish_device_login(subject, login_id)

Wait for and validate the exact pending device-code login.

Return type:

CodexAccountStatus

Parameters:

  • subject (str)

  • login_id (str)

async cancel_device_login(subject)

Cancel and remove one pending device authorization.

Return type:

bool

Parameters:

subject (str)

async account_status(account_id)

Return live non-secret account status, or None when unlinked.

Return type:

CodexAccountStatus | None

Parameters:

account_id (str)

async logout_account(account_id)

Drain active calls, clear auth, and remove exactly one account home.

Return type:

bool

Parameters:

account_id (str)

async validate_route(model, effort, *, service_tier=None, account_id=None)

Verify the linked account’s live model, effort, and service tier.

Return type:

None

Parameters:

  • model (str)

  • effort (str)

  • service_tier (str | None)

  • account_id (str | None)

async model_catalog(*, account_id=None, refresh=False)

Return the linked account’s non-secret live Codex model catalog.

Return type:

tuple[CodexModelCapability, ...]

Parameters:

  • account_id (str | None)

  • refresh (bool)

async capacity_identity(account_id)

Return a deployment-local opaque identity for capacity deduplication.

Return type:

str

Parameters:

account_id (str)

async complete(messages, *, model, effort, tools, service_tier=None, forced_tool_name=None, require_tool=False, response_format=None, account_id=None, stream_callback=None, admin_authorized=False, timeout_seconds=<codex_quota_client._DefaultTimeoutPolicy object>)

Return one OpenAI-shaped message using exactly one linked account.

Marks failures raised before the Codex turn exists as provably effect-free. Account resolution, leasing, session setup, catalog validation, and prompt assembly all run before thread_start, so a failure in any of them cannot have executed shell, filesystem, web, or MCP work. The durable turn checkpoint uses that to release its slot instead of stranding it — see _checkpointed_provider_decision.

Return type:

dict[str, Any]

Parameters:
async close()

Cancel pending logins and drain every active account operation.

Return type:

None