# This file was auto-generated by Fern from our API Definition.

import typing

import pydantic
from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
from .agent_config import AgentConfig
from .cache_directive import CacheDirective


class AtomRequest(UncheckedBaseModel):
    """
    Request shape for the product-agnostic atom API.

    Frontend sends:
    - atoms: Schema definitions for each atom type (JSON Schema format)
    - instructions: Free-form text instructions for the agent
    - context: Product-defined context for cache granularity (optional)

    The context field controls cache granularity:
    - More fields → more specific cache → fewer hits, fresher data
    - Fewer fields → broader cache → more hits, potentially staler

    Platform always injects org_id from the authenticated session.
    Product faces can include user_id in context if per-user caching is desired.
    """

    atoms: typing.Dict[str, typing.Dict[str, typing.Optional[typing.Any]]] = pydantic.Field()
    """
    Schema definitions for each atom type. Keys are atom type names. Values are JSON Schema objects. Used for prompt injection + validation.
    """

    instructions: str = pydantic.Field()
    """
    Free-form text instructions for the agent. Can include markdown, code blocks, structured examples.
    """

    context: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = pydantic.Field(default=None)
    """
    Product-defined context for cache granularity. Platform injects org_id from session. Product can add user_id, page, date, or other fields to control caching.
    """

    cache: typing.Optional[CacheDirective] = pydantic.Field(default=None)
    """
    Client-controlled caching directives
    """

    tools: typing.Optional[typing.List[str]] = pydantic.Field(default=None)
    """
    DEPRECATED: Use agent.tools instead. Additional tool names to enable for the agent. Falls back to this if agent.tools is not set.
    """

    agent: typing.Optional[AgentConfig] = pydantic.Field(default=None)
    """
    Agent configuration overrides (model, temperature, max_tokens, tools).
    """

    if IS_PYDANTIC_V2:
        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
    else:

        class Config:
            frozen = True
            smart_union = True
            extra = pydantic.Extra.allow
