Struct Session 

pub struct Session { /* private fields */ }

A session in a Honcho workspace.

Wraps the API response and provides methods for metadata, configuration, peer management, messages, and more.

Implementations

impl Session

pub fn id(&self) -> &str

The session’s unique identifier.

Examples

println!("{}", session.id());

pub fn is_active(&self) -> bool

Whether the session is currently active.

Examples

if session.is_active() {
    println!("session is active");
}

pub fn metadata(&self) -> Option<HashMap<String, Value>>

Cached metadata from the last API response.

Examples

if let Some(meta) = session.metadata() {
    println!("{meta:?}");
}

pub fn configuration(&self) -> Option<SessionConfiguration>

Cached configuration from the last API response.

Examples

if let Some(config) = session.configuration() {
    println!("{config:?}");
}

pub fn created_at(&self) -> DateTime<Utc>

When the session was created.

Examples

println!("{}", session.created_at());

pub async fn refresh(&self) -> Result<()>

Refresh the session’s cached metadata and configuration from the server.

Examples

session.refresh().await?;

pub async fn get_metadata(&self) -> Result<HashMap<String, Value>>

Fetch and return the session’s metadata, updating the cache.

Examples

let meta = session.get_metadata().await?;

pub async fn set_metadata(&self, metadata: HashMap<String, Value>) -> Result<()>

Set session metadata on the server and update the cache.

Examples

let mut meta = std::collections::HashMap::new();
meta.insert("topic".into(), "rust".into());
session.set_metadata(meta).await?;

pub async fn get_configuration(&self) -> Result<SessionConfiguration>

Fetch and return session configuration, updating the cache.

Examples

let config = session.get_configuration().await?;

pub async fn set_configuration( &self, configuration: &SessionConfiguration, ) -> Result<()>

Set session configuration on the server and update the cache.

Examples

use honcho_ai::types::session::SessionConfiguration;
let config = SessionConfiguration::default();
session.set_configuration(&config).await?;

pub async fn get_configuration_raw(&self) -> Result<HashMap<String, Value>>

Fetch session configuration as a raw JSON map.

Prefer get_configuration for typed access. Use this when the server returns fields not yet represented in SessionConfiguration.

pub async fn set_configuration_raw( &self, configuration: HashMap<String, Value>, ) -> Result<()>

Set session configuration from a raw JSON map.

Prefer set_configuration for typed access. Use this when you need to send fields not yet represented in SessionConfiguration.

pub async fn add_peer(&self, id: impl Into<String>) -> Result<()>

Add a single peer to this session.

Examples

session.add_peer("alice").await?;

pub async fn add_peers( &self, specs: impl IntoIterator<Item = impl Into<PeerSpec>>, ) -> Result<()>

Add multiple peers to this session.

Examples

session.add_peers(["alice", "bob"]).await?;

pub async fn set_peers( &self, specs: impl IntoIterator<Item = impl Into<PeerSpec>>, ) -> Result<()>

Set the complete peer list for this session (replaces existing).

Examples

session.set_peers(["alice", "bob"]).await?;

pub async fn remove_peers( &self, ids: impl IntoIterator<Item = impl Into<String>>, ) -> Result<()>

Remove peers from this session.

Examples

session.remove_peers(["bob"]).await?;

pub async fn peers(&self) -> Result<Vec<Peer>>

List peers in this session.

This call is all-or-nothing: it walks every page and deserializes each peer. If any single peer fails to deserialize (Peer::from_parts errors), the whole call returns that error and the peers already accumulated from earlier pages are discarded — partial results are never returned.

Examples

let peers = session.peers().await?;
for p in &peers {
    println!("{}", p.id());
}

pub async fn get_peer_configuration( &self, peer_id: &str, ) -> Result<SessionPeerConfig>

Get per-peer configuration for a specific peer in this session.

Examples

let config = session.get_peer_configuration("alice").await?;

pub async fn set_peer_configuration( &self, peer_id: &str, config: &SessionPeerConfig, ) -> Result<()>

Set per-peer configuration for a specific peer in this session.

The peer must already be present in the session. This method does not create or add peers; use Session::add_peer or Session::add_peers first. If the peer is absent, the server may return 404/NotFound.

Examples

use honcho_ai::types::session::SessionPeerConfig;
let config = SessionPeerConfig { observe_me: Some(true), observe_others: Some(false) };
session.set_peer_configuration("alice", &config).await?;

pub async fn add_messages( &self, messages: Vec<MessageCreate>, ) -> Result<Vec<Message>>

Add messages to this session.

If more than 100 messages are provided, they are automatically chunked into batches of 100 and sent as separate requests. On chunk failure the already-sent messages are not rolled back (non-atomic). When a chunk fails after earlier chunks succeeded, the error is a HonchoError::PartialFailure containing the successfully created messages from the earlier chunks.

Examples

let peer = client.peer("alice").build().await?;
let msg = peer.message("Hello!").build()?;
let messages = session.add_messages(vec![msg]).await?;

pub async fn messages(&self) -> Result<Page<MessageResponse, Message>>

List messages in this session with default pagination (no filters, page 1, size 50).

Examples

let page = session.messages().await?;
for msg in page.items() {
    println!("{}", msg.content());
}

pub async fn messages_with_options( &self, filters: Option<HashMap<String, Value>>, page: u64, size: u64, reverse: bool, ) -> Result<Page<MessageResponse, Message>>

List messages in this session with optional filters, page, size, and reverse.

page is 1-based. size must be in 1..=100.

Examples

let page = session.messages_with_options(None, 1, 25, false).await?;
for msg in page.items() {
    println!("{}", msg.content());
}

pub fn upload_file( &self, source: impl Into<FileSource>, ) -> UploadFileBuilder<'_>

Begin a file upload to this session.

The API currently accepts text/plain, application/pdf, and application/json; other MIME types may be rejected by the server.

Returns an UploadFileBuilder. You must call .peer(id) and then .send() to complete the upload.

Example

let messages = session
    .upload_file(FileSource::bytes("doc.pdf", data, "application/pdf"))
    .peer("alice")
    .send()
    .await?;

pub fn upload_file_streamed( &self, filename: impl Into<String>, reader: impl AsyncRead + Send + 'static, content_type: impl Into<String>, ) -> UploadFileBuilder<'_>

Begin a file upload to this session from a streaming reader.

The API currently accepts text/plain, application/pdf, and application/json; other MIME types may be rejected by the server.

The reader is fully buffered into memory before uploading. This is not true streaming — use Session::upload_file with a FileSource::path for filesystem streaming that avoids buffering.

Returns an UploadFileBuilder. You must call .peer(id) and then .send() to complete the upload.

pub async fn delete(&self) -> Result<()>

Delete this session.

Examples

session.delete().await?;

pub async fn clone_session(&self) -> Result<Session>

Clone this session, returning a new Session.

Examples

let cloned = session.clone_session().await?;

pub async fn clone_session_with_message( &self, message_id: &str, ) -> Result<Session>

Clone this session up to (and including) the given message.

Examples

let cloned = session.clone_session_with_message("msg-42").await?;

pub async fn get_message(&self, id: &str) -> Result<Message>

Get a single message by ID.

Examples

let msg = session.get_message("msg-1").await?;
println!("{}", msg.content());

pub async fn update_message( &self, id: &str, metadata: HashMap<String, Value>, ) -> Result<Message>

Update a message’s metadata.

Examples

let mut meta = std::collections::HashMap::new();
meta.insert("edited".into(), true.into());
let msg = session.update_message("msg-1", meta).await?;

pub async fn context(&self) -> Result<SessionContext>

Get the session context with default parameters.

Fetches messages, summary, peer representation, and peer card for this session.

Examples

let ctx = session.context().await?;

pub async fn context_with_options( &self, options: &SessionContextOptions, ) -> Result<SessionContext>

Get the session context with custom parameters.

Examples

use honcho_ai::types::session::SessionContextOptions;
let opts = SessionContextOptions::builder().summary(true).build();
let ctx = session.context_with_options(&opts).await?;

pub fn context_builder(&self) -> SessionContextBuilder

Get a context builder for fine-grained control over session context parameters.

Examples

let ctx = session.context_builder()
    .summary(true)
    .peer_target("alice")
    .search_query("preferences")
    .search_top_k(10)
    .send()
    .await?;

pub async fn summaries(&self) -> Result<SessionSummaries>

Get available summaries for this session.

Returns both short and long summaries if they are available. Summaries are created asynchronously as messages are added.

Examples

let summaries = session.summaries().await?;

pub async fn search(&self, query: &str) -> Result<Vec<Message>>

Search messages within this session (default limit of 10).

Returns Err(HonchoError::Validation) when query is empty.

Examples

let results = session.search("important topic").await?;
for msg in results {
    println!("{}", msg.content());
}

pub async fn search_with_options( &self, options: &MessageSearchOptions, ) -> Result<Vec<Message>>

Search messages within this session with custom options (limit, filters).

Returns Err(HonchoError::Validation) when query is empty.

Examples

use honcho_ai::types::message::MessageSearchOptions;
let opts = MessageSearchOptions::builder().query("topic").limit(20).build();
let results = session.search_with_options(&opts).await?;

pub async fn representation(&self, peer_id: &str) -> Result<String>

Get a peer’s representation scoped to this session.

Uses the peer representation endpoint with session_id filter.

Examples

let rep = session.representation("alice").await?;
println!("{rep}");

pub fn representation_builder( &self, peer_id: impl Into<String>, ) -> SessionRepresentationBuilder

Create a builder for fine-grained representation requests scoped to this session.

Examples

let rep = session.representation_builder("alice")
    .search_query("hobbies")
    .search_top_k(10)
    .send()
    .await?;

pub async fn queue_status( &self, observer_id: Option<&str>, sender_id: Option<&str>, ) -> Result<QueueStatus>

Get the processing queue status for this session.

Examples

let status = session.queue_status(None, None).await?;

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.