@papr/memory 1.9.0 → 1.13.0

package/src/resources/feedback.ts

@@ -0,0 +1,424 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Feedback extends APIResource {
+  /**
+   * Retrieve feedback by ID.
+   *
+   *     This endpoint allows developers to fetch feedback details by feedback ID.
+   *     Only the user who created the feedback or users with appropriate permissions can access it.
+   *
+   *     **Authentication Required**:
+   *     One of the following authentication methods must be used:
+   *     - Bearer token in `Authorization` header
+   *     - API Key in `X-API-Key` header
+   *     - Session token in `X-Session-Token` header
+   *
+   *     **Required Headers**:
+   *     - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
+   *
+   * @example
+   * ```ts
+   * const feedbackResponse = await client.feedback.getByID(
+   *   'feedback_id',
+   * );
+   * ```
+   */
+  getByID(feedbackID: string, options?: RequestOptions): APIPromise<FeedbackResponse> {
+    return this._client.get(path`/v1/feedback/${feedbackID}`, options);
+  }
+
+  /**
+   * Submit feedback on search results to help improve model performance.
+   *
+   *     This endpoint allows developers to provide feedback on:
+   *     - Overall answer quality (thumbs up/down, ratings)
+   *     - Specific memory relevance and accuracy
+   *     - User engagement signals (copy, save, create document actions)
+   *     - Corrections and improvements
+   *
+   *     The feedback is used to train and improve:
+   *     - Router model tier predictions
+   *     - Memory retrieval ranking
+   *     - Answer generation quality
+   *     - Agentic graph search performance
+   *
+   *     **Authentication Required**:
+   *     One of the following authentication methods must be used:
+   *     - Bearer token in `Authorization` header
+   *     - API Key in `X-API-Key` header
+   *     - Session token in `X-Session-Token` header
+   *
+   *     **Required Headers**:
+   *     - Content-Type: application/json
+   *     - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
+   *
+   * @example
+   * ```ts
+   * const feedbackResponse = await client.feedback.submit({
+   *   feedbackData: {
+   *     feedbackSource: 'inline',
+   *     feedbackType: 'thumbs_up',
+   *   },
+   *   search_id: 'abc123def456',
+   * });
+   * ```
+   */
+  submit(body: FeedbackSubmitParams, options?: RequestOptions): APIPromise<FeedbackResponse> {
+    return this._client.post('/v1/feedback', { body, ...options });
+  }
+
+  /**
+   * Submit multiple feedback items in a single request.
+   *
+   *     Useful for submitting session-end feedback or bulk feedback collection.
+   *     Each feedback item is processed independently, so partial success is possible.
+   *
+   *     **Authentication Required**:
+   *     One of the following authentication methods must be used:
+   *     - Bearer token in `Authorization` header
+   *     - API Key in `X-API-Key` header
+   *     - Session token in `X-Session-Token` header
+   *
+   *     **Required Headers**:
+   *     - Content-Type: application/json
+   *     - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
+   *
+   * @example
+   * ```ts
+   * const batchResponse = await client.feedback.submitBatch({
+   *   feedback_items: [
+   *     {
+   *       feedbackData: {
+   *         feedbackSource: 'inline',
+   *         feedbackType: 'thumbs_up',
+   *       },
+   *       search_id: 'abc123def456',
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  submitBatch(body: FeedbackSubmitBatchParams, options?: RequestOptions): APIPromise<BatchResponse> {
+    return this._client.post('/v1/feedback/batch', { body, ...options });
+  }
+}
+
+/**
+ * Request model for submitting multiple feedback items
+ */
+export interface BatchRequest {
+  /**
+   * List of feedback items to submit
+   */
+  feedback_items: Array<FeedbackRequest>;
+
+  /**
+   * Session-level context for batch feedback
+   */
+  session_context?: { [key: string]: unknown } | null;
+}
+
+/**
+ * Response model for batch feedback submission
+ */
+export interface BatchResponse {
+  /**
+   * HTTP status code
+   */
+  code: number;
+
+  /**
+   * Human-readable message
+   */
+  message: string;
+
+  /**
+   * 'success' or 'error'
+   */
+  status: string;
+
+  /**
+   * Error message if status is 'error'
+   */
+  error?: string | null;
+
+  /**
+   * List of error details
+   */
+  errors?: Array<{ [key: string]: unknown }>;
+
+  /**
+   * Number of failed feedback items
+   */
+  failed_count?: number;
+
+  /**
+   * List of feedback IDs
+   */
+  feedback_ids?: Array<string>;
+
+  /**
+   * Number of successfully processed feedback items
+   */
+  successful_count?: number;
+}
+
+/**
+ * Request model for submitting feedback on search results
+ */
+export interface FeedbackRequest {
+  /**
+   * The feedback data containing all feedback information
+   */
+  feedbackData: FeedbackRequest.FeedbackData;
+
+  /**
+   * The search_id from SearchResponse that this feedback relates to
+   */
+  search_id: string;
+
+  /**
+   * External user ID for developer API keys acting on behalf of end users
+   */
+  external_user_id?: string | null;
+
+  /**
+   * Internal user ID (if not provided, will be resolved from authentication)
+   */
+  user_id?: string | null;
+}
+
+export namespace FeedbackRequest {
+  /**
+   * The feedback data containing all feedback information
+   */
+  export interface FeedbackData {
+    /**
+     * Where the feedback was provided from
+     */
+    feedbackSource: 'inline' | 'post_query' | 'session_end' | 'memory_citation' | 'answer_panel';
+
+    /**
+     * Types of feedback that can be provided
+     */
+    feedbackType:
+      | 'thumbs_up'
+      | 'thumbs_down'
+      | 'rating'
+      | 'correction'
+      | 'report'
+      | 'copy_action'
+      | 'save_action'
+      | 'create_document'
+      | 'memory_relevance'
+      | 'answer_quality';
+
+    /**
+     * A pointer to a Parse object
+     */
+    assistantMessage?: FeedbackData.AssistantMessage | null;
+
+    citedMemoryIds?: Array<string> | null;
+
+    citedNodeIds?: Array<string> | null;
+
+    feedbackImpact?: string | null;
+
+    feedbackProcessed?: boolean | null;
+
+    feedbackScore?: number | null;
+
+    feedbackText?: string | null;
+
+    feedbackValue?: string | null;
+
+    /**
+     * A pointer to a Parse object
+     */
+    userMessage?: FeedbackData.UserMessage | null;
+  }
+
+  export namespace FeedbackData {
+    /**
+     * A pointer to a Parse object
+     */
+    export interface AssistantMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+
+    /**
+     * A pointer to a Parse object
+     */
+    export interface UserMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+  }
+}
+
+/**
+ * Response model for feedback submission
+ */
+export interface FeedbackResponse {
+  /**
+   * HTTP status code
+   */
+  code: number;
+
+  /**
+   * Human-readable message
+   */
+  message: string;
+
+  /**
+   * 'success' or 'error'
+   */
+  status: string;
+
+  /**
+   * Additional error details
+   */
+  details?: { [key: string]: unknown } | null;
+
+  /**
+   * Error message if status is 'error'
+   */
+  error?: string | null;
+
+  /**
+   * Unique feedback ID
+   */
+  feedback_id?: string | null;
+}
+
+export interface FeedbackSubmitParams {
+  /**
+   * The feedback data containing all feedback information
+   */
+  feedbackData: FeedbackSubmitParams.FeedbackData;
+
+  /**
+   * The search_id from SearchResponse that this feedback relates to
+   */
+  search_id: string;
+
+  /**
+   * External user ID for developer API keys acting on behalf of end users
+   */
+  external_user_id?: string | null;
+
+  /**
+   * Internal user ID (if not provided, will be resolved from authentication)
+   */
+  user_id?: string | null;
+}
+
+export namespace FeedbackSubmitParams {
+  /**
+   * The feedback data containing all feedback information
+   */
+  export interface FeedbackData {
+    /**
+     * Where the feedback was provided from
+     */
+    feedbackSource: 'inline' | 'post_query' | 'session_end' | 'memory_citation' | 'answer_panel';
+
+    /**
+     * Types of feedback that can be provided
+     */
+    feedbackType:
+      | 'thumbs_up'
+      | 'thumbs_down'
+      | 'rating'
+      | 'correction'
+      | 'report'
+      | 'copy_action'
+      | 'save_action'
+      | 'create_document'
+      | 'memory_relevance'
+      | 'answer_quality';
+
+    /**
+     * A pointer to a Parse object
+     */
+    assistantMessage?: FeedbackData.AssistantMessage | null;
+
+    citedMemoryIds?: Array<string> | null;
+
+    citedNodeIds?: Array<string> | null;
+
+    feedbackImpact?: string | null;
+
+    feedbackProcessed?: boolean | null;
+
+    feedbackScore?: number | null;
+
+    feedbackText?: string | null;
+
+    feedbackValue?: string | null;
+
+    /**
+     * A pointer to a Parse object
+     */
+    userMessage?: FeedbackData.UserMessage | null;
+  }
+
+  export namespace FeedbackData {
+    /**
+     * A pointer to a Parse object
+     */
+    export interface AssistantMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+
+    /**
+     * A pointer to a Parse object
+     */
+    export interface UserMessage {
+      className: string;
+
+      objectId: string;
+
+      __type?: string;
+    }
+  }
+}
+
+export interface FeedbackSubmitBatchParams {
+  /**
+   * List of feedback items to submit
+   */
+  feedback_items: Array<FeedbackRequest>;
+
+  /**
+   * Session-level context for batch feedback
+   */
+  session_context?: { [key: string]: unknown } | null;
+}
+
+export declare namespace Feedback {
+  export {
+    type BatchRequest as BatchRequest,
+    type BatchResponse as BatchResponse,
+    type FeedbackRequest as FeedbackRequest,
+    type FeedbackResponse as FeedbackResponse,
+    type FeedbackSubmitParams as FeedbackSubmitParams,
+    type FeedbackSubmitBatchParams as FeedbackSubmitBatchParams,
+  };
+}

package/src/resources/index.ts

@@ -1,5 +1,14 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Feedback,
+  type BatchRequest,
+  type BatchResponse,
+  type FeedbackRequest,
+  type FeedbackResponse,
+  type FeedbackSubmitParams,
+  type FeedbackSubmitBatchParams,
+} from './feedback';
 export {
   Memory,
   type AddMemory,
@@ -30,5 +39,4 @@ export {
   type UserListParams,
   type UserDeleteParams,
   type UserCreateBatchParams,
-  type UserGetParams,
 } from './user';

package/src/resources/memory.ts

@@ -167,6 +167,17 @@ export class Memory extends APIResource {
    *
    *     The API supports response compression for improved performance. Responses larger than 1KB will be automatically compressed when this header is present.
    *
+   *     **HIGHLY RECOMMENDED SETTINGS FOR BEST RESULTS:**
+   *     - Set `enable_agentic_graph: true` for intelligent, context-aware search that can understand ambiguous references
+   *     - Use `max_memories: 15-20` for comprehensive memory coverage
+   *     - Use `max_nodes: 10-15` for comprehensive graph entity relationships
+   *
+   *     **Agentic Graph Benefits:**
+   *     When enabled, the system can understand vague references by first identifying specific entities from your memory graph, then performing targeted searches. For example:
+   *     - "customer feedback" → identifies your customers first, then finds their specific feedback
+   *     - "project issues" → identifies your projects first, then finds related issues
+   *     - "team meeting notes" → identifies your team members first, then finds meeting notes
+   *
    *     **User Resolution Precedence:**
    *     - If both user_id and external_user_id are provided, user_id takes precedence.
    *     - If only external_user_id is provided, it will be resolved to the internal user.
@@ -370,7 +381,7 @@ export type MemoryType = 'text' | 'code_snippet' | 'document';
 export interface RelationshipItem {
   relation_type: string;
 
-  metadata?: unknown;
+  metadata?: { [key: string]: unknown };
 
   related_item_id?: string | null;
 
@@ -382,7 +393,7 @@ export interface RelationshipItem {
   /**
    * Enum for relationship types
    */
-  relationship_type?: 'previous_memory_item_id' | 'all_previous_memory_items' | null;
+  relationship_type?: 'previous_memory_item_id' | 'all_previous_memory_items' | 'link_to_id' | null;
 }
 
 export interface SearchResponse {
@@ -406,6 +417,12 @@ export interface SearchResponse {
    */
   error?: string | null;
 
+  /**
+   * Unique identifier for this search query, maps to QueryLog objectId in Parse
+   * Server
+   */
+  search_id?: string | null;
+
   /**
    * 'success' or 'error'
    */
@@ -445,7 +462,7 @@ export namespace SearchResponse {
 
       current_step?: string | null;
 
-      customMetadata?: unknown | null;
+      customMetadata?: { [key: string]: unknown } | null;
 
       external_user_id?: string | null;
 
@@ -461,7 +478,7 @@ export namespace SearchResponse {
 
       location?: string | null;
 
-      metadata?: string | unknown | null;
+      metadata?: string | { [key: string]: unknown } | null;
 
       page?: string | null;
 
@@ -1094,6 +1111,8 @@ export namespace MemoryDeleteResponse {
     parse?: boolean;
 
     pinecone?: boolean;
+
+    qdrant?: boolean;
   }
 }
 
@@ -1258,25 +1277,39 @@ export interface MemorySearchParams {
   /**
    * Body param: Detailed search query describing what you're looking for. For best
    * results, write 2-3 sentences that include specific details, context, and time
-   * frame. For example: 'Find recurring customer complaints about API performance
-   * from the last month. Focus on issues where customers specifically mentioned
-   * timeout errors or slow response times in their conversations.'
+   * frame. Examples: 'Find recurring customer complaints about API performance from
+   * the last month. Focus on issues where customers specifically mentioned timeout
+   * errors or slow response times in their conversations.' 'What are the main issues
+   * and blockers in my current projects? Focus on technical challenges and timeline
+   * impacts.' 'Find insights about team collaboration and communication patterns
+   * from recent meetings and discussions.'
    */
   query: string;
 
   /**
-   * Query param: Maximum number of memories to return
+   * Query param: HIGHLY RECOMMENDED: Maximum number of memories to return. Use at
+   * least 15-20 for comprehensive results. Lower values (5-10) may miss relevant
+   * information. Default is 20 for optimal coverage.
    */
   max_memories?: number;
 
   /**
-   * Query param: Maximum number of neo nodes to return
+   * Query param: HIGHLY RECOMMENDED: Maximum number of neo nodes to return. Use at
+   * least 10-15 for comprehensive graph results. Lower values may miss important
+   * entity relationships. Default is 15 for optimal coverage.
    */
   max_nodes?: number;
 
   /**
-   * Body param: Whether to enable agentic graph search. Default is false (graph
-   * search is skipped). Set to true to use agentic graph search.
+   * Body param: HIGHLY RECOMMENDED: Enable agentic graph search for intelligent,
+   * context-aware results. When enabled, the system can understand ambiguous
+   * references by first identifying specific entities from your memory graph, then
+   * performing targeted searches. Examples: 'customer feedback' → identifies your
+   * customers first, then finds their specific feedback; 'project issues' →
+   * identifies your projects first, then finds related issues; 'team meeting notes'
+   * → identifies team members first, then finds meeting notes. This provides much
+   * more relevant and comprehensive results. Set to false only if you need faster,
+   * simpler keyword-based search.
    */
   enable_agentic_graph?: boolean;