Django ORM

Proxy: passthrough access to a 3rd party LLM provider’s API, with an API key that Smarter keeps.

A Proxy forwards requests, as they are, to an LLM provider’s native API, e.g. https://api.openai.com/v1/. The only difference between calling the provider directly and calling it through a Proxy is the API key: the caller authenticates with a Smarter API key, and Smarter adds the provider’s API key, which it keeps in a Secret. The provider’s API key never leaves Smarter.

client --(Smarter API key)--> /api/v1/proxy/<name>/<path> --(provider API key)--> <base_url><path>

A Proxy is configured by a Proxy manifest. See smarter.apps.proxy.manifest.models.proxy.spec.

Like other Smarter resources, a Proxy is owned by a user, and its visibility is determined by ownership and role: the built-in Proxies are owned by the Smarter admin, so every account may use them.

class smarter.apps.proxy.models.Proxy(*args, **kwargs)[source]

Bases: MetaDataWithOwnershipModel

A Proxy of a 3rd party LLM provider’s API.

Parameters:

provider – The Provider whose API the Proxy forwards to.
api_key_secret – The Secret that contains the provider’s API key. If None, the Provider’s own API key Secret is used.
base_url – The base URL of the provider’s API. If empty, the Provider’s base URL is used.
auth_header – The HTTP header in which the provider expects its API key, e.g. Authorization or x-api-key.
auth_scheme – The prefix of the API key in the header, e.g. Bearer, or empty for none.
headers – Other HTTP headers that are added to every request, e.g. {"anthropic-version": "2023-06-01"}.
allowed_paths – The paths, relative to the base URL, that callers may use, as glob patterns, e.g. ["chat/completions", "models/*"]. Empty allows every path.
timeout – The most seconds to wait for the provider’s response.
is_active – Inactive Proxies refuse every request.
id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
name (Unknown) – Name. Name in camelCase, e.g., ‘apiKey’, no special characters.
description (Unknown) – Description. A brief description of this resource. Be verbose, but not too verbose.
version (Unknown) – Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.
annotations (Unknown) – Annotations. Key-value pairs for annotating this resource.

Relationship fields:

Parameters:

user_profile (Unknown) – User profile (related name: proxy)
tags (Unknown) – Tags. Tags for categorizing and organizing this resource. (related name: proxy)
tagged_items (Unknown) – Tagged items (related name: +)

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

exception NotUpdated: Bases: ObjectNotUpdated, DatabaseError

allowed_paths

JSONField

Allowed paths. Glob patterns of the paths, relative to the base URL, that callers may use. Empty allows every path.

Type:: Type

annotations

JSONField

Annotations. Key-value pairs for annotating this resource.

Type:: Type

api_key_secret

ForeignKey to Secret

Api key secret. The secret containing the provider’s API key. If empty, the provider’s own API key is used. (related name: proxies)

Type:: Type

api_key_secret_id: Internal field, use api_key_secret instead.

auth_header

CharField

Auth header. The HTTP header in which the provider expects its API key, e.g. ‘Authorization’ or ‘x-api-key’.

Type:: Type

auth_header_value(api_key)[source]

The value of auth_header, e.g. Bearer sk-....

Return type:: str

auth_scheme

CharField

Auth scheme. The prefix of the API key in the auth header, e.g. ‘Bearer’. Empty for none.

Type:: Type

base_url

URLField

Base url. The base URL of the provider’s API, e.g. https://api.openai.com/v1/. If empty, the provider’s base URL is used.

Type:: Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created.

This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:: Type

description

TextField

Description. A brief description of this resource. Be verbose, but not too verbose.

Type:: Type

headers

JSONField

Headers. Other HTTP headers that are added to every request, e.g. {‘anthropic-version’: ‘2023-06-01’}.

Type:: Type

id

BigAutoField

Primary key: ID

Type:: Type

is_active

BooleanField

Is active. Inactive proxies refuse every request.

Type:: Type

property is_billable_resource: bool

each request is charged to the Proxy, and to the caller.

Returns:: True
Return type:: bool
Type:: Proxies are billable

is_path_allowed(path)[source]

Whether callers may use a path: it is a valid path, and allowed_paths is empty or a pattern matches it.

The patterns are matched with fnmatch.fnmatchcase(), so * also matches /, e.g. models/* matches models/gemini-2.5-flash:generateContent. A trailing slash is ignored.

Return type:: bool

property manifest_url: str: The URL of the Proxy’s detail view in the web console, which renders its manifest.

may_use_secret(secret)[source]

Whether the Proxy may send a Secret’s API key: only if the Secret belongs to the Proxy owner’s account.

Otherwise anyone could write a Proxy that sends another account’s API key, e.g. the platform’s, to a base URL of their choosing. The built-in Proxies, which the Smarter admin owns, may use the platform’s Secrets, and every account may use them.

Return type:: bool

name

CharField

Name. Name in camelCase, e.g., ‘apiKey’, no special characters.

Type:: Type

objects: MetaDataWithOwnershipModelManager = <smarter.apps.account.models.metadata_with_ownership.MetaDataWithOwnershipModelManager object>

provider

ForeignKey to Provider

Provider. The provider whose API this proxy forwards requests to. (related name: proxies)

Type:: Type

provider_id: Internal field, use provider instead.

property secret: Secret | None

api_key_secret, else the Provider’s.

Type:: The Secret that contains the provider’s API key

property secret_name: str | None: The name of secret, never its value.

tagged_items

Reverse GenericRelation from Proxy

All + of this tagged item (related name of tagged_items)

Type:: Type

tags = <taggit.managers._TaggableManager object>

timeout

PositiveIntegerField

Timeout. The most seconds to wait for the provider’s response.

Type:: Type

updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated.

This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:: Type

property upstream_base_url: str

base_url, else the Provider’s.

Returns:: The base URL, or an empty string if neither is set.
Type:: The base URL of the provider’s API, with a trailing slash

property upstream_host: str: The host name of the provider’s API, e.g. api.openai.com.

upstream_url(path)[source]

The provider’s URL of a path, relative to the base URL.

Return type:: Optional[str]
Returns:: The URL, or None if the path is refused by normalize_path().

property url: str

The path of the Proxy’s passthrough endpoint, e.g. /api/v1/proxy/openai/.

Empty if the endpoints are disabled, with SMARTER_ENABLE_PROXY=false.

user_profile

ForeignKey to UserProfile

User profile (related name: proxy)

Type:: Type

user_profile_id: Internal field, use user_profile instead.

version

CharField

Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.

Type:: Type

smarter.apps.proxy.models.normalize_path(path)[source]

Normalize a path within a Proxy’s base URL, e.g. /chat/completions to chat/completions.

The path is relative to the base URL, so its leading slashes are removed. Paths that could leave the base URL are refused: .. and . segments, empty segments, backslashes, and absolute URLs.

Return type:: Optional[str]
Returns:: The normalized path, or None if it is refused.