@subcortex-ai/sdk 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @subcortex-ai/sdk
 
-TypeScript SDK for the [SubCortex cognitive engine](https://github.com/tommyboy145/cortex) — persistent memory, identity, signals, and knowledge graph for AI agents.
+TypeScript SDK for the [SubCortex cognitive engine](https://subcortex.ai) — persistent memory, identity, signals, and knowledge graph for AI agents.
 
 ## Install
 

package/dist/index.cjs

@@ -25,9 +25,12 @@ __export(index_exports, {
   CONTEXT_SCHEMA_VERSION: () => CONTEXT_SCHEMA_VERSION,
   ConfidenceLevel: () => ConfidenceLevel,
   ConfidenceScores: () => ConfidenceScores,
+  EntitiesNamespace: () => EntitiesNamespace,
   EntityPredicate: () => EntityPredicate,
   EntityRelationship: () => EntityRelationship,
   EventPredicate: () => EventPredicate,
+  ExperiencesNamespace: () => ExperiencesNamespace,
+  GraphNamespace: () => GraphNamespace,
   IdentityPredicate: () => IdentityPredicate,
   IntakeNamespace: () => IntakeNamespace,
   MULTI_VALUE_PREDICATES: () => MULTI_VALUE_PREDICATES,
@@ -40,10 +43,12 @@ __export(index_exports, {
   RELATIONSHIP_LABELS: () => RELATIONSHIP_LABELS,
   REVERSE_RELATIONSHIPS: () => REVERSE_RELATIONSHIPS,
   RapportPredicate: () => RapportPredicate,
+  RecallNamespace: () => RecallNamespace,
   RelationshipTypes: () => RelationshipTypes,
   RelationshipsNamespace: () => RelationshipsNamespace,
   SIGNAL_DECAY_CONFIG: () => SIGNAL_DECAY_CONFIG,
   SYSTEM_SIGNAL_TYPES: () => SYSTEM_SIGNAL_TYPES,
+  SearchNamespace: () => SearchNamespace,
   SignalsNamespace: () => SignalsNamespace,
   SubCortexAuthenticationError: () => SubCortexAuthenticationError,
   SubCortexAuthorizationError: () => SubCortexAuthorizationError,
@@ -57,6 +62,7 @@ __export(index_exports, {
   SubCortexTimeoutError: () => SubCortexTimeoutError,
   SubCortexValidationError: () => SubCortexValidationError,
   SubjectPrefix: () => SubjectPrefix,
+  TemporalNamespace: () => TemporalNamespace,
   UsersNamespace: () => UsersNamespace,
   WorkPredicate: () => WorkPredicate,
   confidenceToScore: () => confidenceToScore,
@@ -976,49 +982,10 @@ ${connectedPeople.map((p) => {
     let assertionsCreated = 0;
     let relationshipsCreated = 0;
     const warnings = [];
-    await this.http.post("/api/v1/assertions", {
-      tenant_id: this.tenantId,
-      subject: personSubject,
-      predicate: "name",
-      value: input.name,
-      confidence: conf
-    });
-    assertionsCreated++;
+    const candidates = [];
+    candidates.push({ subject: personSubject, predicate: "name", value: input.name, source_confidence: conf, provenance: "agent" });
     if (input.role) {
-      try {
-        const existing = await this.http.get(
-          `/api/v1/assertions/query/${enc2(this.tenantId)}/${enc2(personSubject)}`
-        );
-        const existingRole = existing.find((a) => a.predicate === "role" && !a.isSuperseded);
-        if (existingRole && existingRole.value !== input.role) {
-          warnings.push(`${input.name} was previously "${existingRole.value}" \u2014 now being set as "${input.role}". Role change or mistake?`);
-          await this.http.post("/api/v1/assertions/supersede", {
-            tenant_id: this.tenantId,
-            original_assertion_id: existingRole.id,
-            subject: personSubject,
-            predicate: "role",
-            value: input.role,
-            confidence: conf
-          });
-        } else if (!existingRole) {
-          await this.http.post("/api/v1/assertions", {
-            tenant_id: this.tenantId,
-            subject: personSubject,
-            predicate: "role",
-            value: input.role,
-            confidence: conf
-          });
-        }
-      } catch {
-        await this.http.post("/api/v1/assertions", {
-          tenant_id: this.tenantId,
-          subject: personSubject,
-          predicate: "role",
-          value: input.role,
-          confidence: conf
-        });
-      }
-      assertionsCreated++;
+      candidates.push({ subject: personSubject, predicate: "role", value: input.role, source_confidence: conf, provenance: "agent" });
       try {
         const allAssertions = await this.http.get(
           `/api/v1/assertions/list/${enc2(this.tenantId)}`
@@ -1035,6 +1002,35 @@ ${connectedPeople.map((p) => {
         }
       } catch {
       }
+    }
+    if (input.details) {
+      candidates.push({ subject: personSubject, predicate: "details", value: input.details, source_confidence: conf, provenance: "agent" });
+    }
+    candidates.push({
+      subject: personSubject,
+      predicate: "status",
+      value: input.relationship === "candidate" ? "candidate" : "active",
+      source_confidence: conf,
+      provenance: "agent"
+    });
+    const correlationId = `register_person_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+    const intakeResult = await this.http.post("/api/v1/intake/submit", {
+      correlation_id: correlationId,
+      agent_id: "sdk",
+      tenant_id: this.tenantId,
+      candidates,
+      context: input.sessionId ? { sessionId: input.sessionId } : void 0
+    });
+    assertionsCreated = intakeResult.accepted + intakeResult.reinforced;
+    if (intakeResult.conflicts > 0) {
+      const conflictItems = (intakeResult.items || []).filter(
+        (i) => i.status === "conflict_detected"
+      );
+      for (const item of conflictItems) {
+        warnings.push(item.surfacingHint || "A conflict was detected with existing data.");
+      }
+    }
+    if (input.role) {
       const roleSubject = subject("role" /* ROLE */, input.role);
       await this.http.post("/api/v1/assertions", {
         tenant_id: this.tenantId,
@@ -1050,34 +1046,13 @@ ${connectedPeople.map((p) => {
         relationship_type: "holds_role" /* HOLDS_ROLE */,
         confidence: conf
       });
-      assertionsCreated++;
       relationshipsCreated++;
     }
-    if (input.details) {
-      await this.http.post("/api/v1/assertions", {
-        tenant_id: this.tenantId,
-        subject: personSubject,
-        predicate: "details",
-        value: input.details,
-        confidence: conf
-      });
-      assertionsCreated++;
-    }
-    await this.http.post("/api/v1/assertions", {
-      tenant_id: this.tenantId,
-      subject: personSubject,
-      predicate: "status",
-      value: input.relationship === "candidate" ? "candidate" : "active",
-      confidence: conf
-    });
-    assertionsCreated++;
     const FORWARD_MAP = {
       "direct_report": "manages" /* MANAGES */,
       "team_member": "has_member" /* HAS_MEMBER */,
       "candidate": "manages" /* MANAGES */,
-      // user manages the hiring
       "manager": "reports_to" /* REPORTS_TO */,
-      // user reports to this person
       "stakeholder": "stakeholder_in" /* STAKEHOLDER_IN */,
       "collaborator": "collaborates_with" /* COLLABORATES_WITH */,
       "mentor": "mentors" /* MENTORS */
@@ -1118,31 +1093,26 @@ ${connectedPeople.map((p) => {
   async recordRapport(input) {
     const userSubject = subject("user" /* USER */, input.userId);
     const conf = typeof input.confidence === "number" ? input.confidence : confidenceToScore(input.confidence || "high" /* HIGH */);
-    await this.http.post("/api/v1/assertions", {
-      tenant_id: this.tenantId,
-      subject: userSubject,
-      predicate: input.type,
-      value: input.value,
-      confidence: conf
-    });
+    const candidates = [
+      { subject: userSubject, predicate: input.type, value: input.value, source_confidence: conf, provenance: "agent" }
+    ];
     if (input.aboutPerson) {
       const personSubject = subject("person" /* PERSON */, input.aboutPerson);
-      try {
-        const personAssertions = await this.http.get(
-          `/api/v1/assertions/query/${enc2(this.tenantId)}/${enc2(personSubject)}`
-        );
-        if (personAssertions.length > 0) {
-          await this.http.post("/api/v1/assertions", {
-            tenant_id: this.tenantId,
-            subject: personSubject,
-            predicate: "timeline",
-            value: input.value,
-            confidence: conf
-          });
-        }
-      } catch {
-      }
+      candidates.push({
+        subject: personSubject,
+        predicate: "timeline",
+        value: input.value,
+        source_confidence: conf,
+        provenance: "agent"
+      });
     }
+    const correlationId = `rapport_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+    await this.http.post("/api/v1/intake/submit", {
+      correlation_id: correlationId,
+      agent_id: "sdk",
+      tenant_id: this.tenantId,
+      candidates
+    });
     return { success: true };
   }
   /**
@@ -1431,11 +1401,247 @@ var IntakeNamespace = class {
     return this.http.get(`/api/v1/intake/stats/${enc3(agentId)}`);
   }
 };
+var ExperiencesNamespace = class {
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /** List experiences, optionally filtered by subject. */
+  async list(input) {
+    const tenantId = input?.tenantId || this.tenantId;
+    const params = new URLSearchParams();
+    if (input?.subject) params.set("subject", input.subject);
+    if (input?.limit) params.set("limit", String(input.limit));
+    const qs = params.toString();
+    return this.http.get(
+      `/api/v1/experiences/${enc3(tenantId)}${qs ? `?${qs}` : ""}`
+    );
+  }
+  /** Get a single experience by ID. */
+  async get(experienceId, options) {
+    const tenantId = options?.tenantId || this.tenantId;
+    return this.http.get(
+      `/api/v1/experiences/${enc3(tenantId)}/${enc3(experienceId)}`
+    );
+  }
+};
+var RecallNamespace = class {
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /** BM25 full-text search across assertions. */
+  async search(input) {
+    const tenantId = input.tenantId || this.tenantId;
+    const params = new URLSearchParams({ q: input.query });
+    if (input.limit) params.set("limit", String(input.limit));
+    return this.http.get(
+      `/api/v1/recall/${enc3(tenantId)}?${params.toString()}`
+    );
+  }
+};
+var GraphNamespace = class {
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /** Find paths between two subjects. */
+  async findPaths(input) {
+    const tenantId = input.tenantId || this.tenantId;
+    return this.http.post(
+      `/api/v1/graph/${enc3(tenantId)}/paths`,
+      {
+        from: input.from,
+        to: input.to,
+        max_depth: input.maxDepth,
+        min_confidence: input.minConfidence,
+        strategy: input.strategy
+      }
+    );
+  }
+  /** BFS traversal from a starting subject. */
+  async traverse(input) {
+    const tenantId = input.tenantId || this.tenantId;
+    return this.http.post(
+      `/api/v1/graph/${enc3(tenantId)}/traverse`,
+      {
+        start_subject: input.startSubject,
+        max_depth: input.maxDepth,
+        relationship_types: input.relationshipTypes,
+        min_confidence: input.minConfidence,
+        max_nodes: input.maxNodes
+      }
+    );
+  }
+};
+var TemporalNamespace = class {
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /** Get assertions valid at a specific point in time. */
+  async at(subject2, point, options) {
+    const tenantId = options?.tenantId || this.tenantId;
+    const pointStr = point instanceof Date ? point.toISOString() : point;
+    return this.http.get(
+      `/api/v1/temporal/${enc3(tenantId)}/${enc3(subject2)}/at?point=${enc3(pointStr)}`
+    );
+  }
+  /** Get assertions within a date range. */
+  async range(subject2, start, end, options) {
+    const tenantId = options?.tenantId || this.tenantId;
+    const startStr = start instanceof Date ? start.toISOString() : start;
+    const endStr = end instanceof Date ? end.toISOString() : end;
+    return this.http.get(
+      `/api/v1/temporal/${enc3(tenantId)}/${enc3(subject2)}/range?start=${enc3(startStr)}&end=${enc3(endStr)}`
+    );
+  }
+};
+var SearchNamespace = class {
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /** Semantic nearest-neighbor search over assertion embeddings. */
+  async semantic(input) {
+    const tenantId = input.tenantId || this.tenantId;
+    return this.http.post(
+      `/api/v1/search/${enc3(tenantId)}/semantic`,
+      {
+        embedding: input.embedding,
+        top_k: input.topK
+      }
+    );
+  }
+};
 var DEFAULT_RETRY = {
   maxRetries: 3,
   baseDelayMs: 500,
   maxDelayMs: 1e4
 };
+var EntitiesNamespace = class {
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /** Create an entity with optional description and type. */
+  async create(input) {
+    const tenantId = input.tenantId || this.tenantId;
+    const subject2 = `entity:${input.name.toLowerCase().replace(/\s+/g, "-")}`;
+    const typeAssertion = await this.http.post(
+      `/api/v1/assertions`,
+      {
+        tenant_id: tenantId,
+        subject: subject2,
+        predicate: "type",
+        value: input.type || "model",
+        confidence: 1
+      }
+    );
+    if (input.description) {
+      await this.http.post(
+        `/api/v1/assertions`,
+        {
+          tenant_id: tenantId,
+          subject: subject2,
+          predicate: "description",
+          value: input.description,
+          confidence: 1
+        }
+      );
+    }
+    return typeAssertion;
+  }
+  /** Add a property to an entity. */
+  async addProperty(input) {
+    const tenantId = input.tenantId || this.tenantId;
+    const entitySubject = `entity:${input.entityName.toLowerCase().replace(/\s+/g, "-")}`;
+    const propertySubject = `property:${input.entityName.toLowerCase().replace(/\s+/g, "-")}.${input.name.toLowerCase().replace(/\s+/g, "-")}`;
+    const assertion = await this.http.post(
+      `/api/v1/assertions`,
+      {
+        tenant_id: tenantId,
+        subject: propertySubject,
+        predicate: "field_type",
+        value: input.fieldType,
+        confidence: 1
+      }
+    );
+    const relationship = await this.http.post(
+      `/api/v1/relationships`,
+      {
+        tenant_id: tenantId,
+        from_subject: entitySubject,
+        to_subject: propertySubject,
+        relationship_type: "has_property",
+        confidence: 1
+      }
+    );
+    if (input.required) {
+      await this.http.post(
+        `/api/v1/assertions`,
+        {
+          tenant_id: tenantId,
+          subject: propertySubject,
+          predicate: "required",
+          value: true,
+          confidence: 1
+        }
+      );
+    }
+    return { assertion, relationship };
+  }
+  /** Describe an entity by reconstructing its properties and relationships from assertions. */
+  async describe(entityName, options) {
+    const tenantId = options?.tenantId || this.tenantId;
+    const subject2 = `entity:${entityName.toLowerCase().replace(/\s+/g, "-")}`;
+    const assertions = await this.http.get(
+      `/api/v1/assertions/query/${enc3(tenantId)}/${enc3(subject2)}`
+    );
+    const relationships = await this.http.get(
+      `/api/v1/relationships/query/${enc3(tenantId)}/${enc3(subject2)}`
+    );
+    const typeAssertion = assertions.find((a) => a.predicate === "type" && !a.isSuperseded);
+    const descAssertion = assertions.find((a) => a.predicate === "description" && !a.isSuperseded);
+    const propertyRels = relationships.filter((r) => r.relationshipType === "has_property");
+    const properties = await Promise.all(
+      propertyRels.map(async (rel) => {
+        const propAssertions = await this.http.get(
+          `/api/v1/assertions/query/${enc3(tenantId)}/${enc3(rel.toSubject)}`
+        );
+        const fieldType = propAssertions.find((a) => a.predicate === "field_type" && !a.isSuperseded);
+        const required = propAssertions.find((a) => a.predicate === "required" && !a.isSuperseded);
+        const name = rel.toSubject.replace(/^property:[^.]+\./, "");
+        return {
+          name,
+          fieldType: fieldType ? String(fieldType.value) : null,
+          required: required ? Boolean(required.value) : false
+        };
+      })
+    );
+    const otherRels = relationships.filter((r) => r.relationshipType !== "has_property").map((r) => ({
+      type: r.relationshipType,
+      target: r.toSubject,
+      confidence: r.confidence
+    }));
+    return {
+      subject: subject2,
+      name: entityName,
+      type: typeAssertion ? String(typeAssertion.value) : null,
+      description: descAssertion ? String(descAssertion.value) : null,
+      properties,
+      relationships: otherRels
+    };
+  }
+  /** List all entities for a tenant (subjects with entity: prefix that have a type predicate). */
+  async list(options) {
+    const tenantId = options?.tenantId || this.tenantId;
+    const all = await this.http.get(
+      `/api/v1/assertions/list/${enc3(tenantId)}`
+    );
+    return all.filter((a) => a.subject.startsWith("entity:") && a.predicate === "type" && !a.isSuperseded);
+  }
+};
 var SubCortexClient = class {
   /** Assertion operations (low-level knowledge primitives) */
   assertions;
@@ -1451,6 +1657,18 @@ var SubCortexClient = class {
   users;
   /** Emotional signals — record, query, and resolve */
   signals;
+  /** Graph queries — pathfinding and traversal */
+  graph;
+  /** Temporal queries — point-in-time snapshots and range queries */
+  temporal;
+  /** Semantic search over assertion embeddings */
+  search;
+  /** BM25 full-text recall search */
+  recall;
+  /** Episodic memory — experiences grouped by session */
+  experiences;
+  /** Entity schema management — create, describe, and manage data models */
+  entities;
   http;
   constructor(options) {
     if (!options.apiKey && !options.token) {
@@ -1474,6 +1692,12 @@ var SubCortexClient = class {
     this.intake = new IntakeNamespace(this.http, options.tenantId);
     this.users = new UsersNamespace(this.http, options.tenantId);
     this.signals = new SignalsNamespace(this.http, options.tenantId);
+    this.graph = new GraphNamespace(this.http, options.tenantId);
+    this.temporal = new TemporalNamespace(this.http, options.tenantId);
+    this.search = new SearchNamespace(this.http, options.tenantId);
+    this.recall = new RecallNamespace(this.http, options.tenantId);
+    this.experiences = new ExperiencesNamespace(this.http, options.tenantId);
+    this.entities = new EntitiesNamespace(this.http, options.tenantId);
   }
   /** Check SubCortex server health. */
   async health() {
@@ -1649,9 +1873,12 @@ function esc(s) {
   CONTEXT_SCHEMA_VERSION,
   ConfidenceLevel,
   ConfidenceScores,
+  EntitiesNamespace,
   EntityPredicate,
   EntityRelationship,
   EventPredicate,
+  ExperiencesNamespace,
+  GraphNamespace,
   IdentityPredicate,
   IntakeNamespace,
   MULTI_VALUE_PREDICATES,
@@ -1664,10 +1891,12 @@ function esc(s) {
   RELATIONSHIP_LABELS,
   REVERSE_RELATIONSHIPS,
   RapportPredicate,
+  RecallNamespace,
   RelationshipTypes,
   RelationshipsNamespace,
   SIGNAL_DECAY_CONFIG,
   SYSTEM_SIGNAL_TYPES,
+  SearchNamespace,
   SignalsNamespace,
   SubCortexAuthenticationError,
   SubCortexAuthorizationError,
@@ -1681,6 +1910,7 @@ function esc(s) {
   SubCortexTimeoutError,
   SubCortexValidationError,
   SubjectPrefix,
+  TemporalNamespace,
   UsersNamespace,
   WorkPredicate,
   confidenceToScore,