Journal API Contract

The Pydantic models of the envelope and the error body of every journaled response, and of a journal entry. See Smarter Journal.

Pydantic models of the Smarter Journal api contract.

They describe the envelope that smarter.lib.journal.http.SmarterJournaledJsonResponse adds to every journaled response, the error body of smarter.lib.journal.http.SmarterJournaledJsonErrorResponse, and a journal entry, a smarter.lib.journal.models.SAMJournal row.

These models are the contract’s single source of truth:

the journaled responses are built from them, by smarter.lib.journal.http,
the JSON Schema in journal-contract.schema.json is generated from them (manage.py export_journal_contract_schema), for the clients that read journaled responses, such as the smarter cli.

The envelope and the error body allow extra fields, because each view adds its own data beside them. The model of a journal entry (SAMJournalApiOrmModel) has exactly the row’s fields. Adding a field is backward compatible. Removing or renaming one that is declared here is not.

smarter.lib.journal.contract.models.CONTRACT_MODELS: tuple[type[BaseModel], ...] = (<class 'smarter.lib.journal.contract.models.SAMJournalApiEnvelope'>, <class 'smarter.lib.journal.contract.models.SAMJournalApiErrorResponse'>, <class 'smarter.lib.journal.contract.models.SAMJournalApiResponse'>, <class 'smarter.lib.journal.contract.models.SAMJournalApiOrmModel'>)

The models whose JSON Schema is exported.

Their dependencies are exported with them.

(
    <class 'smarter.lib.journal.contract.models.SAMJournalApiEnvelope'>,
    <class 'smarter.lib.journal.contract.models.SAMJournalApiErrorResponse'>,
    <class 'smarter.lib.journal.contract.models.SAMJournalApiResponse'>,
    <class 'smarter.lib.journal.contract.models.SAMJournalApiOrmModel'>,
)

smarter.lib.journal.contract.models.JOURNAL_API_MODELS: tuple[type[BaseModel], ...] = (<class 'smarter.lib.journal.contract.models.SAMJournalApiEntry'>, <class 'smarter.lib.journal.contract.models.SAMJournalApiPage'>)

The models whose JSON Schemas the Smarter api’s OpenAPI document includes.

(
    <class 'smarter.lib.journal.contract.models.SAMJournalApiEntry'>,
    <class 'smarter.lib.journal.contract.models.SAMJournalApiPage'>,
)

smarter.lib.journal.contract.models.SAMJournalApiCommand

the choices of SAMJournal.command.

See smarter.lib.journal.enum.SmarterJournalCliCommands.choices().

Type:: A journal entry’s command

alias of Literal[‘apply’, ‘prompt’, ‘chat_config’, ‘delete’, ‘deploy’, ‘describe’, ‘get’, ‘journal’, ‘logs’, ‘example_manifest’, ‘status’, ‘json_schema’, ‘version’, ‘undeploy’, ‘validate’, ‘whoami’, ‘resources’]

class smarter.lib.journal.contract.models.SAMJournalApiEntry(**data)[source]

Bases: SAMJournalApiEntrySummary

A journal entry, as the journal’s REST api returns it by its key: with its request and response documents.

It is the output of smarter.lib.journal.serializers.SAMJournalSerializer, in camelCase. The request document holds the caller’s headers and cookies, including its api key.

classmethod from_model(journal)[source]

The REST api’s model of a journal entry.

Parameters:: journal (SAMJournal) – The journal entry, whose user should be fetched with it.
Returns:: Its model.
Return type:: SAMJournalApiEntry

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiEntrySummary(**data)[source]

Bases: BaseModel

A journal entry, as the journal’s list returns it: without its request and response documents.

It is the output of smarter.lib.journal.serializers.SAMJournalMiniSerializer, in camelCase. Unlike SAMJournalApiOrmModel, its user is the username.

classmethod from_model(journal)[source]

The REST api’s summary of a journal entry.

Parameters:: journal (SAMJournal) – The journal entry, whose user should be fetched with it.
Returns:: Its model.
Return type:: SAMJournalApiEntrySummary

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod summary_fields(journal)[source]

The fields of a journal entry that both of the REST api’s models have.

Parameters:: journal (SAMJournal) – The journal entry, whose user should be fetched with it.
Returns:: The fields, by name.
Return type:: dict

class smarter.lib.journal.contract.models.SAMJournalApiEnvelope(**data)[source]

Bases: SAMJournalApiModel

The fields that every journaled response adds beside the view’s own data.

classmethod build(command, thing)[source]

The envelope of a response, without a journal key.

Parameters:

command (object) – The command that the view passed, e.g. a SmarterJournalCliCommands, a string, or None.
thing (object) – The thing that the view passed, e.g. a SmarterJournalThings, a string, or None.

Returns:

The envelope.

Return type:

SAMJournalApiEnvelope

dump()[source]

The envelope as the JSON keys that a journaled response adds: api and metadata.

The metadata’s key is left out until the journal entry is saved.

Returns:: The envelope’s keys.
Return type:: dict[str, TypeAliasType]

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiErrorBody(**data)[source]

Bases: SAMJournalApiModel

The error of a journaled error response: the same shape for every error of the cli and the other journaled apis.

The field names are the values of smarter.lib.journal.enum.SmarterJournalApiResponseErrorKeys.

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiErrorResponse(**data)[source]

Bases: SAMJournalApiModel

The body of a journaled error response.

SAMJournalApiEnvelope’s api and metadata are added beside error.

dump(include_stack_trace=True)[source]

The error response’s JSON.

Parameters:: include_stack_trace (bool) – Whether the error includes its stacktrace.
Returns:: The response’s error key.
Return type:: dict[str, TypeAliasType]

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type smarter.lib.journal.contract.models.SAMJournalApiJson = _AllowAnyJson]: A value that is stored, and returned, as arbitrary JSON, e.g. a journal entry’s request and response documents.

class smarter.lib.journal.contract.models.SAMJournalApiMetadata(**data)[source]

Bases: SAMJournalApiModel

The metadata of a journaled response: its command and thing, and, when the journal is enabled, the key of its journal entry.

command and thing are the strings of the values that the view passed, which may be "None" when it passed none, so they are not limited to the journal’s choices.

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiModel(**data)[source]

Bases: BaseModel

Base class of the contract’s models of responses, which allow extra fields.

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiOrmModel(**data)[source]

Bases: BaseModel

A journal entry: a smarter.lib.journal.models.SAMJournal row.

Its fields are exactly the row’s fields, so extra fields are forbidden. It is built from the row by from_model().

classmethod from_model(journal)[source]

The model of a journal entry.

Parameters:: journal (SAMJournal) – The journal entry.
Returns:: Its model.
Return type:: SAMJournalApiOrmModel

model_config = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiPage(**data)[source]

Bases: BaseModel

One page of the journal’s entries, newest first unless sorted, and a description of the page.

model_config = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class smarter.lib.journal.contract.models.SAMJournalApiResponse(**data)[source]

Bases: SAMJournalApiEnvelope

A journaled response: the envelope, beside the view’s own data, e.g. data or error.

model_config = {'extra': 'allow'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

smarter.lib.journal.contract.models.SAMJournalApiThing

the choices of SAMJournal.thing.

See smarter.lib.journal.enum.SmarterJournalThings.choices().

Type:: A journal entry’s thing

alias of Literal[‘Account’, ‘ApiConnection’, ‘ApiPlugin’, ‘SmarterAuthToken’, ‘Budget’, ‘CustomDomain’, ‘Guardrail’, ‘ImageSearchPlugin’, ‘LLMClient’, ‘MCPClient’, ‘Orchestrator’, ‘Prompt’, ‘ChatConfig’, ‘Proxy’, ‘Provider’, ‘Secret’, ‘SkillPlugin’, ‘SqlConnection’, ‘SqlPlugin’, ‘Plugin’, ‘User’, ‘Vectorsearch’, ‘Vectorstore’, ‘WebsearchPlugin’]

The JSON Schema of the Smarter Journal api contract, generated from its Pydantic models.

manage.py export_journal_contract_schema writes it to journal-contract.schema.json, beside this module, and a test fails if the committed file is out of date.

smarter.lib.journal.contract.schema.journal_contract_schema()[source]

The contract’s JSON Schema (draft 2020-12): one definition, in $defs, per model.

Returns:: The schema.
Return type:: dict[str, Any]

smarter.lib.journal.contract.schema.journal_contract_schema_json()[source]

The contract’s JSON Schema, as the text of journal-contract.schema.json.

Returns:: The schema, as indented JSON, with a final newline.
Return type:: str

smarter.lib.journal.contract.schema.write_journal_contract_schema(path='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/lib/journal/contract/journal-contract.schema.json')[source]

Write the contract’s JSON Schema.

Parameters:: path (str) – The file to write. Defaults to journal-contract.schema.json, beside this module.
Returns:: The path that was written.
Return type:: str