@honcho-ai/core 1.5.1 → 1.6.1

package/src/index.ts

@@ -9,14 +9,20 @@ import * as Uploads from "./uploads.js";
 import * as API from "./resources/index.js";
 import { KeyCreateParams, KeyCreateResponse, Keys } from "./resources/keys.js";
 import {
+  DeriverConfiguration,
   DeriverStatus,
+  DreamConfiguration,
   MessageSearchOptions,
+  PeerCardConfiguration,
+  SummaryConfiguration,
   Workspace,
+  WorkspaceConfiguration,
   WorkspaceDeriverStatusParams,
   WorkspaceGetOrCreateParams,
   WorkspaceListParams,
   WorkspaceSearchParams,
   WorkspaceSearchResponse,
+  WorkspaceTriggerDreamParams,
   WorkspaceUpdateParams,
   Workspaces,
   WorkspacesPage,
@@ -218,9 +224,14 @@ export declare namespace Honcho {
 
   export {
     Workspaces as Workspaces,
+    type DeriverConfiguration as DeriverConfiguration,
     type DeriverStatus as DeriverStatus,
+    type DreamConfiguration as DreamConfiguration,
     type MessageSearchOptions as MessageSearchOptions,
+    type PeerCardConfiguration as PeerCardConfiguration,
+    type SummaryConfiguration as SummaryConfiguration,
     type Workspace as Workspace,
+    type WorkspaceConfiguration as WorkspaceConfiguration,
     type WorkspaceSearchResponse as WorkspaceSearchResponse,
     WorkspacesPage as WorkspacesPage,
     type WorkspaceUpdateParams as WorkspaceUpdateParams,
@@ -228,6 +239,7 @@ export declare namespace Honcho {
     type WorkspaceDeriverStatusParams as WorkspaceDeriverStatusParams,
     type WorkspaceGetOrCreateParams as WorkspaceGetOrCreateParams,
     type WorkspaceSearchParams as WorkspaceSearchParams,
+    type WorkspaceTriggerDreamParams as WorkspaceTriggerDreamParams,
   };
 
   export {

package/src/resources/index.ts

@@ -4,13 +4,19 @@ export { Keys, type KeyCreateResponse, type KeyCreateParams } from "./keys.js";
 export {
   WorkspacesPage,
   Workspaces,
+  type DeriverConfiguration,
   type DeriverStatus,
+  type DreamConfiguration,
   type MessageSearchOptions,
+  type PeerCardConfiguration,
+  type SummaryConfiguration,
   type Workspace,
+  type WorkspaceConfiguration,
   type WorkspaceSearchResponse,
   type WorkspaceUpdateParams,
   type WorkspaceListParams,
   type WorkspaceDeriverStatusParams,
   type WorkspaceGetOrCreateParams,
   type WorkspaceSearchParams,
+  type WorkspaceTriggerDreamParams,
 } from "./workspaces/workspaces.js";

package/src/resources/workspaces/index.ts

@@ -1,28 +1,46 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  ObservationsPage,
+  Observations,
+  type ObservationCreate,
+  type ObservationGet,
+  type ObservationQuery,
+  type PageObservation,
+  type ObservationCreateResponse,
+  type ObservationDeleteResponse,
+  type ObservationQueryResponse,
+  type ObservationCreateParams,
+  type ObservationListParams,
+  type ObservationQueryParams,
+} from "./observations.js";
 export {
   PeersPage,
   Peers,
   type PagePeer,
   type PageSession,
   type Peer,
-  type SessionGet,
   type PeerCardResponse,
+  type SessionGet,
   type PeerChatResponse,
+  type PeerGetContextResponse,
   type PeerSearchResponse,
   type PeerWorkingRepresentationResponse,
   type PeerUpdateParams,
   type PeerListParams,
   type PeerCardParams,
   type PeerChatParams,
+  type PeerGetContextParams,
   type PeerGetOrCreateParams,
   type PeerSearchParams,
+  type PeerSetCardParams,
   type PeerWorkingRepresentationParams,
 } from "./peers/index.js";
 export {
   SessionsPage,
   Sessions,
   type Session,
+  type SessionConfiguration,
   type Summary,
   type SessionDeleteResponse,
   type SessionGetContextResponse,
@@ -47,13 +65,19 @@ export {
 export {
   WorkspacesPage,
   Workspaces,
+  type DeriverConfiguration,
   type DeriverStatus,
+  type DreamConfiguration,
   type MessageSearchOptions,
+  type PeerCardConfiguration,
+  type SummaryConfiguration,
   type Workspace,
+  type WorkspaceConfiguration,
   type WorkspaceSearchResponse,
   type WorkspaceUpdateParams,
   type WorkspaceListParams,
   type WorkspaceDeriverStatusParams,
   type WorkspaceGetOrCreateParams,
   type WorkspaceSearchParams,
+  type WorkspaceTriggerDreamParams,
 } from "./workspaces.js";

package/src/resources/workspaces/observations.ts

@@ -0,0 +1,238 @@
+// 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";
+import { Page, type PageParams } from "../../pagination.js";
+
+export class Observations extends APIResource {
+  /**
+   * Create one or more observations.
+   *
+   * Creates observations (theory-of-mind facts) for the specified observer/observed
+   * peer pairs. Each observation must reference existing peers and a session within
+   * the workspace. Embeddings are automatically generated for semantic search.
+   *
+   * Maximum of 100 observations per request.
+   */
+  create(
+    workspaceId: string,
+    body: ObservationCreateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ObservationCreateResponse> {
+    return this._client.post(`/v2/workspaces/${workspaceId}/observations`, { body, ...options });
+  }
+
+  /**
+   * List all observations using custom filters. Observations are listed by recency
+   * unless `reverse` is set to `true`.
+   *
+   * Observations can be filtered by session_id, observer_id and observed_id using
+   * the filters parameter.
+   */
+  list(
+    workspaceId: string,
+    params?: ObservationListParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<ObservationsPage, Observations>;
+  list(workspaceId: string, options?: Core.RequestOptions): Core.PagePromise<ObservationsPage, Observations>;
+  list(
+    workspaceId: string,
+    params: ObservationListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<ObservationsPage, Observations> {
+    if (isRequestOptions(params)) {
+      return this.list(workspaceId, {}, params);
+    }
+    const { page, reverse, size, ...body } = params;
+    return this._client.getAPIList(`/v2/workspaces/${workspaceId}/observations/list`, ObservationsPage, {
+      query: { page, reverse, size },
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+
+  /**
+   * Delete a specific observation.
+   *
+   * This permanently deletes the observation (document) from the theory-of-mind
+   * system. This action cannot be undone.
+   */
+  delete(
+    workspaceId: string,
+    observationId: string,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<unknown> {
+    return this._client.delete(`/v2/workspaces/${workspaceId}/observations/${observationId}`, options);
+  }
+
+  /**
+   * Query observations using semantic search.
+   *
+   * Performs vector similarity search on observations to find semantically relevant
+   * results. Observer and observed are required for semantic search and must be
+   * provided in filters.
+   */
+  query(
+    workspaceId: string,
+    body: ObservationQueryParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ObservationQueryResponse> {
+    return this._client.post(`/v2/workspaces/${workspaceId}/observations/query`, { body, ...options });
+  }
+}
+
+export class ObservationsPage extends Page<Observations> {}
+
+/**
+ * Schema for creating a single observation
+ */
+export interface ObservationCreate {
+  content: string;
+
+  /**
+   * The peer being observed
+   */
+  observed_id: string;
+
+  /**
+   * The peer making the observation
+   */
+  observer_id: string;
+
+  /**
+   * The session this observation relates to
+   */
+  session_id: string;
+}
+
+/**
+ * Schema for listing observations with optional filters
+ */
+export interface ObservationGet {
+  filters?: { [key: string]: unknown } | null;
+}
+
+/**
+ * Query parameters for semantic search of observations
+ */
+export interface ObservationQuery {
+  /**
+   * Semantic search query
+   */
+  query: string;
+
+  /**
+   * Maximum cosine distance threshold for results
+   */
+  distance?: number | null;
+
+  /**
+   * Additional filters to apply
+   */
+  filters?: { [key: string]: unknown } | null;
+
+  /**
+   * Number of results to return
+   */
+  top_k?: number;
+}
+
+/**
+ * Observation response - external view of a document
+ */
+export interface Observations {
+  id: string;
+
+  content: string;
+
+  created_at: string;
+
+  /**
+   * The peer being observed
+   */
+  observed_id: string;
+
+  /**
+   * The peer who made the observation
+   */
+  observer_id: string;
+
+  session_id: string;
+}
+
+export interface PageObservation {
+  items: Array<Observations>;
+
+  page: number;
+
+  size: number;
+
+  pages?: number;
+
+  total?: number;
+}
+
+export type ObservationCreateResponse = Array<Observations>;
+
+export type ObservationDeleteResponse = unknown;
+
+export type ObservationQueryResponse = Array<Observations>;
+
+export interface ObservationCreateParams {
+  observations: Array<ObservationCreate>;
+}
+
+export interface ObservationListParams extends PageParams {
+  /**
+   * Query param: Whether to reverse the order of results
+   */
+  reverse?: boolean | null;
+
+  /**
+   * Body param:
+   */
+  filters?: { [key: string]: unknown } | null;
+}
+
+export interface ObservationQueryParams {
+  /**
+   * Semantic search query
+   */
+  query: string;
+
+  /**
+   * Maximum cosine distance threshold for results
+   */
+  distance?: number | null;
+
+  /**
+   * Additional filters to apply
+   */
+  filters?: { [key: string]: unknown } | null;
+
+  /**
+   * Number of results to return
+   */
+  top_k?: number;
+}
+
+Observations.ObservationsPage = ObservationsPage;
+
+export declare namespace Observations {
+  export {
+    type ObservationCreate as ObservationCreate,
+    type ObservationGet as ObservationGet,
+    type ObservationQuery as ObservationQuery,
+    type Observations as Observations,
+    type PageObservation as PageObservation,
+    type ObservationCreateResponse as ObservationCreateResponse,
+    type ObservationDeleteResponse as ObservationDeleteResponse,
+    type ObservationQueryResponse as ObservationQueryResponse,
+    ObservationsPage as ObservationsPage,
+    type ObservationCreateParams as ObservationCreateParams,
+    type ObservationListParams as ObservationListParams,
+    type ObservationQueryParams as ObservationQueryParams,
+  };
+}

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

@@ -6,17 +6,20 @@ export {
   type PagePeer,
   type PageSession,
   type Peer,
-  type SessionGet,
   type PeerCardResponse,
+  type SessionGet,
   type PeerChatResponse,
+  type PeerGetContextResponse,
   type PeerSearchResponse,
   type PeerWorkingRepresentationResponse,
   type PeerUpdateParams,
   type PeerListParams,
   type PeerCardParams,
   type PeerChatParams,
+  type PeerGetContextParams,
   type PeerGetOrCreateParams,
   type PeerSearchParams,
+  type PeerSetCardParams,
   type PeerWorkingRepresentationParams,
 } from "./peers.js";
 export { Sessions, type SessionListParams } from "./sessions.js";

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

@@ -87,6 +87,40 @@ export class Peers extends APIResource {
     return this._client.post(`/v2/workspaces/${workspaceId}/peers/${peerId}/chat`, { body, ...options });
   }
 
+  /**
+   * 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 is useful for getting all the context needed about a peer without making
+   * multiple API calls.
+   */
+  getContext(
+    workspaceId: string,
+    peerId: string,
+    query?: PeerGetContextParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PeerGetContextResponse>;
+  getContext(
+    workspaceId: string,
+    peerId: string,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PeerGetContextResponse>;
+  getContext(
+    workspaceId: string,
+    peerId: string,
+    query: PeerGetContextParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PeerGetContextResponse> {
+    if (isRequestOptions(query)) {
+      return this.getContext(workspaceId, peerId, {}, query);
+    }
+    return this._client.get(`/v2/workspaces/${workspaceId}/peers/${peerId}/context`, { query, ...options });
+  }
+
   /**
    * Get a Peer by ID
    *
@@ -113,6 +147,26 @@ export class Peers extends APIResource {
     return this._client.post(`/v2/workspaces/${workspaceId}/peers/${peerId}/search`, { body, ...options });
   }
 
+  /**
+   * Set a peer card for a specific peer relationship.
+   *
+   * Sets the peer card that the observer peer has for the target peer. If no target
+   * is specified, sets the observer's own peer card.
+   */
+  setCard(
+    workspaceId: string,
+    peerId: string,
+    params: PeerSetCardParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<PeerCardResponse> {
+    const { target, ...body } = params;
+    return this._client.put(`/v2/workspaces/${workspaceId}/peers/${peerId}/card`, {
+      query: { target },
+      body,
+      ...options,
+    });
+  }
+
   /**
    * Get a peer's working representation for a session.
    *
@@ -172,10 +226,6 @@ export interface Peer {
   metadata?: { [key: string]: unknown };
 }
 
-export interface SessionGet {
-  filters?: { [key: string]: unknown } | null;
-}
-
 export interface PeerCardResponse {
   /**
    * The peer card content, or None if not found
@@ -183,10 +233,130 @@ export interface PeerCardResponse {
   peer_card?: Array<string> | null;
 }
 
+export interface SessionGet {
+  filters?: { [key: string]: unknown } | null;
+}
+
 export interface PeerChatResponse {
   content: string;
 }
 
+/**
+ * Context for a peer, including representation and peer card.
+ */
+export interface PeerGetContextResponse {
+  /**
+   * The ID of the peer
+   */
+  peer_id: string;
+
+  /**
+   * The ID of the target peer being observed
+   */
+  target_id: string;
+
+  /**
+   * The peer card for the target peer from the observer's perspective
+   */
+  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.
+   */
+  representation?: PeerGetContextResponse.Representation | 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 type PeerSearchResponse = Array<MessagesAPI.Message>;
 
 export type PeerWorkingRepresentationResponse = { [key: string]: unknown };
@@ -231,6 +401,41 @@ export interface PeerChatParams {
   target?: string | null;
 }
 
+export interface PeerGetContextParams {
+  /**
+   * Whether to include the most derived observations in the representation
+   */
+  include_most_derived?: boolean;
+
+  /**
+   * Maximum number of observations to include in the representation
+   */
+  max_observations?: number | null;
+
+  /**
+   * Only used if `search_query` is provided. Maximum distance for semantically
+   * relevant observations
+   */
+  search_max_distance?: number | null;
+
+  /**
+   * Optional query to curate the representation around semantic search results
+   */
+  search_query?: string | null;
+
+  /**
+   * Only used if `search_query` is provided. Number of semantic-search-retrieved
+   * observations 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)
+   */
+  target?: string | null;
+}
+
 export interface PeerGetOrCreateParams {
   id: string;
 
@@ -256,7 +461,49 @@ export interface PeerSearchParams {
   limit?: number;
 }
 
+export interface PeerSetCardParams {
+  /**
+   * Body param: The peer card content to set
+   */
+  peer_card: Array<string>;
+
+  /**
+   * Query param: The peer whose card to set. If not provided, sets the observer's
+   * own card
+   */
+  target?: string | null;
+}
+
 export interface PeerWorkingRepresentationParams {
+  /**
+   * Only used if `search_query` is provided. Whether to include the most derived
+   * observations in the representation
+   */
+  include_most_derived?: boolean | null;
+
+  /**
+   * Only used if `search_query` is provided. Maximum number of observations to
+   * include in the representation
+   */
+  max_observations?: number | null;
+
+  /**
+   * Only used if `search_query` is provided. Maximum distance to search for
+   * semantically relevant observations
+   */
+  search_max_distance?: number | null;
+
+  /**
+   * Optional input to curate the representation around semantic search results
+   */
+  search_query?: string | null;
+
+  /**
+   * Only used if `search_query` is provided. Number of semantic-search-retrieved
+   * observations to include in the representation
+   */
+  search_top_k?: number | null;
+
   /**
    * Get the working representation within this session
    */
@@ -277,9 +524,10 @@ export declare namespace Peers {
     type PagePeer as PagePeer,
     type PageSession as PageSession,
     type Peer as Peer,
-    type SessionGet as SessionGet,
     type PeerCardResponse as PeerCardResponse,
+    type SessionGet as SessionGet,
     type PeerChatResponse as PeerChatResponse,
+    type PeerGetContextResponse as PeerGetContextResponse,
     type PeerSearchResponse as PeerSearchResponse,
     type PeerWorkingRepresentationResponse as PeerWorkingRepresentationResponse,
     PeersPage as PeersPage,
@@ -287,8 +535,10 @@ export declare namespace Peers {
     type PeerListParams as PeerListParams,
     type PeerCardParams as PeerCardParams,
     type PeerChatParams as PeerChatParams,
+    type PeerGetContextParams as PeerGetContextParams,
     type PeerGetOrCreateParams as PeerGetOrCreateParams,
     type PeerSearchParams as PeerSearchParams,
+    type PeerSetCardParams as PeerSetCardParams,
     type PeerWorkingRepresentationParams as PeerWorkingRepresentationParams,
   };