"""
The contract of the web console's session api, ``GET /api/web/session/``, as Pydantic models.
The single-page console (:doc:`ADR-035 </adr/035-single-page-app>`) calls it when it starts, and again
after the user signs in, signs out or changes profile. It replaces what Django's context processors and
the React apps' template tags put into each server-rendered page: who the user is, the account that the
console acts for, the platform's branding, which sign-in options and features are on, the languages, the SAM kinds,
and the state of the welcome dialog and onboarding hints. The JSON is camelCase.
A request without a signed-in user gets a :class:`ConsoleSession` whose ``user``, ``account``,
``onboarding``, ``welcome``, ``badges`` and ``sidebar`` are ``null``: what the sign-in pages need, and nothing about
any user.
``manage.py export_console_session_schema`` writes the models' JSON Schema to
``console-session.schema.json``, beside this module, from which ``@smarter/console`` generates its
TypeScript types (``make console-session-contract``). A test fails if the committed schema is out of date.
"""
import json
from pathlib import Path
from typing import Optional
from pydantic import BaseModel, ConfigDict, Field
from pydantic.alias_generators import to_camel
from pydantic.json_schema import JsonSchemaMode, models_json_schema
from smarter.common.const import SMARTER_PROJECT_WEBSITE_URL
from smarter.lib.typing import SmarterDictType
SCHEMA_PATH = Path(__file__).parent / "console-session.schema.json"
"""The committed JSON Schema of the contract."""
SCHEMA_ID = f"{SMARTER_PROJECT_WEBSITE_URL}/schemas/console-session.schema.json"
[docs]
class ConsoleSessionModel(BaseModel):
"""The base class of the contract's models: camelCase JSON, and no fields that a model doesn't define."""
model_config = ConfigDict(
extra="forbid",
alias_generator=to_camel,
validate_by_name=True,
validate_by_alias=True,
serialize_by_alias=True,
# a response always has every field, so the schema, and the TypeScript types generated
# from it, mark the fields that have defaults as required too.
json_schema_serialization_defaults_required=True,
)
[docs]
def to_json(self) -> SmarterDictType:
"""The model as the view sends it."""
return self.model_dump(mode="json")
[docs]
class ConsoleBranding(ConsoleSessionModel):
"""The platform's identity and contacts, which the console shows in its header, footer and sign-in pages."""
product_name: str = Field(..., description="The product's name, e.g. The Smarter Project.")
product_description: str = Field(..., description="A one-sentence description of the product.")
corporate_name: str = Field(..., description="The organization that runs this platform.")
corporate_address: str = Field(..., description="Its postal address, on one line, or empty.")
support_email: str = Field(..., description="The support email address, or empty.")
support_phone_number: str = Field(..., description="The support phone number, or empty.")
support_hours: str = Field(..., description="When support answers, or empty.")
primary_contact: str = Field(..., description="The name of the platform's primary contact, or empty.")
contact_url: str = Field(..., description="A page for contacting the organization.")
copyright: str = Field(..., description="The copyright notice of the footer.")
url_facebook: str = Field(..., description="The organization's Facebook page, or empty.")
url_twitter: str = Field(..., description="The organization's X/Twitter page, or empty.")
url_linkedin: str = Field(..., description="The organization's LinkedIn page, or empty.")
url_slack: str = Field(..., description="An invitation to the project's Slack workspace, or empty.")
logo_url: str = Field(..., description="The logo, an absolute url on the project's CDN.")
marketing_site_url: str = Field(..., description="The organization's website.")
project_website_url: str = Field(..., description="The Smarter project's website.")
project_docs_url: str = Field(..., description="The documentation, docs.smarter.sh.")
legal_url: str = Field(..., description="The legal page: terms, privacy and cookies.")
environment_url: str = Field(..., description="This platform's own url, e.g. https://platform.example.com.")
[docs]
class ConsoleSignIn(ConsoleSessionModel):
"""The ways to sign in or sign up that the sign-in pages offer."""
google: bool = Field(..., description="Whether the Sign in with Google button shows.")
github: bool = Field(..., description="Whether the Sign in with GitHub button shows.")
sign_up: bool = Field(..., description="Whether anyone may create an account: the sign-up page answers 404 if not.")
footer_links: bool = Field(..., description="Whether the sign-in page shows its footer's links.")
doodle: bool = Field(..., description="Whether the sign-in pages show the doodle of the day.")
[docs]
class ConsoleLanguageOption(ConsoleSessionModel):
"""A language that the console is translated into."""
code: str = Field(..., description="Its code, e.g. pt-br.")
name: str = Field(..., description="Its name, in itself, e.g. Português Brasileiro.")
[docs]
class ConsoleLanguage(ConsoleSessionModel):
"""The console's languages, and the one that this response, and the session, are in."""
current: str = Field(..., description="The code of the session's language.")
bidi: bool = Field(..., description="Whether the session's language is written right to left.")
languages: list[ConsoleLanguageOption] = Field(..., description="Every language the menu offers.")
[docs]
class ConsoleCookies(ConsoleSessionModel):
"""The names and domain of Django's cookies, which the console's api calls send."""
csrf_cookie_name: str = Field(..., description="The CSRF cookie, whose value is sent as X-CSRFToken.")
session_cookie_name: str = Field(..., description="The session cookie.")
cookie_domain: str = Field(..., description="The cookies' domain, or empty for the request's host.")
[docs]
class ConsoleFlags(ConsoleSessionModel):
"""The console's optional features: which pages exist, and which tabs and widgets show."""
proxy: bool = Field(..., description="Whether the Proxies pages exist.")
vectorstore: bool = Field(..., description="Whether the Vectorstores pages exist.")
manifest_drop_zone: bool = Field(..., description="Whether the manifest drop zone page exists.")
terminal: bool = Field(..., description="Whether the Terminal page exists for this user, a superuser.")
passthrough: bool = Field(..., description="Whether the Prompt Passthrough page exists.")
server_logs: bool = Field(..., description="Whether the Server Logs tabs show.")
did_you_know: bool = Field(..., description="Whether the header shows a Did you know? tip.")
react_debug_mode: bool = Field(..., description="Whether the React apps log their debugging output.")
[docs]
class ConsoleUser(ConsoleSessionModel):
"""The signed-in user."""
username: str
email: str
first_name: str
last_name: str
is_superuser: bool
is_staff: bool
administers_account: bool = Field(
...,
description=(
"Whether the user administers the account that the console acts for: a superuser, staff, or an "
"admin of that account only, e.g. a department's head."
),
)
profile_image_url: str = Field(..., description="The user's avatar, or the default image.")
user_profile_count: int = Field(..., description="How many accounts the user belongs to.")
[docs]
class ConsoleAccount(ConsoleSessionModel):
"""The account that the console acts for: that of the user's selected profile."""
account_number: str = Field(..., description="The account's number, e.g. 3141-5926-5359.")
name: str = Field(..., description="The account's company name.")
[docs]
class ConsoleOnboarding(ConsoleSessionModel):
"""The state of the console's onboarding hints for the user."""
enabled: bool = Field(..., description="Whether hints show by themselves.")
seen: list[str] = Field(..., description="The hints that the user has seen, which no longer show by themselves.")
[docs]
class ConsoleWelcome(ConsoleSessionModel):
"""The state of the welcome dialog for the user."""
show_at_startup: bool = Field(..., description="Whether the dialog opens by itself each time the user signs in.")
show: bool = Field(
..., description="Whether it opens by itself now: it shows at startup, and hasn't been closed in this session."
)
[docs]
class ConsoleBadges(ConsoleSessionModel):
"""The counts that the sidebar shows beside its items."""
extension_updates: int = Field(
..., description="Installed extensions with an update; 0 for a user who isn't a superuser."
)
[docs]
class ConsoleSession(ConsoleSessionModel):
"""Everything that the console needs to start, for the request's user, or for a visitor who isn't signed in."""
is_authenticated: bool = Field(..., description="Whether the request has a signed-in user.")
version: str = Field(..., description="The platform's version.")
branding: ConsoleBranding
sign_in: ConsoleSignIn
language: ConsoleLanguage
cookies: ConsoleCookies
flags: ConsoleFlags
sam_kinds: list[str] = Field(
...,
description=(
"Every SAM kind, sorted by name, e.g. LLMClient: the docs pages list each one's example manifest "
"and JSON Schema."
),
)
user: Optional[ConsoleUser] = Field(..., description="The signed-in user, or null.")
account: Optional[ConsoleAccount] = Field(..., description="The account the console acts for, or null.")
onboarding: Optional[ConsoleOnboarding] = Field(..., description="The onboarding hints' state, or null.")
welcome: Optional[ConsoleWelcome] = Field(..., description="The welcome dialog's state, or null.")
badges: Optional[ConsoleBadges] = Field(..., description="The sidebar's counts, or null.")
sidebar: Optional[ConsoleSidebar] = Field(..., description="The sidebar's links, or null.")
RESPONSE_MODELS: tuple[type[BaseModel], ...] = (ConsoleSession,)
"""What the view sends."""
[docs]
def contract_schema() -> SmarterDictType:
"""
The contract's JSON Schema (draft 2020-12): one definition, in ``$defs``, per model.
It also has the models of the console's account api, :mod:`smarter.apps.account.api.web.contract`,
so that the console generates every type it sends and receives from one schema.
"""
# pylint: disable=import-outside-toplevel
from smarter.apps.account.api.web import contract as account_contract
models: list[tuple[type[BaseModel], JsonSchemaMode]] = []
for model in RESPONSE_MODELS + account_contract.RESPONSE_MODELS:
models.append((model, "serialization"))
for model in account_contract.REQUEST_MODELS:
models.append((model, "validation"))
_, schema = models_json_schema(
models,
title="Smarter web console session contract",
description=(
"What the web console needs to start, from GET /api/web/session/: the user, the account, the "
"platform's branding, its sign-in options, features and languages, and the state of the welcome "
"dialog and onboarding hints; and the requests and responses of its account api, /api/web/account/. "
"Generated from smarter.apps.api.web.session.contract and smarter.apps.account.api.web.contract; "
"do not edit."
),
)
return {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": SCHEMA_ID, **schema}
[docs]
def contract_schema_json() -> str:
"""The contract's JSON Schema, as the text of ``console-session.schema.json``."""
return json.dumps(contract_schema(), indent=2, sort_keys=True) + "\n"
__all__ = [
"ConsoleAccount",
"ConsoleBadges",
"ConsoleBranding",
"ConsoleCookies",
"ConsoleFlags",
"ConsoleLanguage",
"ConsoleLanguageOption",
"ConsoleOnboarding",
"ConsoleSession",
"ConsoleSessionModel",
"ConsoleSidebar",
"ConsoleSignIn",
"ConsoleUser",
"ConsoleWelcome",
"RESPONSE_MODELS",
"SCHEMA_ID",
"SCHEMA_PATH",
"contract_schema",
"contract_schema_json",
]