@honcho-ai/core 1.8.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> {}
@@ -233,79 +237,6 @@ export interface PeerCardResponse {
   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.
- */
-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 SessionGet {
   filters?: { [key: string]: unknown } | null;
 }
@@ -317,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
    */
@@ -334,30 +265,17 @@ 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?: Representation | null;
+  representation?: string | null;
 }
 
-export type PeerSearchResponse = Array<MessagesAPI.Message>;
+export interface PeerRepresentationResponse {
+  representation: string;
+}
 
-export type PeerWorkingRepresentationResponse = { [key: string]: unknown };
+export type PeerSearchResponse = Array<MessagesAPI.Message>;
 
 export interface PeerUpdateParams {
   configuration?: { [key: string]: unknown } | null;
@@ -374,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;
 }
@@ -386,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
    */
@@ -399,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;
 
@@ -423,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;
 }
@@ -442,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;
 }
@@ -523,22 +446,21 @@ export declare namespace Peers {
     type PageSession as PageSession,
     type Peer as Peer,
     type PeerCardResponse as PeerCardResponse,
-    type Representation as Representation,
     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";