feat(brains): createFromProject high-level helper (#182)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkfleet/memory-sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "TypeScript SDK for app.memmesh.ai — admin + project memory CRUD, semantic search, feedback, and Lattice behavioral patterns",
   "type": "module",
   "main": "./dist/index.cjs",

src/index.ts

@@ -116,10 +116,12 @@ export { BrainsResource } from './resources/brains.js'
 export type {
   Brain,
   BrainCard,
+  BrainReasoningCoverage,
   BrainProvenance,
   BrainVisibility,
   BrainStatus,
   CreateBrainRequest,
+  CreateBrainFromProjectOptions,
   UpdateBrainRequest,
   ListBrainsParams,
 } from './types/brain.js'

src/resources/brains.ts

@@ -2,6 +2,7 @@ import type { HttpClient } from '../core/http-client.js'
 import type { RequestOptions, SeekPage } from '../core/types.js'
 import type {
   Brain,
+  CreateBrainFromProjectOptions,
   CreateBrainRequest,
   ListBrainsParams,
   UpdateBrainRequest,
@@ -40,6 +41,47 @@ export class BrainsResource {
     return this.http.post<Brain>('/brains', body, options)
   }
 
+  /**
+   * Create a brain from the calling project's memory — the easy, high-level path.
+   *
+   * Where {@link create} wants a full {@link CreateBrainRequest}, this builds a
+   * sensible one for you from just a slug + name (plus optional domain / version
+   * / visibility) and an empty-but-valid Brain Card. Coverage (subjects, facts,
+   * and the induced reasoning layer) is computed server-side from the project's
+   * own memory, so you don't pass it. The brain is created as a DRAFT + PRIVATE;
+   * publishing and pricing are deliberate, separate steps.
+   *
+   * @example
+   * ```ts
+   * const brain = await tf.brains.createFromProject({
+   *   externalId: 'my-support-playbook',
+   *   name: 'Support Playbook',
+   *   domain: 'support',
+   * })
+   * // brain.status === 'DRAFT', brain.visibility === 'PRIVATE'
+   *
+   * // Publish it later, once you're ready:
+   * await tf.brains.update(brain.id, { visibility: 'PUBLIC', status: 'PUBLISHED' })
+   * ```
+   */
+  async createFromProject(
+    opts: CreateBrainFromProjectOptions,
+    options?: RequestOptions,
+  ): Promise<Brain> {
+    const body: CreateBrainRequest = {
+      externalId: opts.externalId,
+      name: opts.name,
+      domain: opts.domain,
+      version: opts.version ?? '1.0.0',
+      visibility: opts.visibility ?? 'PRIVATE',
+      // Empty-but-valid card: an empty provenance list and empty coverage. The
+      // server recomputes coverage from the project's memory; a real licensed
+      // provenance source is only required to publish PUBLIC (a separate step).
+      card: { provenance: [], coverage: {} },
+    }
+    return this.create(body, options)
+  }
+
   /** List the project's brains (cursor-paginated). */
   async list(params?: ListBrainsParams, options?: RequestOptions): Promise<SeekPage<Brain>> {
     return this.http.get<SeekPage<Brain>>(

src/types/brain.ts

@@ -21,12 +21,29 @@ export interface BrainProvenance {
   url?: string
 }
 
+/**
+ * Coverage the induced reasoning layer advertises on a Brain Card — the
+ * procedure/checklist/decomposition memories that make a brain worth more than a
+ * plain dataset. A facts-only brain reports `total: 0`.
+ */
+export interface BrainReasoningCoverage {
+  procedures?: number
+  checklists?: number
+  decompositions?: number
+  total?: number
+}
+
 /** The Brain Card manifest (stored on the brain, surfaced in the catalog). */
 export interface BrainCard {
   ontologyRef?: string
   provenance?: BrainProvenance[]
   changelogRef?: string
-  coverage?: { subjects?: number; facts?: number; freshness?: string }
+  coverage?: {
+    subjects?: number
+    facts?: number
+    reasoning?: BrainReasoningCoverage
+    freshness?: string
+  }
   evaluation?: { benchmark?: string; score?: number }
   predictEnabled?: boolean
   pricing?: { model?: string; unit?: string }
@@ -71,3 +88,20 @@ export interface ListBrainsParams {
   limit?: number
   cursor?: string
 }
+
+/**
+ * High-level options for {@link BrainsResource.createFromProject} — the easy
+ * path to turning a project's memory into a brain. A minimal set of fields; the
+ * Brain Card (provenance/coverage) is filled in for you.
+ */
+export interface CreateBrainFromProjectOptions {
+  /** Stable slug the Router addresses the brain by (unique per project). */
+  externalId: string
+  name: string
+  /** Domain the brain covers, e.g. "finance". Required before publishing PUBLIC. */
+  domain?: string
+  /** Semantic version. Defaults to "1.0.0". */
+  version?: string
+  /** Defaults to "PRIVATE". A brain is only consumable once separately PUBLISHED. */
+  visibility?: BrainVisibility
+}