Merge pull request #2267 from tisnik/lcore-3229-updated-models-docs

LCORE-3229: Updated models docs

Author: tisnik

Makefile

@@ -212,7 +212,7 @@ doc:	generate-documentation	## Generate or regenerated content of the whole /doc
 devel-doc:	## Generate documentation for developers
 	scripts/gen_doc.py
 
-docs/models:	docs/models/requests.puml docs/models/responses.puml docs/models/database.puml docs/models/common.puml	## Generate documentation about models
+docs/models:	docs/models/requests.puml docs/models/responses.puml docs/models/database.puml docs/models/common.puml docs/models/requests.svg docs/models/responses.svg docs/models/database.svg docs/models/common.svg	## Generate documentation about models
 	rm -f docs/models/packages.puml
 
 docs/models/requests.puml: ## Generate PlantUML class diagram for requests data models

docs/models/common.puml

@@ -10,23 +10,24 @@ class "AgentTurnAccumulator" as src.models.common.agents.turn_accumulator.AgentT
   seen_docs : set[tuple[str, str]]
   text_parts : list[str]
   tool_round : int
-  turn_summary : TurnSummary
+  turn_summary
   vector_store_ids : Final[list[str]]
   increment_round_if_pending() -> None
 }
 class "Attachment" as src.models.common.query.Attachment {
-  attachment_type : Optional[str]
-  content : Optional[str]
-  content_type : Optional[str]
+  attachment_type : str
+  content : str
+  content_type : str
   model_config : dict
+  validate_image_attachment() -> Self
 }
 class "ConversationData" as src.models.common.conversation.ConversationData {
   conversation_id : str
   last_message_timestamp : float
   topic_summary : Optional[str]
 }
 class "ConversationDetails" as src.models.common.conversation.ConversationDetails {
-  conversation_id : Optional[str]
+  conversation_id : str
   created_at : Optional[str]
   last_message_at : Optional[str]
   last_used_model : Optional[str]
@@ -35,13 +36,13 @@ class "ConversationDetails" as src.models.common.conversation.ConversationDetail
   topic_summary : Optional[str]
 }
 class "ConversationTurn" as src.models.common.conversation.ConversationTurn {
-  completed_at : Optional[str]
-  messages : Optional[list[Message]]
-  model : Optional[str]
-  provider : Optional[str]
-  started_at : Optional[str]
-  tool_calls : Optional[list[ToolCallSummary]]
-  tool_results : Optional[list[ToolResultSummary]]
+  completed_at : str
+  messages : list[Message]
+  model : str
+  provider : str
+  started_at : str
+  tool_calls : list[ToolCallSummary]
+  tool_results : list[ToolResultSummary]
 }
 class "EndEventData" as src.models.common.agents.stream_payloads.EndEventData {
   input_tokens : int
@@ -86,39 +87,39 @@ class "InterruptedStreamPayload" as src.models.common.agents.stream_payloads.Int
   create() -> Self
 }
 class "MCPListToolsSummary" as src.models.common.turn_summary.MCPListToolsSummary {
-  server_label : Optional[str]
-  tools : Optional[list[ToolInfoSummary]]
+  server_label : str
+  tools : list[ToolInfoSummary]
 }
 class "MCPServerAuthInfo" as src.models.common.mcp.MCPServerAuthInfo {
-  client_auth_headers : Optional[list[str]]
-  name : Optional[str]
+  client_auth_headers : list[str]
+  name : str
 }
 class "MCPServerInfo" as src.models.common.mcp.MCPServerInfo {
-  name : Optional[str]
-  provider_id : Optional[str]
-  source : Optional[str]
-  url : Optional[str]
+  name : str
+  provider_id : str
+  source : str
+  url : str
 }
 class "Message" as src.models.common.conversation.Message {
-  content : Optional[str]
+  content : str
   referenced_documents : Optional[list[ReferencedDocument]]
-  type : Optional[Literal['user', 'assistant', 'system', 'developer']]
+  type : Literal['user', 'assistant', 'system', 'developer']
 }
 class "ProviderHealthStatus" as src.models.common.health.ProviderHealthStatus {
   message : Optional[str]
-  provider_id : Optional[str]
-  status : Optional[str]
+  provider_id : str
+  status : str
 }
 class "RAGChunk" as src.models.common.turn_summary.RAGChunk {
   attributes : Optional[dict[str, Any]]
-  content : Optional[str]
+  content : str
   score : Optional[float]
   source : Optional[str]
 }
 class "RAGContext" as src.models.common.turn_summary.RAGContext {
-  context_text : Optional[str]
-  rag_chunks : Optional[list[RAGChunk]]
-  referenced_documents : Optional[list[ReferencedDocument]]
+  context_text : str
+  rag_chunks : list[RAGChunk]
+  referenced_documents : list[ReferencedDocument]
 }
 class "ReferencedDocument" as src.models.common.turn_summary.ReferencedDocument {
   doc_title : Optional[str]
@@ -127,12 +128,12 @@ class "ReferencedDocument" as src.models.common.turn_summary.ReferencedDocument
   source : Optional[str]
 }
 class "ResponseGeneratorContext" as src.models.common.responses.contexts.ResponseGeneratorContext {
-  client : AsyncLlamaStackClient
+  client
   conversation_id : str
-  inline_rag_context : RAGContext
+  inline_rag_context
   model_id : str
   moderation_result
-  query_request : QueryRequest
+  query_request
   rag_id_mapping : dict[str, str]
   request_id : str
   skip_userid_check : bool
@@ -141,24 +142,24 @@ class "ResponseGeneratorContext" as src.models.common.responses.contexts.Respons
   vector_store_ids : list[str]
 }
 class "ResponsesApiParams" as src.models.common.responses.responses_api_params.ResponsesApiParams {
-  conversation : Optional[str]
+  conversation : str
   extra_headers : Optional[dict[str, str]]
   include : Optional[list[IncludeParameter]]
-  input : Optional[ResponseInput]
+  input
   instructions : Optional[str]
   max_infer_iters : Optional[int]
   max_output_tokens : Optional[int]
   max_tool_calls : Optional[int]
   metadata : Optional[dict[str, str]]
-  model : Optional[str]
-  omit_conversation : Optional[bool]
+  model : str
+  omit_conversation : bool
   parallel_tool_calls : Optional[bool]
   previous_response_id : Optional[str]
   prompt : Optional[Prompt]
   reasoning : Optional[Reasoning]
   safety_identifier : Optional[str]
-  store : Optional[bool]
-  stream : Optional[bool]
+  store : bool
+  stream : bool
   temperature : Optional[float]
   text : Optional[Text]
   tool_choice : Optional[ToolChoice]
@@ -167,40 +168,40 @@ class "ResponsesApiParams" as src.models.common.responses.responses_api_params.R
   model_dump() -> dict[str, Any]
 }
 class "ResponsesContext" as src.models.common.responses.contexts.ResponsesContext {
-  auth : Optional[tuple[str, str, bool, str]]
+  auth : tuple[str, str, bool, str]
   background_tasks : Optional[BackgroundTasks]
-  client : Optional[AsyncLlamaStackClient]
+  client
   compacted_original_input : Optional[ResponseInput]
-  endpoint_path : Optional[str]
-  filter_server_tools : Optional[bool]
-  generate_topic_summary : Optional[bool]
-  inline_rag_context : Optional[RAGContext]
-  input_text : Optional[str]
-  model_config : ConfigDict
-  moderation_result : Optional[ShieldModerationResult]
-  rh_identity_context : Optional[tuple[str, str]]
-  started_at : Optional[datetime]
+  endpoint_path : str
+  filter_server_tools : bool
+  generate_topic_summary : bool
+  inline_rag_context
+  input_text : str
+  model_config
+  moderation_result
+  rh_identity_context : tuple[str, str]
+  started_at : datetime
   user_agent : Optional[str]
 }
 class "ResponsesConversationContext" as src.models.common.responses.responses_conversation_context.ResponsesConversationContext {
-  conversation : Optional[str]
-  generate_topic_summary : Optional[bool]
-  model_config : ConfigDict
+  conversation : str
+  generate_topic_summary : bool
+  model_config
   user_conversation : Optional[UserConversation]
 }
 class "ShieldModerationBlocked" as src.models.common.moderation.ShieldModerationBlocked {
   decision : Literal['blocked']
   message : str
   moderation_id : str
-  refusal_response : OpenAIResponseMessage
+  refusal_response
 }
 class "ShieldModerationPassed" as src.models.common.moderation.ShieldModerationPassed {
   decision : Literal['passed']
 }
 class "SolrVectorSearchRequest" as src.models.common.query.SolrVectorSearchRequest {
   filters : Optional[dict[str, Any]]
   mode : Optional[Literal['semantic', 'hybrid', 'lexical']]
-  model_config : ConfigDict
+  model_config
   coerce_legacy_plain_dict(data: Any) -> Any
 }
 class "StartEventData" as src.models.common.agents.stream_payloads.StartEventData {
@@ -213,7 +214,7 @@ class "StartStreamPayload" as src.models.common.agents.stream_payloads.StartStre
   create() -> Self
 }
 class "StreamPayloadBase" as src.models.common.agents.stream_payloads.StreamPayloadBase {
-  model_config : ConfigDict
+  model_config
   serialize_json() -> str
   serialize_text() -> str
 }
@@ -228,42 +229,42 @@ class "TokenStreamPayload" as src.models.common.agents.stream_payloads.TokenStre
   serialize_text() -> str
 }
 class "ToolCallStreamPayload" as src.models.common.agents.stream_payloads.ToolCallStreamPayload {
-  data : ToolCallSummary
+  data
   event : Literal['tool_call']
   serialize_text() -> str
 }
 class "ToolCallSummary" as src.models.common.turn_summary.ToolCallSummary {
-  args : Optional[dict[str, Any]]
-  id : Optional[str]
-  name : Optional[str]
-  type : Optional[str]
+  args : dict[str, Any]
+  id : str
+  name : str
+  type : str
 }
 class "ToolInfoSummary" as src.models.common.turn_summary.ToolInfoSummary {
   description : Optional[str]
   input_schema : Optional[dict[str, Any]]
-  name : Optional[str]
+  name : str
 }
 class "ToolResultStreamPayload" as src.models.common.agents.stream_payloads.ToolResultStreamPayload {
-  data : ToolResultSummary
+  data
   event : Literal['tool_result']
   serialize_text() -> str
 }
 class "ToolResultSummary" as src.models.common.turn_summary.ToolResultSummary {
-  content : Optional[str]
-  id : Optional[str]
-  round : Optional[int]
-  status : Optional[str]
-  type : Optional[str]
+  content : str
+  id : str
+  round : int
+  status : str
+  type : str
 }
 class "Transcript" as src.models.common.transcripts.Transcript {
-  attachments : Optional[list[dict[str, Any]]]
+  attachments : list[dict[str, Any]]
   llm_response : str
   metadata
   query_is_valid : bool
-  rag_chunks : Optional[list[dict[str, Any]]]
+  rag_chunks : list[dict[str, Any]]
   redacted_query : str
-  tool_calls : Optional[list[dict[str, Any]]]
-  tool_results : Optional[list[dict[str, Any]]]
+  tool_calls : list[dict[str, Any]]
+  tool_results : list[dict[str, Any]]
   truncated : bool
 }
 class "TranscriptMetadata" as src.models.common.transcripts.TranscriptMetadata {
@@ -281,16 +282,16 @@ class "TurnCompleteStreamPayload" as src.models.common.agents.stream_payloads.Tu
   create() -> Self
 }
 class "TurnSummary" as src.models.common.turn_summary.TurnSummary {
-  id : Optional[str]
+  id : str
   llm_response : str
-  next_chunk_id : Optional[int]
-  output_items : Optional[list[OpenAIResponseOutput]]
-  partial_tokens : Optional[list[str]]
-  rag_chunks : Optional[list[RAGChunk]]
-  referenced_documents : Optional[list[ReferencedDocument]]
-  token_usage : Optional[TokenCounter]
-  tool_calls : Optional[list[ToolCallSummary]]
-  tool_results : Optional[list[ToolResultSummary]]
+  next_chunk_id : int
+  output_items : list[OpenAIResponseOutput]
+  partial_tokens : list[str]
+  rag_chunks : list[RAGChunk]
+  referenced_documents : list[ReferencedDocument]
+  token_usage
+  tool_calls : list[ToolCallSummary]
+  tool_results : list[ToolResultSummary]
 }
 src.models.common.agents.stream_payloads.EndStreamPayload --|> src.models.common.agents.stream_payloads.StreamPayloadBase
 src.models.common.agents.stream_payloads.ErrorStreamPayload --|> src.models.common.agents.stream_payloads.StreamPayloadBase
@@ -300,11 +301,11 @@ src.models.common.agents.stream_payloads.TokenStreamPayload --|> src.models.comm
 src.models.common.agents.stream_payloads.ToolCallStreamPayload --|> src.models.common.agents.stream_payloads.StreamPayloadBase
 src.models.common.agents.stream_payloads.ToolResultStreamPayload --|> src.models.common.agents.stream_payloads.StreamPayloadBase
 src.models.common.agents.stream_payloads.TurnCompleteStreamPayload --|> src.models.common.agents.stream_payloads.StreamPayloadBase
-src.models.common.agents.stream_payloads.EndStreamPayload --> src.models.common.agents.stream_payloads.EndEventData : data
-src.models.common.agents.stream_payloads.ErrorStreamPayload --> src.models.common.agents.stream_payloads.ErrorEventData : data
-src.models.common.agents.stream_payloads.InterruptedStreamPayload --> src.models.common.agents.stream_payloads.InterruptedEventData : data
-src.models.common.agents.stream_payloads.StartStreamPayload --> src.models.common.agents.stream_payloads.StartEventData : data
-src.models.common.agents.stream_payloads.TokenStreamPayload --> src.models.common.agents.stream_payloads.TokenChunkData : data
-src.models.common.agents.stream_payloads.TurnCompleteStreamPayload --> src.models.common.agents.stream_payloads.TokenChunkData : data
-src.models.common.transcripts.Transcript --> src.models.common.transcripts.TranscriptMetadata : metadata
+src.models.common.agents.stream_payloads.EndEventData --* src.models.common.agents.stream_payloads.EndStreamPayload : data
+src.models.common.agents.stream_payloads.ErrorEventData --* src.models.common.agents.stream_payloads.ErrorStreamPayload : data
+src.models.common.agents.stream_payloads.InterruptedEventData --* src.models.common.agents.stream_payloads.InterruptedStreamPayload : data
+src.models.common.agents.stream_payloads.StartEventData --* src.models.common.agents.stream_payloads.StartStreamPayload : data
+src.models.common.agents.stream_payloads.TokenChunkData --* src.models.common.agents.stream_payloads.TokenStreamPayload : data
+src.models.common.agents.stream_payloads.TokenChunkData --* src.models.common.agents.stream_payloads.TurnCompleteStreamPayload : data
+src.models.common.transcripts.TranscriptMetadata --* src.models.common.transcripts.Transcript : metadata
 @enduml