soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

docs: complete Stage 3 CANONICAL taxonomy documentation (v5.5.0)

Browse source 
Added comprehensive documentation for Stage 3 taxonomy migration:

API Documentation Updates:
- Updated version header from v5.4.0 to v5.5.0
- Fixed all deprecated NounType.Content examples → Document, Concept
- Added versions.asOf() method documentation with examples
- Added comprehensive Type System Reference section

Type System Reference:
- Documented all 42 noun types organized by category
- Documented 127 verb types organized by functional groups
- Added migration guide from v5.4.0 (deprecated types)
- Breaking changes: User→Person, Topic→Concept, Content→Document
- Stage 3 adds +11 nouns, +87 verbs (169 total types)

Build Status:
- ✅ TypeScript build passes with zero errors (stale cache issue resolved)
- ✅ All Stage 2 references updated to Stage 3 CANONICAL
- ✅ Type embeddings current (42 nouns + 127 verbs = 338KB)

Tested with confidential Tales from Talifar Glossary (NOT in repo):
- Successfully imported 2,284 entities across 7 noun types
- Created 2,280 relationships (contains verb)
- Noun type distribution: document (50%), thing (16%), person (16%),
  location (9%), concept (9%), collection (1%), file (<1%)
- Demonstrates Stage 3 taxonomy handles rich fantasy world data

Type System Coverage:
- 7/42 noun types used (16.7%) - appropriate for glossary domain
- 1/127 verb types used (0.8%) - opportunity for richer relationships

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
David Snelling 2025-11-06 10:28:47 -08:00
parent 2dd9678a7f
commit f019ac241e
1 changed files with 141 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

148
docs/api/README.md
View file

@ -3,7 +3,7 @@
> **Complete API documentation for Brainy v5.0+** > **Complete API documentation for Brainy v5.0+**
> Zero Configuration • Triple Intelligence • Git-Style Branching • Entity Versioning > Zero Configuration • Triple Intelligence • Git-Style Branching • Entity Versioning
**Updated:** 2025-11-05 for v5.4.0 **Updated:** 2025-11-06 for v5.5.0
**All APIs verified against actual code** **All APIs verified against actual code**
--- ---
@ -19,7 +19,7 @@ await brain.init() // VFS auto-initialized in v5.1.0!
// Add data (text auto-embeds!) // Add data (text auto-embeds!)
const id = await brain.add({ const id = await brain.add({
data: 'The future of AI is here', data: 'The future of AI is here',
type: NounType.Content, type: NounType.Concept,
metadata: { category: 'technology' } metadata: { category: 'technology' }
}) })
@ -32,7 +32,7 @@ const results = await brain.find({
// Fork for safe experimentation (v5.0.0+) // Fork for safe experimentation (v5.0.0+)
const experiment = await brain.fork('test-feature') const experiment = await brain.fork('test-feature')
await experiment.add({ data: 'test', type: NounType.Content }) await experiment.add({ data: 'test', type: NounType.Document })
await experiment.commit({ message: 'Add test data' }) await experiment.commit({ message: 'Add test data' })
// Entity versioning (v5.3.0+) // Entity versioning (v5.3.0+)
@ -76,6 +76,7 @@ Time-travel and history tracking for individual entities - Git-like version cont
- [Configuration](#configuration) - [Configuration](#configuration)
- [Storage Adapters](#storage-adapters) - [Storage Adapters](#storage-adapters)
- [Utility Methods](#utility-methods) - [Utility Methods](#utility-methods)
- [Type System Reference](#type-system-reference)
--- ---
@ -290,7 +291,7 @@ Add multiple entities in one operation.
```typescript ```typescript
const result = await brain.addMany({ const result = await brain.addMany({
items: [ items: [
{ data: 'Entity 1', type: NounType.Content }, { data: 'Entity 1', type: NounType.Document },
{ data: 'Entity 2', type: NounType.Concept } { data: 'Entity 2', type: NounType.Concept }
] ]
}) })
@ -358,7 +359,7 @@ Create an instant fork (<100ms) with full isolation.
const experiment = await brain.fork('test-feature') const experiment = await brain.fork('test-feature')
// Make changes safely in isolation // Make changes safely in isolation
await experiment.add({ data: 'Test entity', type: NounType.Content }) await experiment.add({ data: 'Test entity', type: NounType.Document })
await experiment.update({ id: someId, metadata: { modified: true } }) await experiment.update({ id: someId, metadata: { modified: true } })
// Parent is unaffected! // Parent is unaffected!
@ -477,6 +478,50 @@ const history = await brain.getHistory({
--- ---
### `asOf(commitId, options?)` → `Promise<Brainy>`
Create a read-only snapshot at a specific commit for time-travel queries.
```typescript
// Get commit ID from history
const commits = await brain.getHistory({ limit: 1 })
const commitId = commits[0].id
// Create snapshot (lazy-loading, no eager data loading)
const snapshot = await brain.asOf(commitId, {
cacheSize: 10000 // LRU cache size (default: 10000)
})
// Query historical state - full Triple Intelligence works!
const results = await snapshot.find({
query: 'AI research',
where: { category: 'technology' }
})
// Get historical relationships
const related = await snapshot.getRelated(entityId, { depth: 2 })
// MUST close when done to free memory
await snapshot.close()
```
**Parameters:**
- `commitId`: `string` - Commit hash to snapshot from
- `options?`: `object`
- `cacheSize?`: `number` - LRU cache size for lazy-loading (default: 10000)
**Returns:** `Promise<Brainy>` - Read-only Brainy instance with historical state
**Features:**
- **Lazy-Loading** - Loads entities on-demand, not eagerly
- **Bounded Memory** - LRU cache prevents memory bloat
- **Full Query Support** - All find(), getRelated(), etc. work on historical data
- **Read-Only** - Prevents accidental modifications to history
**Important:** Always call `snapshot.close()` when done to release resources.
---
## Entity Versioning (v5.3.0+) ## Entity Versioning (v5.3.0+)
**NEW in v5.3.0:** Git-style versioning for individual entities with content-addressable storage. **NEW in v5.3.0:** Git-style versioning for individual entities with content-addressable storage.
@ -1558,7 +1603,7 @@ await brain.shutdown() // Graceful shutdown, flush caches
// Create // Create
const id = await brain.add({ const id = await brain.add({
data: 'Quantum computing breakthrough', data: 'Quantum computing breakthrough',
type: NounType.Content, type: NounType.Concept,
metadata: { category: 'tech', year: 2024 } metadata: { category: 'tech', year: 2024 }
}) })
@ -1635,7 +1680,7 @@ const experiment = await brain.fork('test-migration')
// Make changes in isolation // Make changes in isolation
await experiment.add({ await experiment.add({
data: 'New feature', data: 'New feature',
type: NounType.Content type: NounType.Document
}) })
// Commit your work // Commit your work
@ -1677,6 +1722,95 @@ const tree = await brain.vfs.getTreeStructure('/projects', {
--- ---
## Type System Reference
**NEW in v5.5.0:** Stage 3 CANONICAL taxonomy with 169 types (42 nouns + 127 verbs)
### Noun Types (42)
Brainy uses a comprehensive noun type system covering 96-97% of human knowledge:
**Core Entity Types (7)**
- `NounType.Person` - Individual human entities
- `NounType.Organization` - Companies, institutions, collectives
- `NounType.Location` - Geographic and spatial entities
- `NounType.Thing` - Physical objects and artifacts
- `NounType.Concept` - Abstract ideas and principles
- `NounType.Event` - Temporal occurrences
- `NounType.Agent` - AI agents, bots, automated systems
**Digital/Content Types (4)**
- `NounType.Document` - Text-based files and written content
- `NounType.Media` - Audio, video, images
- `NounType.File` - Generic digital files
- `NounType.Message` - Communication content
**Business Types (4)**
- `NounType.Product` - Commercial products
- `NounType.Service` - Service offerings
- `NounType.Task` - Actions, todos, work items
- `NounType.Project` - Organized initiatives
**Scientific Types (2)**
- `NounType.Hypothesis` - Theories and propositions
- `NounType.Experiment` - Studies and investigations
**And 25 more types** including: `Organism`, `Substance`, `Quality`, `TimeInterval`, `Function`, `Proposition`, `Collection`, `Dataset`, `Process`, `State`, `Role`, `Language`, `Currency`, `Measurement`, `Contract`, `Regulation`, `Interface`, `Resource`, `Custom`, `SocialGroup`, `Institution`, `Norm`, `InformationContent`, `InformationBearer`, `Relationship`
### Verb Types (127)
Brainy supports 127 relationship types organized into categories:
**Foundational (7)**
- `VerbType.InstanceOf`, `VerbType.SubclassOf`, `VerbType.ParticipatesIn`
- `VerbType.RelatedTo`, `VerbType.Contains`, `VerbType.PartOf`, `VerbType.References`
**Spatial & Temporal (14)**
- Location: `LocatedAt`, `AdjacentTo`, `ContainsSpatially`, `OverlapsSpatially`, `Above`, `Below`, `Inside`, `Outside`, `Facing`
- Time: `Precedes`, `During`, `OccursAt`, `Overlaps`, `ImmediatelyAfter`, `SimultaneousWith`
**Causal & Dependency (11)**
- Direct: `Causes`, `Enables`, `Prevents`, `DependsOn`, `Requires`
- Modal: `CanCause`, `MustCause`, `WouldCauseIf`, `ProbablyCauses`
- Variations: `RigidlyDependsOn`, `FunctionallyDependsOn`, `HistoricallyDependsOn`
**Creation & Change (10)**
- Lifecycle: `Creates`, `Transforms`, `Becomes`, `Modifies`, `Consumes`, `Destroys`
- Properties: `GainsProperty`, `LosesProperty`, `RemainsSame`, `PersistsThrough`
**Social & Communication (8)**
- `MemberOf`, `WorksWith`, `FriendOf`, `Follows`, `Likes`, `ReportsTo`, `Mentors`, `Communicates`
**Epistemic & Modal (14)**
- Knowledge: `Knows`, `Doubts`, `Believes`, `Learns`
- Mental states: `Desires`, `Intends`, `Fears`, `Loves`, `Hates`, `Hopes`, `Perceives`
- Modality: `CouldBe`, `MustBe`, `Counterfactual`
**Measurement & Comparison (9)**
- `Measures`, `MeasuredIn`, `ConvertsTo`, `HasMagnitude`, `GreaterThan`
- `SimilarityDegree`, `ApproximatelyEquals`, `MoreXThan`, `HasDegree`
**And 54 more specialized verbs** including ownership, composition, uncertainty, deontic relationships (obligations/permissions), context-dependent truth, spatial/temporal variations, information theory, and meta-level relationships.
### Complete Reference
For the full taxonomy with all 169 types and their descriptions, see:
- **[Stage 3 CANONICAL Taxonomy](../STAGE3-CANONICAL-TAXONOMY.md)** - Complete list with categories
- **[Noun-Verb Taxonomy Architecture](../architecture/noun-verb-taxonomy.md)** - Design rationale
### Migration from v5.4.0
**Breaking Changes:**
- `NounType.Content` removed → Use `Document`, `Message`, or `InformationContent`
- `NounType.User` removed → Use `Person` or `Agent`
- `NounType.Topic` removed → Use `Concept` or `Category`
**New Types Added:**
- **+11 noun types**: Agent, Organism, Substance, Quality, TimeInterval, Function, Proposition, Custom, SocialGroup, Institution, Norm, InformationContent, InformationBearer, Relationship
- **+87 verb types**: Extensive additions across all categories
---
## What's New in v5.0 ## What's New in v5.0
### v5.3.0 (Latest) ### v5.3.0 (Latest)