@kybernesis/brain-contracts 0.13.0 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- package/dist/brain-provider.d.ts +53 -1
- package/dist/brain-provider.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -19,6 +19,11 @@ pnpm add @kybernesis/brain-contracts
|
|
|
19
19
|
|
|
20
20
|
- **Provider interfaces** — `StorageProvider` (and its repositories: timeline, entity-graph,
|
|
21
21
|
fact, sleep, vector), plus the shapes the kernel injects. The seams a backend must satisfy.
|
|
22
|
+
- **`BrainProvider`** — the Layer-2, consumer-facing facade interface (ADR-0016):
|
|
23
|
+
bound-tenant, all-async, coarse-grained brain operations (`remember` / `addNote` / `query` /
|
|
24
|
+
`timeline` / entity ops / `graph` / `listEntities` / `stats` / `sleep`). Implemented locally
|
|
25
|
+
by `createLocalBrainProvider` in [`brain-core`](../brain-core); the seam a future remote
|
|
26
|
+
cloud provider also satisfies. Exported from the package root.
|
|
22
27
|
- **Zod schemas + types** — `TimelineEvent`, `Entity`, `Fact`, sleep types, etc. Canonical
|
|
23
28
|
field shapes (snake_case to match the wire format), with a guard test enforcing it.
|
|
24
29
|
- **`TenantContext` + `pathsFor`** — the per-brain context describing where its SQLite files
|
package/dist/brain-provider.d.ts
CHANGED
|
@@ -37,7 +37,7 @@ import type { HybridSearchResult, HybridSearchOptions } from './search.js';
|
|
|
37
37
|
import type { TimelineEvent } from './timeline.js';
|
|
38
38
|
import type { TimelineQuery, EntityRelatedHit } from './storage.js';
|
|
39
39
|
import type { Entity, EntityMention } from './entity.js';
|
|
40
|
-
import type { EntityType } from './constants.js';
|
|
40
|
+
import type { EntityType, RelationshipType } from './constants.js';
|
|
41
41
|
/** Options common to all write operations. */
|
|
42
42
|
export interface WriteOpts {
|
|
43
43
|
/**
|
|
@@ -98,6 +98,39 @@ export interface EntityRecall {
|
|
|
98
98
|
mentions: EntityMention[];
|
|
99
99
|
related_entities: EntityRelatedHit[];
|
|
100
100
|
}
|
|
101
|
+
/**
|
|
102
|
+
* A single entity↔entity edge in the renderable entity graph
|
|
103
|
+
* ({@link BrainProvider.graph}). Endpoints are entity ids (the `nodes` array
|
|
104
|
+
* carries the full {@link Entity} rows). Field names mirror KAD's
|
|
105
|
+
* `GET /brain/graph` entity-relation edge sub-shape (`relationship` /
|
|
106
|
+
* `confidence`) minus its UI-only id namespacing, so a KAD/Arcana renderer maps
|
|
107
|
+
* `source_id`→`e:<id>` without reshaping.
|
|
108
|
+
*/
|
|
109
|
+
export interface BrainGraphEdge {
|
|
110
|
+
source_id: number;
|
|
111
|
+
target_id: number;
|
|
112
|
+
relationship: RelationshipType;
|
|
113
|
+
confidence: number;
|
|
114
|
+
rationale?: string;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* A renderable slice of the **entity** graph — entity nodes + typed entity↔entity
|
|
118
|
+
* edges, drawn from `entity-graph.db` ONLY.
|
|
119
|
+
*
|
|
120
|
+
* SCOPE (deliberate): this is the entity-graph primitive, NOT KAD's full
|
|
121
|
+
* `GET /brain/graph` assembly. KAD's route is a HOST-level unified graph that
|
|
122
|
+
* also folds in timeline-event nodes, sleep `memory_edges`, temporal-fact nodes
|
|
123
|
+
* and disk-scanned notes — work that crosses three DBs and walks the filesystem,
|
|
124
|
+
* which the kernel must not do (the kernel never touches the fs). A host that
|
|
125
|
+
* wants the full canvas composes this entity slice with `timeline()` + its own
|
|
126
|
+
* sleep/disk sources; the library owns only the entity graph.
|
|
127
|
+
*/
|
|
128
|
+
export interface BrainGraph {
|
|
129
|
+
/** Entity nodes, most-mentioned (most-connected) first — the graph anchors. */
|
|
130
|
+
nodes: Entity[];
|
|
131
|
+
/** Typed entity↔entity edges among `nodes` (closed: both endpoints are nodes). */
|
|
132
|
+
edges: BrainGraphEdge[];
|
|
133
|
+
}
|
|
101
134
|
/** Brain-wide counts, as returned by {@link BrainProvider.stats}. */
|
|
102
135
|
export interface BrainStats {
|
|
103
136
|
timeline_rows: number;
|
|
@@ -177,6 +210,25 @@ export interface BrainProvider {
|
|
|
177
210
|
recallEntity(name: string): Promise<EntityRecall | null>;
|
|
178
211
|
/** Pinned entities, most-mentioned first. */
|
|
179
212
|
getPinnedEntities(): Promise<PinnedEntity[]>;
|
|
213
|
+
/**
|
|
214
|
+
* Renderable slice of the entity graph — nodes (most-mentioned first) + the
|
|
215
|
+
* typed edges among them. Coarse-grained: ONE call returns the whole
|
|
216
|
+
* renderable graph (chunky, not chatty). `opts.limit` caps the node count
|
|
217
|
+
* (default 50); edges are restricted to pairs where both endpoints are nodes,
|
|
218
|
+
* so the returned graph is always closed/drawable. Entity-graph.db only — see
|
|
219
|
+
* {@link BrainGraph} for why this is the entity slice, not KAD's full assembly.
|
|
220
|
+
*/
|
|
221
|
+
graph(opts?: {
|
|
222
|
+
limit?: number;
|
|
223
|
+
}): Promise<BrainGraph>;
|
|
224
|
+
/**
|
|
225
|
+
* Flat entity list for an entities table/browser, most-mentioned (most-
|
|
226
|
+
* relevant) first, optionally filtered by `type`. `opts.limit` defaults to 50.
|
|
227
|
+
*/
|
|
228
|
+
listEntities(opts?: {
|
|
229
|
+
limit?: number;
|
|
230
|
+
type?: EntityType;
|
|
231
|
+
}): Promise<Entity[]>;
|
|
180
232
|
/** Brain-wide counts (timeline / facts / entities / vectors). */
|
|
181
233
|
stats(): Promise<BrainStats>;
|
|
182
234
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"brain-provider.d.ts","sourceRoot":"","sources":["../src/brain-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;
|
|
1
|
+
{"version":3,"file":"brain-provider.d.ts","sourceRoot":"","sources":["../src/brain-provider.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED