@honcho-ai/core 1.7.0 → 2.0.0

package/src/resources/workspaces/peers/peers.ts

@@ -13,7 +13,7 @@ export class Peers extends APIResource {
   sessions: SessionsAPI.Sessions = new SessionsAPI.Sessions(this._client);
 
   /**
-   * Update a Peer's name and/or metadata
+   * Update a Peer's metadata and/or configuration.
    */
   update(
     workspaceId: string,
@@ -25,7 +25,7 @@ export class Peers extends APIResource {
   }
 
   /**
-   * Get All Peers for a Workspace
+   * Get all Peers for a Workspace, paginated with optional filters.
    */
   list(
     workspaceId: string,
@@ -76,7 +76,9 @@ export class Peers extends APIResource {
   }
 
   /**
-   * Chat
+   * Query a Peer's representation using natural language. Performs agentic search
+   * and reasoning to comprehensively answer the query based on all latent knowledge
+   * gathered about the peer from their messages and conclusions.
    */
   chat(
     workspaceId: string,
@@ -90,39 +92,39 @@ export class Peers extends APIResource {
   /**
    * Get context for a peer, including their representation and peer card.
    *
-   * This endpoint returns the working representation and peer card for a peer. If a
-   * target is specified, returns the context for the target from the observer peer's
-   * perspective. If no target is specified, returns the peer's own context
-   * (self-observation).
+   * This endpoint returns a curated subset of the representation and peer card for a
+   * peer. If a target is specified, returns the context for the target from the
+   * observer peer's perspective. If no target is specified, returns the peer's own
+   * context (self-observation).
    *
    * This is useful for getting all the context needed about a peer without making
    * multiple API calls.
    */
-  getContext(
+  context(
     workspaceId: string,
     peerId: string,
-    query?: PeerGetContextParams,
+    query?: PeerContextParams,
     options?: Core.RequestOptions,
-  ): Core.APIPromise<PeerGetContextResponse>;
-  getContext(
+  ): Core.APIPromise<PeerContextResponse>;
+  context(
     workspaceId: string,
     peerId: string,
     options?: Core.RequestOptions,
-  ): Core.APIPromise<PeerGetContextResponse>;
-  getContext(
+  ): Core.APIPromise<PeerContextResponse>;
+  context(
     workspaceId: string,
     peerId: string,
-    query: PeerGetContextParams | Core.RequestOptions = {},
+    query: PeerContextParams | Core.RequestOptions = {},
     options?: Core.RequestOptions,
-  ): Core.APIPromise<PeerGetContextResponse> {
+  ): Core.APIPromise<PeerContextResponse> {
     if (isRequestOptions(query)) {
-      return this.getContext(workspaceId, peerId, {}, query);
+      return this.context(workspaceId, peerId, {}, query);
     }
     return this._client.get(`/v2/workspaces/${workspaceId}/peers/${peerId}/context`, { query, ...options });
   }
 
   /**
-   * Get a Peer by ID
+   * Get a Peer by ID or create a new Peer with the given ID.
    *
    * If peer_id is provided as a query parameter, it uses that (must match JWT
    * workspace_id). Otherwise, it uses the peer_id from the JWT.
@@ -136,7 +138,29 @@ export class Peers extends APIResource {
   }
 
   /**
-   * Search a Peer
+   * Get a curated subset of a Peer's Representation. A Representation is always a
+   * subset of the total knowledge about the Peer. The subset can be scoped and
+   * filtered in various ways.
+   *
+   * If a session_id is provided in the body, we get the Representation of the Peer
+   * scoped to that Session. If a target is provided, we get the Representation of
+   * the target from the perspective of the Peer. If no target is provided, we get
+   * the omniscient Honcho Representation of the Peer.
+   */
+  representation(
+    workspaceId: string,
+    peerId: string,
+    body: PeerRepresentationParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PeerRepresentationResponse> {
+    return this._client.post(`/v2/workspaces/${workspaceId}/peers/${peerId}/representation`, {
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * Search a Peer's messages, optionally filtered by various criteria.
    */
   search(
     workspaceId: string,
@@ -166,26 +190,6 @@ export class Peers extends APIResource {
       ...options,
     });
   }
-
-  /**
-   * Get a peer's working representation for a session.
-   *
-   * If a session_id is provided in the body, we get the working representation of
-   * the peer in that session. If a target is provided, we get the representation of
-   * the target from the perspective of the peer. If no target is provided, we get
-   * the omniscient Honcho representation of the peer.
-   */
-  workingRepresentation(
-    workspaceId: string,
-    peerId: string,
-    body: PeerWorkingRepresentationParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<PeerWorkingRepresentationResponse> {
-    return this._client.post(`/v2/workspaces/${workspaceId}/peers/${peerId}/representation`, {
-      body,
-      ...options,
-    });
-  }
 }
 
 export class PeersPage extends Page<Peer> {}
@@ -244,7 +248,7 @@ export interface PeerChatResponse {
 /**
  * Context for a peer, including representation and peer card.
  */
-export interface PeerGetContextResponse {
+export interface PeerContextResponse {
   /**
    * The ID of the peer
    */
@@ -261,106 +265,18 @@ export interface PeerGetContextResponse {
   peer_card?: Array<string> | null;
 
   /**
-   * A Representation is a traversable and diffable map of observations. At the base,
-   * we have a list of explicit observations, derived from a peer's messages.
-   *
-   * From there, deductive observations can be made by establishing logical
-   * relationships between explicit observations.
-   *
-   * In the future, we can add more levels of reasoning on top of these.
-   *
-   * All of a peer's observations are stored as documents in a collection. These
-   * documents can be queried in various ways to produce this Representation object.
-   *
-   * Additionally, a "working representation" is a version of this data structure
-   * representing the most recent observations within a single session.
-   *
-   * A representation can have a maximum number of observations, which is applied
-   * individually to each level of reasoning. If a maximum is set, observations are
-   * added and removed in FIFO order.
+   * A curated subset of the representation of the target peer from the observer's
+   * perspective
    */
-  representation?: PeerGetContextResponse.Representation | null;
+  representation?: string | null;
 }
 
-export namespace PeerGetContextResponse {
-  /**
-   * A Representation is a traversable and diffable map of observations. At the base,
-   * we have a list of explicit observations, derived from a peer's messages.
-   *
-   * From there, deductive observations can be made by establishing logical
-   * relationships between explicit observations.
-   *
-   * In the future, we can add more levels of reasoning on top of these.
-   *
-   * All of a peer's observations are stored as documents in a collection. These
-   * documents can be queried in various ways to produce this Representation object.
-   *
-   * Additionally, a "working representation" is a version of this data structure
-   * representing the most recent observations within a single session.
-   *
-   * A representation can have a maximum number of observations, which is applied
-   * individually to each level of reasoning. If a maximum is set, observations are
-   * added and removed in FIFO order.
-   */
-  export interface Representation {
-    /**
-     * Conclusions that MUST be true given explicit facts and premises - strict logical
-     * necessities. Each deduction should have premises and a single conclusion.
-     */
-    deductive?: Array<Representation.Deductive>;
-
-    /**
-     * Facts LITERALLY stated by the user - direct quotes or clear paraphrases only, no
-     * interpretation or inference. Example: ['The user is 25 years old', 'The user has
-     * a dog']
-     */
-    explicit?: Array<Representation.Explicit>;
-  }
-
-  export namespace Representation {
-    /**
-     * Deductive observation with multiple premises and one conclusion, plus metadata.
-     */
-    export interface Deductive {
-      /**
-       * The deductive conclusion
-       */
-      conclusion: string;
-
-      created_at: string;
-
-      message_ids: Array<number>;
-
-      session_name: string;
-
-      /**
-       * Supporting premises or evidence for this conclusion
-       */
-      premises?: Array<string>;
-    }
-
-    /**
-     * Explicit observation with content and metadata.
-     */
-    export interface Explicit {
-      /**
-       * The explicit observation
-       */
-      content: string;
-
-      created_at: string;
-
-      message_ids: Array<number>;
-
-      session_name: string;
-    }
-  }
+export interface PeerRepresentationResponse {
+  representation: string;
 }
 
 export type PeerSearchResponse = Array<MessagesAPI.Message>;
 
-export type PeerWorkingRepresentationResponse = { [key: string]: unknown };
-
 export interface PeerUpdateParams {
   configuration?: { [key: string]: unknown } | null;
 
@@ -376,8 +292,8 @@ export interface PeerListParams extends PageParams {
 
 export interface PeerCardParams {
   /**
-   * The peer whose card to retrieve. If not provided, returns the observer's own
-   * card
+   * Optional target peer to retrieve a card for, from the observer's perspective. If
+   * not provided, returns the observer's own card
    */
   target?: string | null;
 }
@@ -388,6 +304,11 @@ export interface PeerChatParams {
    */
   query: string;
 
+  /**
+   * Level of reasoning to apply: minimal, low, medium, high, or extra-high
+   */
+  reasoning_level?: 'minimal' | 'low' | 'medium' | 'high' | 'extra-high';
+
   /**
    * ID of the session to scope the representation to
    */
@@ -401,20 +322,20 @@ export interface PeerChatParams {
   target?: string | null;
 }
 
-export interface PeerGetContextParams {
+export interface PeerContextParams {
   /**
-   * Whether to include the most derived observations in the representation
+   * Whether to include the most frequent conclusions in the representation
    */
-  include_most_derived?: boolean;
+  include_most_frequent?: boolean;
 
   /**
-   * Maximum number of observations to include in the representation
+   * Maximum number of conclusions to include in the representation
    */
-  max_observations?: number | null;
+  max_conclusions?: number | null;
 
   /**
    * Only used if `search_query` is provided. Maximum distance for semantically
-   * relevant observations
+   * relevant conclusions
    */
   search_max_distance?: number | null;
 
@@ -425,13 +346,13 @@ export interface PeerGetContextParams {
 
   /**
    * Only used if `search_query` is provided. Number of semantic-search-retrieved
-   * observations to include
+   * conclusions to include
    */
   search_top_k?: number | null;
 
   /**
-   * The target peer to get context for. If not provided, returns the peer's own
-   * context (self-observation)
+   * Optional target peer to get context for, from the observer's perspective. If not
+   * provided, returns the observer's own context (self-observation)
    */
   target?: string | null;
 }
@@ -444,74 +365,74 @@ export interface PeerGetOrCreateParams {
   metadata?: { [key: string]: unknown } | null;
 }
 
-export interface PeerSearchParams {
+export interface PeerRepresentationParams {
   /**
-   * Search query
+   * Only used if `search_query` is provided. Whether to include the most frequent
+   * conclusions in the representation
    */
-  query: string;
+  include_most_frequent?: boolean | null;
 
   /**
-   * Filters to scope the search
+   * Only used if `search_query` is provided. Maximum number of conclusions to
+   * include in the representation
    */
-  filters?: { [key: string]: unknown } | null;
+  max_conclusions?: number | null;
 
   /**
-   * Number of results to return
+   * Only used if `search_query` is provided. Maximum distance to search for
+   * semantically relevant conclusions
    */
-  limit?: number;
-}
+  search_max_distance?: number | null;
 
-export interface PeerSetCardParams {
   /**
-   * Body param: The peer card content to set
+   * Optional input to curate the representation around semantic search results
    */
-  peer_card: Array<string>;
+  search_query?: string | null;
 
   /**
-   * Query param: The peer whose card to set. If not provided, sets the observer's
-   * own card
+   * Only used if `search_query` is provided. Number of semantic-search-retrieved
+   * conclusions to include in the representation
    */
-  target?: string | null;
-}
+  search_top_k?: number | null;
 
-export interface PeerWorkingRepresentationParams {
   /**
-   * Only used if `search_query` is provided. Whether to include the most derived
-   * observations in the representation
+   * Optional session ID within which to scope the representation
    */
-  include_most_derived?: boolean | null;
+  session_id?: string | null;
 
   /**
-   * Only used if `search_query` is provided. Maximum number of observations to
-   * include in the representation
+   * Optional peer ID to get the representation for, from the perspective of this
+   * peer
    */
-  max_observations?: number | null;
+  target?: string | null;
+}
 
+export interface PeerSearchParams {
   /**
-   * Only used if `search_query` is provided. Maximum distance to search for
-   * semantically relevant observations
+   * Search query
    */
-  search_max_distance?: number | null;
+  query: string;
 
   /**
-   * Optional input to curate the representation around semantic search results
+   * Filters to scope the search
    */
-  search_query?: string | null;
+  filters?: { [key: string]: unknown } | null;
 
   /**
-   * Only used if `search_query` is provided. Number of semantic-search-retrieved
-   * observations to include in the representation
+   * Number of results to return
    */
-  search_top_k?: number | null;
+  limit?: number;
+}
 
+export interface PeerSetCardParams {
   /**
-   * Get the working representation within this session
+   * Body param: The peer card content to set
    */
-  session_id?: string | null;
+  peer_card: Array<string>;
 
   /**
-   * Optional peer ID to get the representation for, from the perspective of this
-   * peer
+   * Query param: Optional target peer to set a card for, from the observer's
+   * perspective. If not provided, sets the observer's own card
    */
   target?: string | null;
 }
@@ -527,19 +448,19 @@ export declare namespace Peers {
     type PeerCardResponse as PeerCardResponse,
     type SessionGet as SessionGet,
     type PeerChatResponse as PeerChatResponse,
-    type PeerGetContextResponse as PeerGetContextResponse,
+    type PeerContextResponse as PeerContextResponse,
+    type PeerRepresentationResponse as PeerRepresentationResponse,
     type PeerSearchResponse as PeerSearchResponse,
-    type PeerWorkingRepresentationResponse as PeerWorkingRepresentationResponse,
     PeersPage as PeersPage,
     type PeerUpdateParams as PeerUpdateParams,
     type PeerListParams as PeerListParams,
     type PeerCardParams as PeerCardParams,
     type PeerChatParams as PeerChatParams,
-    type PeerGetContextParams as PeerGetContextParams,
+    type PeerContextParams as PeerContextParams,
     type PeerGetOrCreateParams as PeerGetOrCreateParams,
+    type PeerRepresentationParams as PeerRepresentationParams,
     type PeerSearchParams as PeerSearchParams,
     type PeerSetCardParams as PeerSetCardParams,
-    type PeerWorkingRepresentationParams as PeerWorkingRepresentationParams,
   };
 
   export { Sessions as Sessions, type SessionListParams as SessionListParams };

package/src/resources/workspaces/peers/sessions.ts

@@ -9,7 +9,7 @@ import { type PageParams } from "../../../pagination.js";
 
 export class Sessions extends APIResource {
   /**
-   * Get All Sessions for a Peer
+   * Get all Sessions for a Peer, paginated with optional filters.
    */
   list(
     workspaceId: string,

package/src/resources/workspaces/queue.ts

@@ -0,0 +1,111 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from "../../resource.js";
+import { isRequestOptions } from "../../core.js";
+import * as Core from "../../core.js";
+
+export class Queue extends APIResource {
+  /**
+   * Get the processing queue status for a Workspace, optionally scoped to an
+   * observer, sender, and/or session.
+   */
+  status(
+    workspaceId: string,
+    query?: QueueStatusParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<QueueStatusResponse>;
+  status(workspaceId: string, options?: Core.RequestOptions): Core.APIPromise<QueueStatusResponse>;
+  status(
+    workspaceId: string,
+    query: QueueStatusParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<QueueStatusResponse> {
+    if (isRequestOptions(query)) {
+      return this.status(workspaceId, {}, query);
+    }
+    return this._client.get(`/v2/workspaces/${workspaceId}/queue/status`, { query, ...options });
+  }
+}
+
+/**
+ * Aggregated processing queue status.
+ */
+export interface QueueStatusResponse {
+  /**
+   * Completed work units
+   */
+  completed_work_units: number;
+
+  /**
+   * Work units currently being processed
+   */
+  in_progress_work_units: number;
+
+  /**
+   * Work units waiting to be processed
+   */
+  pending_work_units: number;
+
+  /**
+   * Total work units
+   */
+  total_work_units: number;
+
+  /**
+   * Per-session status when not filtered by session
+   */
+  sessions?: { [key: string]: QueueStatusResponse.Sessions } | null;
+}
+
+export namespace QueueStatusResponse {
+  /**
+   * Status for a specific session within the processing queue.
+   */
+  export interface Sessions {
+    /**
+     * Completed work units
+     */
+    completed_work_units: number;
+
+    /**
+     * Work units currently being processed
+     */
+    in_progress_work_units: number;
+
+    /**
+     * Work units waiting to be processed
+     */
+    pending_work_units: number;
+
+    /**
+     * Total work units
+     */
+    total_work_units: number;
+
+    /**
+     * Session ID if filtered by session
+     */
+    session_id?: string | null;
+  }
+}
+
+export interface QueueStatusParams {
+  /**
+   * Optional observer ID to filter by
+   */
+  observer_id?: string | null;
+
+  /**
+   * Optional sender ID to filter by
+   */
+  sender_id?: string | null;
+
+  /**
+   * Optional session ID to filter by
+   */
+  session_id?: string | null;
+}
+
+export declare namespace Queue {
+  export { type QueueStatusResponse as QueueStatusResponse, type QueueStatusParams as QueueStatusParams };
+}

package/src/resources/workspaces/sessions/index.ts

@@ -15,7 +15,6 @@ export {
 export {
   Peers,
   type SessionPeerConfig,
-  type PeerSetConfigResponse,
   type PeerListParams,
   type PeerAddParams,
   type PeerRemoveParams,
@@ -29,13 +28,13 @@ export {
   type SessionConfiguration,
   type Summary,
   type SessionDeleteResponse,
-  type SessionGetContextResponse,
+  type SessionContextResponse,
   type SessionSearchResponse,
   type SessionSummariesResponse,
   type SessionUpdateParams,
   type SessionListParams,
   type SessionCloneParams,
-  type SessionGetContextParams,
+  type SessionContextParams,
   type SessionGetOrCreateParams,
   type SessionSearchParams,
 } from "./sessions.js";

package/src/resources/workspaces/sessions/messages.ts

@@ -16,29 +16,16 @@ export class Messages extends APIResource {
     body: MessageCreateParams,
     options?: Core.RequestOptions,
   ): Core.APIPromise<MessageCreateResponse> {
-    return this._client.post(`/v2/workspaces/${workspaceId}/sessions/${sessionId}/messages/`, {
+    return this._client.post(`/v2/workspaces/${workspaceId}/sessions/${sessionId}/messages`, {
       body,
       ...options,
     });
   }
 
   /**
-   * Get a Message by ID
-   */
-  retrieve(
-    workspaceId: string,
-    sessionId: string,
-    messageId: string,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<Message> {
-    return this._client.get(
-      `/v2/workspaces/${workspaceId}/sessions/${sessionId}/messages/${messageId}`,
-      options,
-    );
-  }
-
-  /**
-   * Update the metadata of a Message
+   * Update the metadata of a message.
+   *
+   * This will overwrite any existing metadata for the message.
    */
   update(
     workspaceId: string,
@@ -54,7 +41,7 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Get all messages for a session
+   * Get all messages for a Session with optional filters. Results are paginated.
    */
   list(
     workspaceId: string,
@@ -84,6 +71,21 @@ export class Messages extends APIResource {
     );
   }
 
+  /**
+   * Get a single message by ID from a Session.
+   */
+  get(
+    workspaceId: string,
+    sessionId: string,
+    messageId: string,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<Message> {
+    return this._client.get(
+      `/v2/workspaces/${workspaceId}/sessions/${sessionId}/messages/${messageId}`,
+      options,
+    );
+  }
+
   /**
    * Create messages from uploaded files. Files are converted to text and split into
    * multiple messages.
@@ -148,15 +150,15 @@ export namespace MessageCreate {
    */
   export interface Configuration {
     /**
-     * Configuration for deriver functionality.
+     * Configuration for peer card functionality. If reasoning is disabled, peer cards
+     * will also be disabled and these settings will be ignored.
      */
-    deriver?: WorkspacesAPI.DeriverConfiguration | null;
+    peer_card?: WorkspacesAPI.PeerCardConfiguration | null;
 
     /**
-     * Configuration for peer card functionality. If deriver is disabled, peer cards
-     * will also be disabled and these settings will be ignored.
+     * Configuration for reasoning functionality.
      */
-    peer_card?: WorkspacesAPI.PeerCardConfiguration | null;
+    reasoning?: WorkspacesAPI.ReasoningConfiguration | null;
   }
 }