@redplanethq/sdk 0.1.2 → 0.1.4

package/LICENSE

@@ -1,4 +1,4 @@
-Sol License
+Core License
 
 GNU AFFERO GENERAL PUBLIC LICENSE
 Version 3, 19 November 2007

package/README.md

@@ -1,19 +1,21 @@
-# Echo SDK
+# Core SDK
 
-The Echo SDK provides tools and utilities for building integrations with the Echo platform.
+The Core SDK provides tools and utilities for building integrations with the Core platform.
 
 ## Integration System
 
-The Echo integration system uses a CLI-based approach where each integration is a command-line tool that responds to specific events. This makes integrations portable, testable, and easy to debug.
+The Core integration system uses a CLI-based approach where each integration is a command-line tool that responds to specific events. This makes integrations portable, testable, and easy to debug.
 
 ### Integration Event Types
 
 Each integration CLI handles 5 core event types:
 
 #### 1. `spec`
+
 Returns the integration's metadata and configuration.
 
 **Usage:**
+
 ```bash
 my-integration spec
 ```
@@ -21,9 +23,11 @@ my-integration spec
 **Returns:** Integration specification including name, description, auth config, etc.
 
 #### 2. `setup`
+
 Processes authentication data and returns tokens/credentials to be saved.
 
 **Usage:**
+
 ```bash
 my-integration setup --event-body '{"code":"oauth_code","state":"state"}' --integration-definition '{}'
 ```
@@ -31,9 +35,11 @@ my-integration setup --event-body '{"code":"oauth_code","state":"state"}' --inte
 **Returns:** Configuration data (tokens, credentials) to be stored for the account.
 
 #### 3. `identify`
+
 Extracts accountId from webhook data to route webhooks to the correct account.
 
 **Usage:**
+
 ```bash
 my-integration identify --webhook-data '{"team_id":"T123","event":{}}'
 ```
@@ -41,9 +47,11 @@ my-integration identify --webhook-data '{"team_id":"T123","event":{}}'
 **Returns:** Account identifier for webhook routing.
 
 #### 4. `process`
+
 Handles webhook events and returns activity data.
 
 **Usage:**
+
 ```bash
 my-integration process --event-data '{"type":"reaction_added","reaction":"=M"}' --config '{"access_token":"token"}'
 ```
@@ -51,9 +59,11 @@ my-integration process --event-data '{"type":"reaction_added","reaction":"=M"}'
 **Returns:** Activity messages representing user actions.
 
 #### 5. `sync`
+
 Performs scheduled data synchronization for integrations that don't support webhooks.
 
 **Usage:**
+
 ```bash
 my-integration sync --config '{"access_token":"token","last_sync":"2023-01-01T00:00:00Z"}'
 ```
@@ -72,20 +82,24 @@ All integration responses are wrapped in a `Message` object with a `type` field:
 ### Building an Integration
 
 1. **Install the SDK:**
+
 ```bash
-npm install @echo/core-sdk
+npm install @Core/core-sdk
 ```
 
 2. **Create your integration class:**
+
 ```typescript
-import { IntegrationCLI } from '@echo/core-sdk';
+import { IntegrationCLI } from '@Core/core-sdk';
 
 class MyIntegration extends IntegrationCLI {
   constructor() {
     super('my-integration', '1.0.0');
   }
 
-  protected async handleEvent(eventPayload: IntegrationEventPayload): Promise<any> {
+  protected async handleEvent(
+    eventPayload: IntegrationEventPayload,
+  ): Promise<any> {
     switch (eventPayload.event) {
       case 'SETUP':
         return this.handleSetup(eventPayload);
@@ -110,24 +124,28 @@ class MyIntegration extends IntegrationCLI {
         OAuth2: {
           token_url: 'https://api.example.com/oauth/token',
           authorization_url: 'https://api.example.com/oauth/authorize',
-          scopes: ['read', 'write']
-        }
-      }
+          scopes: ['read', 'write'],
+        },
+      },
     };
   }
 
-  private async handleSetup(eventPayload: IntegrationEventPayload): Promise<any> {
+  private async handleSetup(
+    eventPayload: IntegrationEventPayload,
+  ): Promise<any> {
     // Process OAuth response and return tokens to save
     const { code } = eventPayload.eventBody;
     // Exchange code for tokens...
     return {
       access_token: 'token',
       refresh_token: 'refresh_token',
-      expires_at: Date.now() + 3600000
+      expires_at: Date.now() + 3600000,
     };
   }
 
-  private async handleProcess(eventPayload: IntegrationEventPayload): Promise<any> {
+  private async handleProcess(
+    eventPayload: IntegrationEventPayload,
+  ): Promise<any> {
     // Handle webhook events
     const { eventData } = eventPayload.eventBody;
     // Process event and return activity...
@@ -135,23 +153,29 @@ class MyIntegration extends IntegrationCLI {
       type: 'message',
       user: 'user123',
       content: 'Hello world',
-      timestamp: new Date()
+      timestamp: new Date(),
     };
   }
 
-  private async handleIdentify(eventPayload: IntegrationEventPayload): Promise<any> {
+  private async handleIdentify(
+    eventPayload: IntegrationEventPayload,
+  ): Promise<any> {
     // Extract account ID from webhook
     const { team_id } = eventPayload.eventBody;
     return { id: team_id };
   }
 
-  private async handleSync(eventPayload: IntegrationEventPayload): Promise<any> {
+  private async handleSync(
+    eventPayload: IntegrationEventPayload,
+  ): Promise<any> {
     // Perform scheduled sync
     const { config } = eventPayload;
     // Fetch data since last sync...
     return {
-      activities: [/* activity data */],
-      state: { last_sync: new Date().toISOString() }
+      activities: [
+        /* activity data */
+      ],
+      state: { last_sync: new Date().toISOString() },
     };
   }
 }
@@ -162,6 +186,7 @@ integration.parse();
 ```
 
 3. **Build and package your integration:**
+
 ```bash
 npm run build
 npm pack
@@ -200,4 +225,4 @@ node dist/index.js process --event-data '{"type":"test"}' --config '{"token":"te
 5. **Store minimal state** for sync operations
 6. **Test all event types** thoroughly
 
-For more examples, see the integrations in the `integrations/` directory.
+For more examples, see the integrations in the `integrations/` directory.

package/dist/index.d.mts

@@ -53,9 +53,25 @@ declare const LLMModelType: {
 };
 type LLMModelType = (typeof LLMModelType)[keyof typeof LLMModelType];
 
-declare enum EpisodeType {
-    Conversation = "CONVERSATION",
-    Text = "TEXT"
+/**
+ * Interface for document node in the reified knowledge graph
+ * Documents are parent containers for episodic chunks
+ */
+interface DocumentNode {
+    uuid: string;
+    title: string;
+    originalContent: string;
+    metadata: Record<string, any>;
+    source: string;
+    userId: string;
+    createdAt: Date;
+    validAt: Date;
+    totalChunks: number;
+    sessionId?: string;
+    version: number;
+    contentHash: string;
+    previousVersionUuid?: string;
+    chunkHashes?: string[];
 }
 /**
  * Interface for episodic node in the reified knowledge graph
@@ -74,7 +90,23 @@ interface EpisodicNode {
     userId: string;
     space?: string;
     sessionId?: string;
+    recallCount?: number;
+    chunkIndex?: number;
+    labelIds?: string[];
 }
+/**
+ * Episodic node without embeddings for query responses
+ * Use this type when returning episodes from Cypher queries to avoid loading large embedding arrays
+ */
+type EpisodicNodeWithoutEmbeddings = Omit<EpisodicNode, "contentEmbedding">;
+/**
+ * Helper to get episodic node properties for Cypher RETURN clause (excludes embeddings)
+ * Usage in Cypher: RETURN ${EPISODIC_NODE_PROPERTIES} as episode
+ */
+declare const EPISODIC_NODE_PROPERTIES = "{\n  uuid: e.uuid,\n  content: e.content,\n  originalContent: e.originalContent,\n  createdAt: e.createdAt,\n  userId: e.userId,\n  sessionId: e.sessionId,\n  labelIds: e.labelIds,\n  validAt: e.validAt,\n  recallCount: e.recallCount,\n  chunkIndex: e.chunkIndex\n}";
+declare const STATEMENT_NODE_PROPERTIES = "{\n  uuid: s.uuid,\n  fact: s.fact,\n  createdAt: s.createdAt,\n  userId: s.userId,\n  validAt: s.validAt,\n  invalidAt: s.invalidAt,\n  invalidatedBy: s.invalidatedBy,\n  attributes: s.attributes,\n  recallCount: s.recallCount,\n  provenanceCount: s.provenanceCount\n}";
+declare const ENTITY_NODE_PROPERTIES = "{\n  uuid: ent.uuid,\n  name: ent.name,\n  createdAt: ent.createdAt,\n  userId: ent.userId,\n  attributes: ent.attributes\n}";
+declare const COMPACTED_SESSION_NODE_PROPERTIES = "{\n  uuid: cs.uuid,\n  sessionId: cs.sessionId,\n  summary: cs.summary,\n  episodeCount: cs.episodeCount,\n  startTime: cs.startTime,\n  endTime: cs.endTime,\n  createdAt: cs.createdAt,\n  updatedAt: cs.updatedAt,\n  confidence: cs.confidence,\n  userId: cs.userId,\n  source: cs.source,\n  compressionRatio: cs.compressionRatio,\n  metadata: cs.metadata\n}";
 /**
  * Interface for entity node in the reified knowledge graph
  * Entities represent subjects, objects, or predicates in statements
@@ -82,13 +114,11 @@ interface EpisodicNode {
 interface EntityNode {
     uuid: string;
     name: string;
-    type: string;
-    attributes: Record<string, any>;
-    nameEmbedding: number[];
-    typeEmbedding: number[];
+    type?: string;
+    nameEmbedding?: number[];
+    attributes?: Record<string, any>;
     createdAt: Date;
     userId: string;
-    space?: string;
 }
 /**
  * Interface for statement node in the reified knowledge graph
@@ -101,9 +131,16 @@ interface StatementNode {
     createdAt: Date;
     validAt: Date;
     invalidAt: Date | null;
+    invalidatedBy?: string;
     attributes: Record<string, any>;
     userId: string;
     space?: string;
+    labelIds?: string[];
+    recallCount?: {
+        low: number;
+        high: number;
+    };
+    provenanceCount?: number;
 }
 /**
  * Interface for a triple in the reified knowledge graph
@@ -117,14 +154,25 @@ interface Triple {
     object: EntityNode;
     provenance: EpisodicNode;
 }
+declare enum EpisodeTypeEnum {
+    CONVERSATION = "CONVERSATION",
+    DOCUMENT = "DOCUMENT"
+}
+declare const EpisodeType: {
+    CONVERSATION: string;
+    DOCUMENT: string;
+    IMAGE: string;
+};
+type EpisodeType = (typeof EpisodeType)[keyof typeof EpisodeType];
 type AddEpisodeParams = {
     episodeBody: string;
     referenceTime: Date;
-    metadata: Record<string, any>;
+    metadata?: Record<string, any>;
     source: string;
     userId: string;
     spaceId?: string;
     sessionId?: string;
+    type?: EpisodeType;
 };
 type AddEpisodeResult = {
     episodeUuid: string;
@@ -134,13 +182,29 @@ type AddEpisodeResult = {
 };
 interface ExtractedTripleData {
     source: string;
-    sourceType: string;
+    sourceType?: string;
     predicate: string;
     target: string;
-    targetType: string;
+    targetType?: string;
     fact: string;
     attributes?: Record<string, any>;
 }
+interface CompactedSessionNode {
+    uuid: string;
+    sessionId: string;
+    summary: string;
+    summaryEmbedding?: number[];
+    episodeCount: number;
+    startTime: Date;
+    endTime: Date;
+    createdAt: Date;
+    updatedAt?: Date;
+    confidence: number;
+    userId: string;
+    source: string;
+    compressionRatio?: number;
+    metadata?: Record<string, any>;
+}
 
 declare enum ActionStatusEnum {
     ACCEPT = "ACCEPT",
@@ -199,10 +263,23 @@ declare enum IntegrationEventType {
     /**
      * For returning integration metadata/config
      */
-    SPEC = "spec"
+    SPEC = "spec",
+    /**
+     * For to start mcp
+     */
+    MCP = "mcp"
+}
+interface IntegrationDefinition {
+    name: string;
+    version: string;
+    description: string;
 }
 interface IntegrationEventPayload {
     event: IntegrationEventType;
+    integrationDefinition?: IntegrationDefinition;
+    eventBody: any;
+    config?: Config;
+    state?: Record<string, string>;
     [x: string]: any;
 }
 declare class Spec {
@@ -220,7 +297,7 @@ declare class Spec {
 }
 interface Config {
     access_token: string;
-    [key: string]: any;
+    [key: string]: string;
 }
 interface Identifier {
     id: string;
@@ -238,6 +315,235 @@ declare enum UserTypeEnum {
     System = "System"
 }
 
+interface SpaceNode {
+    uuid: string;
+    name: string;
+    description?: string;
+    userId: string;
+    createdAt: Date;
+    updatedAt: Date;
+    isActive: boolean;
+    contextCount?: number;
+    embedding?: number[];
+}
+interface CreateSpaceParams {
+    name: string;
+    description?: string;
+    userId: string;
+    workspaceId: string;
+}
+interface UpdateSpaceParams {
+    name?: string;
+    description?: string;
+    icon?: string;
+    status?: string;
+}
+interface SpaceWithStatements extends SpaceNode {
+    statements: any[];
+}
+interface AssignStatementsParams {
+    statementIds: string[];
+    spaceId: string;
+    userId: string;
+}
+interface SpaceAssignmentResult {
+    success: boolean;
+    statementsUpdated: number;
+    error?: string;
+}
+interface SpaceDeletionResult {
+    deleted: boolean;
+    statementsUpdated: number;
+    error?: string;
+}
+
+type UserConfirmationStatus = "pending" | "accepted" | "rejected" | "edited";
+interface SpacePattern {
+    id: string;
+    name: string;
+    source: "explicit" | "implicit";
+    type: string;
+    summary: string;
+    editedSummary?: string;
+    evidence: string[];
+    confidence: number;
+    userConfirmed: UserConfirmationStatus;
+    spaceId: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreatePatternParams {
+    name: string;
+    source: "explicit" | "implicit";
+    type: string;
+    summary: string;
+    editedSummary?: string;
+    evidence: string[];
+    confidence: number;
+    userConfirmed?: UserConfirmationStatus;
+    spaceId: string;
+}
+interface PatternDetectionResult {
+    explicitPatterns: Omit<SpacePattern, "id" | "createdAt" | "updatedAt" | "spaceId">[];
+    implicitPatterns: Omit<SpacePattern, "id" | "createdAt" | "updatedAt" | "spaceId">[];
+    totalPatternsFound: number;
+    processingStats: {
+        statementsAnalyzed: number;
+        themesProcessed: number;
+        implicitPatternsExtracted: number;
+    };
+}
+interface PatternConfirmationParams {
+    patternId: string;
+    confirmed: boolean;
+}
+declare const EXPLICIT_PATTERN_TYPES: {
+    readonly THEME: "theme";
+    readonly TOPIC: "topic";
+    readonly DOMAIN: "domain";
+    readonly INTEREST_AREA: "interest_area";
+};
+declare const IMPLICIT_PATTERN_TYPES: {
+    readonly PREFERENCE: "preference";
+    readonly HABIT: "habit";
+    readonly WORKFLOW: "workflow";
+    readonly COMMUNICATION_STYLE: "communication_style";
+    readonly DECISION_PATTERN: "decision_pattern";
+    readonly TEMPORAL_PATTERN: "temporal_pattern";
+    readonly BEHAVIORAL_PATTERN: "behavioral_pattern";
+    readonly LEARNING_STYLE: "learning_style";
+    readonly COLLABORATION_STYLE: "collaboration_style";
+};
+declare const PATTERN_TYPES: {
+    readonly PREFERENCE: "preference";
+    readonly HABIT: "habit";
+    readonly WORKFLOW: "workflow";
+    readonly COMMUNICATION_STYLE: "communication_style";
+    readonly DECISION_PATTERN: "decision_pattern";
+    readonly TEMPORAL_PATTERN: "temporal_pattern";
+    readonly BEHAVIORAL_PATTERN: "behavioral_pattern";
+    readonly LEARNING_STYLE: "learning_style";
+    readonly COLLABORATION_STYLE: "collaboration_style";
+    readonly THEME: "theme";
+    readonly TOPIC: "topic";
+    readonly DOMAIN: "domain";
+    readonly INTEREST_AREA: "interest_area";
+};
+type ExplicitPatternType = (typeof EXPLICIT_PATTERN_TYPES)[keyof typeof EXPLICIT_PATTERN_TYPES];
+type ImplicitPatternType = (typeof IMPLICIT_PATTERN_TYPES)[keyof typeof IMPLICIT_PATTERN_TYPES];
+type PatternType = (typeof PATTERN_TYPES)[keyof typeof PATTERN_TYPES];
+
+/**
+ * Search options interface
+ */
+interface SearchOptions {
+    limit?: number;
+    maxBfsDepth?: number;
+    validAt?: Date;
+    startTime?: Date | null;
+    endTime?: Date;
+    includeInvalidated?: boolean;
+    entityTypes?: string[];
+    predicateTypes?: string[];
+    scoreThreshold?: number;
+    minResults?: number;
+    labelIds?: string[];
+    adaptiveFiltering?: boolean;
+    structured?: boolean;
+    useLLMValidation?: boolean;
+    qualityThreshold?: number;
+    maxEpisodesForLLM?: number;
+    sortBy?: "relevance" | "recency";
+}
+/**
+ * Statement with source provenance tracking
+ */
+interface StatementWithSource {
+    statement: StatementNode;
+    sources: {
+        episodeGraph?: {
+            score: number;
+            entityMatches: number;
+        };
+        bfs?: {
+            score: number;
+            hopDistance: number;
+            relevance: number;
+        };
+        vector?: {
+            score: number;
+            similarity: number;
+        };
+        bm25?: {
+            score: number;
+            rank: number;
+        };
+    };
+    primarySource: "episodeGraph" | "bfs" | "vector" | "bm25";
+}
+/**
+ * Episode with provenance tracking from multiple sources
+ */
+interface EpisodeWithProvenance {
+    episode: EpisodicNode;
+    statements: StatementWithSource[];
+    episodeGraphScore: number;
+    bfsScore: number;
+    vectorScore: number;
+    bm25Score: number;
+    sourceBreakdown: {
+        fromEpisodeGraph: number;
+        fromBFS: number;
+        fromVector: number;
+        fromBM25: number;
+    };
+    entityMatchCount?: number;
+    firstLevelScore?: number;
+}
+/**
+ * Quality filtering result
+ */
+interface QualityFilterResult {
+    episodes: EpisodeWithProvenance[];
+    confidence: number;
+    message: string;
+}
+/**
+ * Quality thresholds for filtering
+ */
+declare const QUALITY_THRESHOLDS: {
+    HIGH_QUALITY_EPISODE: number;
+    MEDIUM_QUALITY_EPISODE: number;
+    LOW_QUALITY_EPISODE: number;
+    CONFIDENT_RESULT: number;
+    UNCERTAIN_RESULT: number;
+    NO_RESULT: number;
+    MINIMUM_GAP_RATIO: number;
+};
+/**
+ * Episode search result with aggregated scores and sample statements
+ * Returned by BM25, Vector, and BFS searches
+ */
+interface EpisodeSearchResult {
+    episode: EpisodicNode;
+    score: number;
+    statementCount: number;
+    topStatements: StatementNode[];
+    invalidatedStatements: StatementNode[];
+}
+/**
+ * Configuration for reranking
+ */
+interface RerankConfig {
+    provider: "cohere" | "ollama" | "none";
+    limit?: number;
+    threshold: number;
+    cohereApiKey?: string;
+    cohereModel?: string;
+    ollamaUrl?: string;
+    ollamaModel?: string;
+}
+
 declare abstract class IntegrationCLI {
     protected program: Command;
     protected integrationName: string;
@@ -248,10 +554,11 @@ declare abstract class IntegrationCLI {
     private setupDataCommands;
     private setupSpecCommand;
     private setupSyncCommand;
+    private setupMCPCommand;
     protected abstract handleEvent(eventPayload: IntegrationEventPayload): Promise<Message[]>;
     protected abstract getSpec(): Promise<Spec>;
     parse(): void;
     getProgram(): Command;
 }
 
-export { APIKeyParams, ActionStatus, ActionStatusEnum, type AddEpisodeParams, type AddEpisodeResult, type AuthType, ClaudeModels, type Config, type EntityNode, EpisodeType, type EpisodicNode, type ExtractedTripleData, GeminiModels, type Identifier, IntegrationCLI, type IntegrationEventPayload, IntegrationEventType, LLMMappings, LLMModelEnum, LLMModelType, type Message, type MessageType, OAuth2Params, OpenAIModels, Spec, type StatementNode, type Triple, UserTypeEnum };
+export { APIKeyParams, ActionStatus, ActionStatusEnum, type AddEpisodeParams, type AddEpisodeResult, type AssignStatementsParams, type AuthType, COMPACTED_SESSION_NODE_PROPERTIES, ClaudeModels, type CompactedSessionNode, type Config, type CreatePatternParams, type CreateSpaceParams, type DocumentNode, ENTITY_NODE_PROPERTIES, EPISODIC_NODE_PROPERTIES, EXPLICIT_PATTERN_TYPES, type EntityNode, type EpisodeSearchResult, EpisodeType, EpisodeTypeEnum, type EpisodeWithProvenance, type EpisodicNode, type EpisodicNodeWithoutEmbeddings, type ExplicitPatternType, type ExtractedTripleData, GeminiModels, IMPLICIT_PATTERN_TYPES, type Identifier, type ImplicitPatternType, IntegrationCLI, type IntegrationEventPayload, IntegrationEventType, LLMMappings, LLMModelEnum, LLMModelType, type Message, type MessageType, OAuth2Params, OpenAIModels, PATTERN_TYPES, type PatternConfirmationParams, type PatternDetectionResult, type PatternType, QUALITY_THRESHOLDS, type QualityFilterResult, type RerankConfig, STATEMENT_NODE_PROPERTIES, type SearchOptions, type SpaceAssignmentResult, type SpaceDeletionResult, type SpaceNode, type SpacePattern, type SpaceWithStatements, Spec, type StatementNode, type StatementWithSource, type Triple, type UpdateSpaceParams, type UserConfirmationStatus, UserTypeEnum };