Yj\dZddlmZddlZddlZddlmZddlmZmZddl m Z m Z m Z m Z ddlmZmZmZmZmZmZmZmZdd lmZmZdd lmZdd lmZdd lmZdd l m!Z!ddl"m#Z#ddl$m%Z%m&Z&m'Z'ddl(m)Z)m*Z*m+Z+m,Z,er ddl-m.Z.ddl/m0Z0ej1e2Z3ddgZ4GddeeZ5dS)z"Sync Session class for Honcho SDK.) annotationsN)datetime) TYPE_CHECKINGAny) ConfigDictField PrivateAttr validate_call)MessageCreateParamsMessageResponse PeerResponseQueueStatusResponseRepresentationResponseSessionConfigurationSessionPeerConfigSessionResponse)PeerBase SessionBase)routes)Message)MetadataConfigMixin)SyncPage)Peer)SessionContextSessionSummariesSummary)datetime_to_isonormalize_peers_to_dictprepare_file_for_upload resolve_id SessionAio)HonchoSessionrceZdZUdZedZded<edZded<eZded <e dd Z e dd Z d Z ddZ ddZddZddZddZeeddfddZe ddZeed !"edd#d$%edd&fedd'edd(d)dfd.Zedd/fdd2Zedd3fdd4Zedd5fdd7Zdd9Zdd=Zdd>Zeedd?fddCZeeddDdEddHZddIZ ddJddNZ!eed !"d eddOdPQeddReddSeddTedUdVedd#dWdXYeddZd[d\Yedd]edd#dWd^Yd_ ddpZ"ddrZ#eedd#ds%eddtedud#dWdvwfdd{Z$eed !"edd|edd}edd~eddeddfddZ%eed !"ddedd#dWeddZd[dedd#dWdddZ&eed !" dddZ'eed !"eddeddfddZ(ddZ)ddZ*xZ+S)r%a Represents a session in Honcho. Sessions are scoped to a set of peers and contain messages/content. They create bidirectional relationships between peers and provide a context for multi-party conversations and interactions. Attributes: id: Unique identifier for this session workspace_id: Workspace ID for scoping operations metadata: Cached metadata for this session. May be stale if not recently fetched. Call get_metadata() for fresh data. configuration: Cached configuration for this session. May be stale if not recently fetched. Call get_configuration() for fresh data. N)defaultdict[str, object] | None _metadataSessionConfiguration | None_configurationz'Honcho'_honchoreturnc|jS)zRCached metadata for this session. May be stale. Use get_metadata() for fresh data.)r)selfs U/home/ubuntu/.hermes/hermes-agent/venv/lib/python3.11/site-packages/honcho/session.pymetadatazSession.metadataCs ~c|jS)z\Cached configuration for this session. May be stale. Use get_configuration() for fresh data.)r+r/s r1 configurationzSession.configurationHs ""r3cL|j|jjSN)r,_ensure_workspace_httpr/s r1_get_http_clientzSession._get_http_clientNs! &&(((|!!r3strc4tj|jSr7)rsessions workspace_idr/s r1_get_fetch_routezSession._get_fetch_routeRst0111r3c@tj|j|jSr7)rsessionr>idr/s r1_get_update_routezSession._get_update_routeUs~d/999r3dict[str, Any]cd|jiS)NrBrBr/s r1_get_fetch_bodyzSession._get_fetch_bodyXsdgr3data+tuple[dict[str, object], dict[str, object]]crtj|}|jpi|jdfS)NT exclude_none)rmodel_validater2r5 model_dumpr0rHrAs r1_parse_responsezSession._parse_response[sG"066%2w'<'G'G(H( (   r3rc8|j|||}t j|}|jpi|_ |j |_ |j S)z Get configuration from the server and update the cache. Returns: A SessionConfiguration object containing the configuration settings. body) r,r8r:postr?rGrrMr2r)r5r+rOs r1get_configurationzSession.get_configurationds &&((($$&&++  ! ! # #$*>*>*@*@,  "066 )/R%3""r3.zConfiguration to set) descriptionr5Nonec||d|di||_dS)z Set configuration on the server and update the cache. Args: configuration: A SessionConfiguration object with configuration settings. r5TrKrRN)r:putrCrNr+)r0r5s r1set_configurationzSession.set_configurationtse ##  " " $ $!=#;#;#;#N#NO $   ,r3 'SessionAio'c$ddlm}||S)a Access async versions of all Session methods. Returns a SessionAio view that provides async versions of all methods while sharing state with this Session instance. Example: ```python session = honcho.session("session-123") # Async operations await session.aio.add_messages(peer.message("Hello")) async for msg in session.aio.messages(): print(msg.content) ``` r r")aior#)r0r#s r1r]z Session.aios&& $#####z$r3T)arbitrary_types_allowed)configr z"Unique identifier for this session) min_lengthrVzHoncho client instancezwOptional metadata dictionary to associate with this session. If set, will get/create session immediately with metadata.zgOptional configuration to set for this session. If set, will get/create session immediately with flags.r2r5 session_idhonchorr2ct||j||_||_||_|||jd|i}|||d<||d|d<|j tj |j|}tj |}|j|_|j|_dSdS) aY Initialize a new Session. Provided metadata and configuration will overwrite any existing data in those locations if given. Args: session_id: Unique identifier for this session within the workspace honcho: Honcho client instance metadata: Optional metadata dictionary to associate with this session. If set, will get/create session immediately with metadata. configuration: Optional configuration to set for this session. If set, will get/create session immediately with flags. )rBr>NrBr2TrKr5rR)super__init__r>r,r)r+r8rNr9rTrr=rrMr2r5) r0rbrcr2r5rSrH session_data __class__s r1rfzSession.__init__s> ,     !+  $(< L * * , , ,$(*#5D##+Z ((5(@(@d(@(S(S_%<$$V_V5H%I%IPT$UUD*9$??L)2DN"."rBrr0ris r1 add_peerszSession.add_peerssd: &&(((   !2DG < <(//      r3zPeers to set for the sessionc|j|jjt j|j|jt|dS)a^ Set the complete peer list for this session. Makes an API call to replace the current peer list with the provided peers. This will remove any peers not in the new list and add any that are missing. Args: peers: Peers to set for the session. Can be: - str: Single peer ID - Peer: Single Peer object - List[Union[Peer, str]]: List of Peer objects and/or peer IDs - tuple[str, SessionPeerConfig]: Single peer ID and SessionPeerConfig - tuple[Peer, SessionPeerConfig]: Single Peer object and SessionPeerConfig - List[tuple[Union[Peer, str], SessionPeerConfig]]: List of Peer objects and/or peer IDs and SessionPeerConfig - Mixed lists with peers and tuples/lists containing peer+config combinations rRN) r,r8r9rYrrlr>rBrrms r1 set_peerszSession.set_peerssd8 &&(((   !2DG < <(//      r3z Peers to remove from the session%str | PeerBase | list[PeerBase | str]c|jt|ts|g}d|D}|jjt j|j|j |dS)a Remove peers from this session. Makes an API call to remove one or more peers from this session. Removed peers will no longer be able to participate in the session unless added back. Args: peers: Peers to remove from the session. Can be: - str: Single peer ID - Peer: Single Peer object - List[Union[Peer, str]]: List of Peer objects and/or peer IDs cJg|] }t|tr|n|j!S) isinstancer;rB).0peers r1 z(Session.remove_peers../s-QQQ4JtS11>DDtwQQQr3rRN) r,r8rulistr9deleterrlr>rB)r0ripeer_idss r1 remove_peerszSession.remove_peerss& &&(((%&& GEQQ5QQQ !!  !2DG < < "     r3 list[Peer]cjjjt jjj}|dg}fd|DS)av Get all peers in this session. Makes an API call to retrieve the list of peer IDs that are currently members of this session. Automatically converts the paginated response into a list for us -- the max number of peers in a session is usually 10. Returns: A list of Peer objects that are members of this session itemschg|].}ttj|jj/Srt)rrrMrBr,)rvrwr0s r1rxz!Session.peers..GsC    ,T225t| D D   r3)r,r8r9getrrlr>rB)r0rH peers_datas` r1riz Session.peers6s &&(((#|155  !2DG < <  !%" 5 5     "    r3rwstr | PeerBasercX|jt|tr|n|j}|jjtj|j |j|}t|d|dS)zC Get the configuration for a peer in this session. observe_others observe_me)rr) r,r8rur;rBr9rrsession_peer_configr>r)r0rwpeer_idrHs r1get_peer_configurationzSession.get_peer_configurationLs &&((($T3//<$$TW|!%%  &t'8$'7 K K  !88$455xx --    r3c:|jt|tr|n|j}i}|j |j|d<|j |j|d<|jjtj |j |j||dS)zC Set the configuration for a peer in this session. NrrrR) r,r8rur;rBrrr9rYrrr>)r0rwr5rrSs r1set_peer_configurationzSession.set_peer_configurationZs &&((($T3//<$$TW!  ' 3%2%AD! "  # /!.!9D    &t'8$'7 K K      r3zMessages to add to the sessionmessages/MessageCreateParams | list[MessageCreateParams] list[Message]c|jt|ts|g}d|D}|jjt j|j|j d|i}d|DS)a Add one or more messages to this session. Makes an API call to store messages in this session. Any message added to a session will automatically add the creating peer to the session if they are not already a member. Args: messages: Messages to add to the session. Can be: - MessageCreateParams: Single MessageCreateParams object - List[MessageCreateParams]: List of MessageCreateParams objects c<g|]}|ddS)jsonT)moderL)rNrvmsgs r1rxz(Session.add_messages..s5   ?BCNNTN : :   r3rrRcZg|](}tjtj|)Srtrfrom_api_responser rMrs r1rxz(Session.add_messages..>     %o&DS&I&I J J   r3) r,r8ruryr9rTrrr>rB)r0r messages_datarHs r1 add_messageszSession.add_messagesms& &&((((D)) " zH  FN   |!&& OD-tw 7 7m,'        r3zDictionary of filter criteria)filtersr"SyncPage[MessageResponse, Message]c jjjt jjjrdind}d ddfd t|tS)a Get messages from this session with optional filtering. Makes an API call to retrieve messages from this session. Results can be filtered based on various criteria. Args: filters: Dictionary of filter criteria. Supported filters include: - peer_id: Filter messages by the peer who created them - metadata: Filter messages by metadata key-value pairs - timestamp_start: Filter messages after a specific timestamp - timestamp_end: Filter messages before a specific timestamp Returns: A list of Message objects matching the specified criteria, ordered by creation time (most recent first) rNrRresponser r-rc*tj|Sr7)rr)rs r1 transformz#Session.messages..transforms,X66 6r3pageintrcjjtjjjrdindd|i}t|tS)Nrr)rSquery) r,r9rTr messages_listr>rBrr )r next_data fetch_nextrr0rs r1rz$Session.messages..fetch_nextsf *//$T%6@@-4>i))$tn0I I :NN Nr3)rr r-r)rrr-r) r,r8r9rTrrr>rBrr )r0rrHrrs`` @@r1rzSession.messagess2 &&(((|!&&  !2DG < <)0:)W%%d'    7 7 7 7 O O O O O O O O Ooy*EEEr3c|j|jjt j|j|jdS)aY Delete this session and all associated data. Makes an API call to permanently delete this session and all related data including: - Messages - Message embeddings - Conclusions - Session-Peer associations - Background processing queue items This action cannot be undone. N)r,r8r9rzrrAr>rBr/s r1rzzSession.deletesH &&((( !!&.1BDG"L"LMMMMMr3) message_idr str | None 'Session'c@|ji}|||d<|jjt j|j|j|r|nd}tj |}t|j|j|j |j S)ay Clone this session, optionally up to a specific message. Makes an API call to create a copy of this session with a new ID. All messages and peers from the original session are copied to the new session. If a message_id is provided, only messages up to and including that message are copied. Args: message_id: Optional message ID to cut off the clone at. If provided, the cloned session will only contain messages up to and including this message. Returns: A new Session object representing the cloned session Example: ```python # Clone entire session cloned = session.clone() # Clone session up to a specific message cloned = session.clone(message_id="msg_abc123") ``` Nrrra) r,r8r9rTr session_cloner>rBrrMr%r2r5)r0rrrHcloneds r1clonez Session.clones< &&((( "  !",E, |!&&  !2DG < < *%%d'  !/55 I L_ .     r3rz2Maximum number of tokens to include in the context)gtrVa5A peer ID to get context for. If given *without* `peer_perspective`, a representation and peer card will be included from the omniscient Honcho-level view of `peer_target`. If given *with* `peer_perspective`, will get the representation and card for `peer_target` *from the perspective of `peer_perspective`*.zA query string (or Message object) used to fetch semantically relevant conclusions. Use this alongside `peer_target` to get a more focused context -- does nothing if `peer_target` is not provided.zA peer ID to get context *from the perspective of*. If given, response will attempt to include representation and card from the perspective of `peer_perspective`. Must be provided with `peer_target`.FzwWhether to limit the representation to this session only. If True, only conclusions from this session will be included.dzSNumber of semantically relevant facts to return when searching with `search_query`.)gelerVgg?zZMaximum semantic distance for search results (0.0-1.0) when searching with `search_query`.zGWhether to include the most frequent conclusions in the representation.z?Maximum number of conclusions to include in the representation.) summarytokens peer_target search_querypeer_perspectivelimit_to_session search_top_ksearch_max_distanceinclude_most_frequentmax_conclusionsrboolr int | Nonerrstr | Message | Nonerrrr float | Noner bool | Nonerrc Z|j||td||tdt|tr|jn|} ||d} ||| d<| | | d<||| d<||| d<||| d <||| d <| | | d <| | | d <|jjtj |j |j | } d}| dr:| d}t|d|d|d|d|d}d| dgD}t|j ||| dr"t| dnd| dS)a Get optimized context for this session within a token limit. Makes an API call to retrieve a curated list of messages that provides optimal context for the conversation while staying within the specified token limit. Uses tiktoken for token counting, so results should be compatible with OpenAI models. Args: summary: Whether to include summary information tokens: Maximum number of tokens to include in the context. Will default to Honcho server configuration if not provided. peer_target: A peer ID to get context for. search_query: A query string for semantic search. peer_perspective: A peer ID to get context from the perspective of. limit_to_session: Whether to limit the representation to this session only. search_top_k: Number of semantically relevant facts to return. search_max_distance: Maximum semantic distance for search results. include_most_frequent: Whether to include the most frequent conclusions. max_conclusions: Maximum number of conclusions to include. Returns: A SessionContext object containing the optimized message history and summary, if available, that maximizes conversational context while respecting the token limit Note: Token counting is performed using tiktoken. For models using different tokenizers, you may need to adjust the token limit accordingly. NzDYou must provide a `peer_target` when `peer_perspective` is providedz@You must provide a `peer_target` when `search_query` is provided)rrrrrrrrrrrrcontentr summary_type created_at token_countrrrrrcZg|](}tjtj|)Srtrrs r1rxz#Session.context..s>     %o&DS&I&I J J   r3rpeer_representation peer_card)rbrrrr)r,r8 ValueErrorrurrr9rrsession_contextr>rBrrr;)r0rrrrrrrrrrsearch_query_textrrHsession_summarysrs r1contextzSession.contexts;Z &&(((  #3#?V   <#;R  %/|W$E$E WL <   0! !   $E(O  ($5E. !  "#.E-  '(8E$ %  #$0E. !  *+>E' ( ,-BE) *  &'6E# $|!%%  "4#4dg > >&    88I   YA%) \?~.\?m, O  xx B//    w#xx-..!DHH-B$C$C D D Dhh{++    r3rcH|j|jjt j|j|j}d}|dr:|d}t|d|d|d|d|d}d}|d r:|d }t|d|d|d|d|d}t|d p|j|| S) a Get available summaries for this session. Makes an API call to retrieve both short and long summaries for this session, if they are available. Summaries are created asynchronously by the backend as messages are added to the session. Returns: A SessionSummaries object containing: - id: The session ID - short_summary: The short summary if available, including metadata - long_summary: The long summary if available, including metadata Note: Summaries may be None if: - Not enough messages have been added to trigger summary generation - The summary generation is still in progress - Summary generation is disabled for this session N short_summaryrrrrrr long_summaryrB)rBrr) r,r8r9rrsession_summariesr>rBrr)r0rHrrrs r1 summarieszSession.summariess6( &&(((|!%%  $T%6 @ @   88O $ $ _%A#) \?~.\?m, M 88N # # ^$A") \?~.\?m, L xx~~('%    r3zThe search query to usezFilters to scope the search zNumber of results to return)r'rrrVrlimitrc|j|jjt j|j|j|||d}d|DS)a1 Search for messages in this session. Makes an API call to search for messages in this session. Args: query: The search query to use filters: Filters to scope the search. See [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters). limit: Number of results to return (1-100, default: 10) Returns: A list of Message objects representing the search results. Returns an empty list if no messages are found. )rrrrRcZg|](}tjtj|)Srtrrs r1rxz"Session.search..rr3)r,r8r9rTrsession_searchr>rB)r0rrrrHs r1searchzSession.searchsz2 &&(((|!&&  !$"3TW = = WuEE'        r3zxFile to upload. Can be a file object, (filename, bytes, content_type) tuple, or (filename, fileobj, content_type) tuple.z9The peer creating the messages (ID string or Peer object)z;Optional metadata dictionary to associate with the messagesz@Optional configuration dictionary to associate with the messageszWOptional created-at timestamp for the messages. Should be an ISO 8601 formatted string.file3tuple[str, bytes, str] | tuple[str, Any, str] | Anydict[str, Any] | Nonerstr | datetime | Nonec|jt|\}}}t|tr|n|j} d| i} |t j|| d<|t j|| d<t|} | | | d<|jj tj |j |jd|||fi| } d| DS) a# Upload file to create message(s) in this session. Accepts a flexible payload: - File objects (opened in binary mode) - (filename, bytes, content_type) tuples - (filename, fileobj, content_type) tuples Files are normalized to (filename, fileobj, content_type) tuples for the HTTP client. Args: file: File to upload. Can be: - a file object (must have .name and .read()) - a tuple (filename, bytes, content_type) - a tuple (filename, fileobj, content_type) peer: The peer who will be attributed as the creator of the messages. Can be a peer ID string or a Peer object. metadata: Optional metadata dictionary to associate with the messages configuration: Optional configuration dictionary to associate with the messages created_at: Optional created-at timestamp for the messages. Should be an ISO 8601 formatted string. Returns: A list of Message objects representing the created messages Note: Supported file types include PDFs, text files, and JSON documents. Large files will be automatically split into multiple messages to fit within message size limits. rNr2r5rr)filesrHcZg|](}tjtj|)Srtrrs r1rxz'Session.upload_file..2rr3)r,r8r rur;rBrdumpsrr9uploadrmessages_uploadr>) r0rrwr2r5rfilename content_bytes content_typeresolved_peer_id data_dictcreated_at_isors r1 upload_filezSession.upload_filesh &&(((1H0M0M--$.dC#8#8E44dg&/0@$A  $(Jx$8$8Ij !  $)-M)B)BIo &(44  %&4Il #<%,,  "4#4dg > >Hm\BC-         r3)rr)targetrrrrrrstr | PeerBase | Nonec~|jt|}t|} d|ji} | r| | d<||| d<||| d<||| d<||| d<||| d<|jjt j|j|| } tj | } | j S) a Get a subset of the representation of the peer in this session. Args: peer: Peer to get the representation of. target: Optional target peer to get the representation of. If provided, queries what `peer` knows about the `target`. search_query: Semantic search query to filter relevant conclusions search_top_k: Number of semantically relevant facts to return search_max_distance: Maximum semantic distance for search results (0.0-1.0) include_most_frequent: Whether to include the most frequent conclusions max_conclusions: Maximum number of conclusions to include Returns: A Representation string Example: ```python # Get peer's representation in this session rep = session.representation('user123') print(rep) # Get what user123 knows about assistant in this session local_rep = session.representation('user123', target='assistant') # Get representation with semantic search searched_rep = session.representation( 'user123', search_query='preferences', search_top_k=10 ) ``` rbrNrrrrrrR) r,r8r!rBr9rTrrr>rrMrepresentation) r0rwrrrrrrr target_idrrHrs r1rzSession.representation7sZ &&(((T""v&& !-tw 7  ('E(O  #$0E. !  #$0E. !  *+>E' ( ,-BE) *  &'6E# $|!&&  &t'8' B B'  *8>>&&r3observersenderrc6|jt|}t|}d|ji}|r||d<|r||d<|jjt j|j|}tj |S)a1 Get the queue processing status, optionally scoped to an observer, sender, and/or session. Args: observer: Optional observer (ID string or Peer object) to scope the status check sender: Optional sender (ID string or Peer object) to scope the status check rb observer_id sender_idr) r,r8r!rBr9rrworkspace_queue_statusr>rrM)r0rrresolved_observer_idresolved_sender_idrrHs r1 queue_statuszSession.queue_status}s &&((()(33'//!-tw 7  8#7E-  4!3E+ |!%%  )$*; < <&  #1$777r3z*The Message object or message ID to updatez&The metadata to update for the messagemessage Message | strdict[str, object]rc>|jt|tr|jn|}|jjtj|j |j|d|i}tj tj |S)ai Update the metadata of a message in this session. Makes an API call to update the metadata of a specific message within this session. Args: message: Either a Message object or a message ID string metadata: The metadata to update for the message Returns: The updated Message object r2rR) r,r8rurrBr9rYrrr>rr rM)r0rr2rrHs r1update_messagezSession.update_messages, &&(((#-gw#?#?LWZZW |!%% N4,dgz B Bh'&  ()G)M)MNNNr3cd|jdS)z Return a string representation of the Session. Returns: A string representation suitable for debugging z Session(id='z')rFr/s r1__repr__zSession.__repr__s*dg))))r3c|jS)z~ Return a human-readable string representation of the Session. Returns: The session's ID rFr/s r1__str__zSession.__str__s wr3)r-r()r-r*)r-r;)r-rD)rHrDr-rI)r-r)r5rr-rW)r-r[) rbr;rcrr2r(r5r*r-rW)rirjr-rW)rirqr-rW)r-r})rwrr-r)rwrr5rr-rW)rrr-r)rr(r-r)r-rW)rrr-r)rrrrrrrrrrrrrrrrrrrrr-r)r-r)rr;rr(rrr-r) rrrwrr2r(r5rrrr-r)rwrrrrrrrrrrrrrr-r;)NN)rrrrr-r)rrr2rr-r),__name__ __module__ __qualname____doc__r r)__annotations__r+r,propertyr2r5r:r?rCrGrPrUr rrZr]rrfrnrpr|rirrrrrzrrrrrrrrrr __classcell__)rhs@r1r%r%.sg +6+d*C*C*CICCCC2=+d2K2K2KNKKKK# G%%%% X###X# """2222::::    #### /4e 3/ / / ,,,,],$   X ,]**TBBBCCC % A+O   eC-EFFF 2=.3U R. . . 6;U B6 6 6 2=2=2=2=2=2=2=DC2=xMRE :M M M ! ! ! ! ! VMRE ;M M M       H8=u ?8 8 8      <    ,         &EJE =E E E ! ! ! ! ]! F-2E =- - - )F)F)F)F)F])FVNNNN&"&- - - - - - ^]**TBBBCCC"U Q$X   #(% P# # # .3U _. . . (-u b( ( ( "' R" " " $)5 m $ $ $ -2E t - - - .3U a. . . ',e Y ' ' ' OO O O O O DCO b3 3 3 3 jU31:STTT,1E ;- - - U12O       ]  D]**TBBBCCCEJE SE E E  %u X   .3U U. . . 05u Z0 0 0 -2E q- - - #N N N N DCN `]**TBBBCCC )-#'#(5!#<#<#<,1E$33,G,G,G-1&+eDQ3&?&?&?C'C'C'C'C'DCC'J]**TBBBCCC+/(,8888DC88]**TBBBCCC"' I" " " ',e E' ' ' OOOODCO<****r3)6r  __future__rrloggingrtypingrrpydanticrrr r api_typesr r rrrrrrbaserrhttprrrmixinsr paginationrrwrrrrrutilsrrr r!r]r#clientr$ getLoggerrlogger__all__r%rtr3r1rs;(("""""" %%%%%%%%BBBBBBBBBBBB                    (''''''''''''' FFFFFFFFFF  8 $ $ ) *[[[[[k.[[[[[r3