iQ xSrSSKJr SSKrSSKJr SSKJr SSKJr SSK J r J r J r SSK JrJrJrJrJrJrJrJrJr \"S \ S 9r\"S \\ \4S 9r\\S \4r\\\\S \44r"SS\ \\5r"SS\ \\5r"SS\ 5r\\\\\\\4\ \44r!S\\\4S\!4Sjr"S1r#04S\S\\\4S\\\\\4\ \44Sjjr$"SS\ \\5r%"SS\&5r'S\!S\\(4S jr)S!\\\\\4\ \4S\*\(\+44S"jr,"S#S$\ \\5r-"S%S&\ \\5r.g)'a Agent Data API Schema Definitions This module provides typed wrappers around the raw LlamaCloud agent data API, enabling type-safe interactions with agent-generated structured data. The agent data API serves as a persistent storage system for structured data produced by LlamaCloud agents (particularly extraction agents). It provides CRUD operations, search capabilities, filtering, and aggregation functionality for managing agent-generated data at scale. Key Concepts: - Agent Slug: Unique identifier for an agent instance - Collection: Named grouping of data within an agent (defaults to "default"). Data within a collection should be of the same type. - Agent Data: Individual structured data records with metadata and timestamps Example Usage: ```python from pydantic import BaseModel class Person(BaseModel): name: str age: int client = AsyncAgentDataClient( client=async_llama_cloud, type=Person, collection="people", agent_url_id="my-extraction-agent-xyz" ) # Create typed data person = Person(name="John", age=30) result = await client.create_agent_data(person) print(result.data.name) # Type-safe access ``` )datetimeN) ExtractRun) AgentData)AggregateGroup) BaseModelFieldValidationError) GenericListLiteralOptionalDictTypeTypeVarUnionAny AgentDataT)bound ExtractedT)erroracceptedrejectedpending_review)gtgteltlteeqincludesc\rSrSr%Sr\"SS9r\\\ S'\"SS9r \\ S'\"SS9r \\\ S '\"S S9r \ \ S '\"S S9r\\\ S '\"SS9r\\\ S'\S\S\\ SS4Sj5rSrg)TypedAgentDataHaM Type-safe wrapper for agent data records. This class represents a single data record stored in the agent data API, combining the structured data payload with metadata about when and where it was created. Attributes: id: Unique identifier for this data record agent_url_id: Identifier of the agent that created this data collection: Named collection within the agent (used for organization) data: The actual structured data payload (typed as AgentDataT) created_at: Timestamp when the record was first created updated_at: Timestamp when the record was last modified Example: ```python # Access typed data person_data: TypedAgentData[Person] = await client.get_agent_data(id) print(person_data.data.name) # Type-safe access to Person fields print(person_data.created_at) # Access metadata ``` z&Unique identifier for this data record descriptionidz.Identifier of the agent that created this data agent_url_idz7Named collection within the agent for data organization collectionzThe structured data payloaddatazWhen this record was created created_atz"When this record was last modified updated_atraw_data validatorreturnzTypedAgentData[AgentDataT]c URUR5nU"URURURUUR UR S9$)z Convert raw API response to typed agent data. Args: raw_data: Raw agent data from the API validator: Pydantic model class to validate the data field Returns: TypedAgentData instance with validated data )r%r&r'r(r)r*)model_validater(r% agent_slugr'r)r*)clsr+r,r(s e/home/james-whalen/.local/lib/python3.13/site-packages/llama_cloud_services/beta/agent_data/schema.pyfrom_rawTypedAgentData.from_rawnsS%33HMMB{{!,,******   N)__name__ __module__ __qualname____firstlineno____doc__rr%r str__annotations__r&r'r(rr)rr* classmethodrrr3__static_attributes__r6r5r2r!r!Hs0*RSB SDL#!&M!J )FGD*G%*7U%VJ"V%*8&J"   -1*-= %  r5r!cn\rSrSr%Sr\"SS9r\\\ \ S'\"SS9r \ \ \ S'\"SS9r\\ S 'S rg ) TypedAgentDataItemsa Paginated collection of agent data records. This class represents a page of search results from the agent data API, providing both the data records and pagination metadata. Attributes: items: List of agent data records in this page total: Total number of records matching the query (only present if requested) has_more: Whether there are more records available beyond this page Example: ```python # Search with pagination results = await client.search( page_size=10, include_total=True ) for item in results.items: print(item.data.name) if results.has_more: # Load next page next_page = await client.search( page_size=10, offset=10 ) ``` z'List of agent data records in this pager#itemszFTotal number of records matching the query (only present if requested)totalz9Whether there are more records available beyond this pagehas_morer6N)r7r8r9r:r;rrCr r!rr=rDr intrEboolr?r6r5r2rArAsW>/4=/E4z* +!\E8C=OHdr5rAc\rSrSr%Sr\"SSS9r\\\ S'\"SSS9r \\ \ S'\"SS S9r \\ \ S '\"SS S9r \\\ S '\"SS S9r\\\ S'Srg)ExtractedFieldMetadatazU Metadata for an extracted data field, such as confidence, and citation information. Nz_symbol for how the citation/confidence was derived: 'INFERRED FROM TEXT', 'VERBATIM EXTRACTION'r# reasoningzRThe confidence score for the field, combined with parsing confidence if applicable confidencezCThe confidence score for the field based on the extracted text onlyextraction_confidencez*The page number that the field occurred on page_numberz5The original text this field's value was derived from matching_textr6)r7r8r9r:r;rrKr r<r=rLfloatrMrNrFrOr?r6r5r2rIrIs % u Ix}#( h#J.3 Y.8E?"' F"K#$) K$M8C=r5rIfield_metadatar-cUR5VVs0sHupU[;dMU[U5_M snn$s snnf)N)rC _METADATA_FIELDS_SIBLING_TO_LEAF)_parse_extracted_field_metadata_recursive)rQkvs r2parse_extracted_field_metadatarWsJ #((* *DA 4 4 8 4Q 77*  s<<rK field_valueadditional_fieldsc [U[5(aU$[U[5(Ga<1Skn[UR UR 555S:a0UEUEn[R U5nSU;a}[US5S:akUSSnSU;a5[US[R5(a[US5Ul SU;a"[US[5(a USUl U$UR5VVs0sHupgU[;dMXg_M nnnUR5VVs0sHupgU[;dMU[!Xq5_M snn$[U["5(aUVs/sHn[!U5PM sn$[%SUS35e![a Nf=fs snnfs snnfs snf)zX Parse the extracted field metadata into a dictionary of field names to field metadata. >citationrLrMrr[pagerOzInvalid field value: z0. Expected ExtractedFieldMetadata, dict, or list) isinstancerIdictlen intersectionkeysr/numbersNumberrFrNr<rOr rCrSrTlist ValueError) rXrYindicator_fieldsmerged validatedfirst_citationrUrVitems r2rTrTs+566 K & &O ,,[-=-=-?@ AA E =K=+<=2AA&I ,[5L1MPQ1Q%0%>3A2Q /  $))+ +44 AD+  $))+ +88 OA8N N+  K & &LWXKD9$?KXX#K=0` a  #    Ys1BF*F:&F:GGG* F76F7c\rSrSr%Sr\"SS9r\\S'\"SS9r \\S'\"SS9r \ \S '\"S S S9r \ \\S '\"\S S9r\\S'\"S SS9r\ \\S'\"S SS9r\ \\S'\"S SS9r\ \\S'\"\SS9r\ \\\4\S'\S0S S S S 4S\S \ S\S\ \S\ \S\ \S\ \\\4SS4Sjj5r\S S\S\\S\ \S\ \S\ \S \ S\ \\\4SS4Sjj5rSrg )! ExtractedDataiaq Wrapper for extracted data with workflow status tracking. This class is designed for extraction workflows where data goes through review and approval stages. It maintains both the original extracted data and the current state after any modifications. Attributes: original_data: The data as originally extracted from the source data: The current state of the data (may differ from original after edits) status: Current workflow status (in_review, accepted, rejected, error) confidence: Confidence scores for individual fields (if available) file_id: The llamacloud file ID of the file that was used to extract the data file_name: The name of the file that was used to extract the data file_hash: A content hash of the file that was used to extract the data, for de-duplication Status Workflow: - "pending_review": Initial state, awaiting human review - "accepted": Data approved and ready for use - "rejected": Data rejected, needs re-extraction or manual fix - "error": Processing error occurred Example: ```python # Create extracted data for review extracted = ExtractedData.create( data=person_data, status="pending_review", confidence={"name": 0.95, "age": 0.87} ) # Later, after review if extracted.status == "accepted": # Use the data process_person(extracted.data) ``` z6The original data that was extracted from the documentr# original_datazBThe latest state of the data. Will differ if data has been updatedr(z The status of the extracted datastatusNz3The overall confidence score for the extracted dataoverall_confidencezPage links, and perhaps eventually bounding boxes, for individual fields in the extracted data. Structure is expected to have a )default_factoryr$rQz4The ID of the file that was used to extract the datafile_idz6The name of the file that was used to extract the data file_namez6The hash of the file that was used to extract the data file_hashzJAdditional metadata about the extracted data, such as errors, tokens, etc.metadatarr-zExtractedData[ExtractedT]c X[U5nU"UUUU[U5UUUU=(d 0S9 $)ay Create a new ExtractedData instance with sensible defaults. Args: extracted_data: The extracted data payload status: Initial workflow status field_metadata: Optional confidence scores, citations, and other metadata for fields file_id: The llamacloud file ID of the file that was used to extract the data file_name: The name of the file that was used to extract the data file_hash: A content hash of the file that was used to extract the data, for de-duplication metadata: Arbitrary additional application-specific data about the extracted data Returns: New ExtractedData instance ready for storage ) rmr(rnrQrorqrrrsrt)rWcalculate_overall_confidence) r1r(rnrQrqrrrsrtnormalized_field_metadatas r2createExtractedData.createWsB4%C>$R!4;rxrrrr?r6r5r2rlrls$L!&L!M:XD*+MNFJN*/ I+27W2N.# PGXc] % R Ix} % R Ix}*/`*HhtCH~& .57!%#'#'-1$ $ $ 3 $ # $ C= $ C=$ 4S>*$  %$ $ L $(#'!%--1,=,=Z ,=C= ,= C= ,= # ,=,=4S>*,= %,=,=r5rlcD^\rSrSrSrS\\\\44U4Sjjr Sr U=r $)rizJ Exception raised when the extracted data does not conform to the schema. rc0>Xl[TU] S5 g)Nz;Not able to parse the extracted data, parsed invalid format)rsuper__init__)selfr __class__s r2rInvalidExtractionData.__init__s( VWr5)r) r7r8r9r:r;rlrr<rrr? __classcell__)rs@r2rrs)X]4S>%BXXr5rrtc2[U5upUS:XagX- $)@ Calculate the overall confidence score for the extracted data. rN)'_calculate_overall_confidence_recursive)rt numerator denominators r2rvrvs& EXNIa  ""r5rLcj[U[5(aURbURS4$g[U[5(a3SnSnUR 5Hn[ U5upEX- nX%- nM X4$[U[ 5(a%SnSnUHn[ U5upEX- nX%- nM X4$g)r)rrr)r]rIrLr^valuesrrd)rLrrvaluenumdens r2rrs *455  ,((!+ +*d##  &&(E>uEHC  I  K)%% J % %  E>uEHC  I  K %%r5c\rSrSr%Sr\"SS9r\\\ 4\ S'\"SS9r \ \ \ S'\"SS9r\ \\ S '\S \S \\S S 4Sj5rSrg)TypedAggregateGroupiaY Represents a group of agent data records aggregated by common field values. This class is used for grouping and analyzing agent data based on shared characteristics. It's particularly useful for generating summaries and statistics across large datasets. Attributes: group_key: The field values that define this group count: Number of records in this group (if count aggregation was requested) first_item: Representative data record from this group (if requested) Example: ```python # Group by age range groups = await client.aggregate_agent_data( group_by=["age_range"], count=True, first=True ) for group in groups.items: print(f"Age range {group.group_key['age_range']}: {group.count} people") if group.first_item: print(f"Example: {group.first_item.name}") ``` z'The field values that define this groupr# group_keyzDNumber of records in this group (if count aggregation was requested)countz9Representative data record from this group (if requested) first_itemr+r,r-zTypedAggregateGroup[AgentDataT]czURnUbURU5nU"URURUS9$)z Convert raw API response to typed aggregate group. Args: raw_data: Raw aggregate group from the API validator: Pydantic model class to validate the first_item field Returns: TypedAggregateGroup instance with validated first_item )rrr)rr/rr)r1r+r,rs r2r3TypedAggregateGroup.from_raw sE,4+>+>  !"11*=J((..!  r5r6N)r7r8r9r:r;rrrr<rr=rr rFrrr>rrr3r?r6r5r2rrs8!&=!ItCH~!ZE8C=(-O(J$ % 26z2B *  r5rcn\rSrSr%Sr\"SS9r\\\ \ S'\"SS9r \ \ \ S'\"SS9r\\ S 'S rg ) TypedAggregateGroupItemsi#a Paginated collection of aggregate groups. This class represents a page of aggregation results from the agent data API, providing both the grouped data and pagination metadata. Attributes: items: List of aggregate groups in this page total: Total number of groups matching the query (only present if requested) has_more: Whether there are more groups available beyond this page Example: ```python # Get first page of groups results = await client.aggregate_agent_data( group_by=["department"], count=True, page_size=20 ) for group in results.items: dept = group.group_key["department"] print(f"{dept}: {group.count} employees") # Load more if needed if results.has_more: next_page = await client.aggregate_agent_data( group_by=["department"], count=True, page_size=20, offset=20 ) ``` z%List of aggregate groups in this pager#rCzETotal number of groups matching the query (only present if requested)rDz8Whether there are more groups available beyond this pagerEr6N)r7r8r9r:r;rrCr rrr=rDr rFrErGr?r6r5r2rr#sY!F49;4E4#J/ 0![E8C=NHdr5r)/r;rrb llama_cloudrllama_cloud.types.agent_datar!llama_cloud.types.aggregate_grouprpydanticrrr typingr r r r rrrrrrr^rr<rComparisonOperatorr!rArIrdrrWrSrTrl ExceptionrrPrvtuplerFrrrr6r5r2rs$L"2<66   \ 3 \y$)? @ 7LMsR S g@A3F GG = Y 3= @()WZ%8(VY4"%tCH~tCy@ AA cN%0= )+1 1 CH~1  !4S>49 <=1 hX=Iwz2X=vXIX #( # e_ #,d38nd3iGH 5#:>= )WZ%8= @,y'**=,r5