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

feat: add VFS methods and fix documentation accuracy

Browse source 
- Add exportToJSON() for directory structure export
- Add searchEntities() for advanced entity filtering
- Add bulkWrite() for efficient batch operations
- Fix VFS documentation to accurately reflect implementation
- Add USER_FUNCTIONS.md with domain-specific templates
- Clarify Knowledge Layer augmentation pattern
- Correct GitBridge integration examples
This commit is contained in:
David Snelling 2025-09-25 12:12:20 -07:00
parent a4ed075e5f
commit 7730b88618
6 changed files with 1150 additions and 131 deletions
Download patch file Download diff file Expand all files Collapse all files

247
docs/vfs/VFS_EXAMPLES_SCENARIOS.md
View file

@ -2,7 +2,14 @@
## Real-World Scenarios
This document demonstrates how VFS with Knowledge Layer enables powerful real-world applications. All examples show actual working code.
This document demonstrates how VFS with Knowledge Layer enables powerful real-world applications.
### Legend
- ✅ **Real VFS methods** - Fully implemented and working
- 📝 **User functions** - Templates available in [USER_FUNCTIONS.md](./USER_FUNCTIONS.md)
- 🔮 **Future features** - Not yet available (AI augmentations)
**Note:** All ✅ marked methods are production-ready. For 📝 methods, see USER_FUNCTIONS.md for implementation templates.
## Scenario 1: Collaborative Novel Writing
@ -19,13 +26,13 @@ async function novelWritingProject() {
await vfs.init()
await vfs.enableKnowledgeLayer()
// Create project structure
// Create project structure ✅
await vfs.mkdir('/novel')
await vfs.mkdir('/novel/chapters')
await vfs.mkdir('/novel/characters')
await vfs.mkdir('/novel/worldbuilding')
// Define main characters as persistent entities
// Define main characters as persistent entities ✅
const protagonist = await vfs.createEntity({
name: 'Elena Blackwood',
type: 'character',
@ -61,7 +68,7 @@ async function novelWritingProject() {
}
})
// Link entities
// Link entities ✅
await vfs.linkEntities(protagonist.id, city.id, 'lives_in')
await vfs.linkEntities(protagonist.id, antagonist.id, 'investigates')
@ -77,7 +84,7 @@ async function novelWritingProject() {
infiltrate the Crypto Quarter facility.
`)
// Multiple authors can work simultaneously
// Multiple authors can work simultaneously ✅
vfs.setUser('author-alice')
await vfs.writeFile('/novel/chapters/chapter2.md', `
# Chapter 2: The Void Industries Tower
@ -92,17 +99,17 @@ async function novelWritingProject() {
He smiled. Let her come. The trap was already set.
`)
// Track character appearances across chapters
// Track character appearances across chapters ✅
const elenaAppearances = await vfs.findEntityOccurrences(protagonist.id)
console.log('Elena appears in:', elenaAppearances.map(f => f.path))
// Find all locations mentioned
// Find all locations mentioned ✅
const locations = await vfs.listEntities({ type: 'location' })
// Generate character relationship graph
// Generate character relationship graph ✅
const relationships = await vfs.getEntityGraph(protagonist.id, { depth: 2 })
// Track plot threads using concepts
// Track plot threads using concepts ✅
await vfs.createConcept({
name: 'The Void Conspiracy',
type: 'plot',
@ -111,17 +118,17 @@ async function novelWritingProject() {
keywords: ['scientists', 'experiments', 'void industries', 'conspiracy']
})
// Find all chapters related to the conspiracy
// Find all chapters related to the conspiracy ✅
const conspiracyChapters = await vfs.findByConcept('The Void Conspiracy')
// Version control for revisions
// Version control for revisions ✅
const chapterVersions = await vfs.getVersions('/novel/chapters/chapter1.md')
// Collaborative editing history
// Collaborative editing history ✅
const history = await vfs.getCollaborationHistory('/novel/chapters/chapter2.md')
console.log('Chapter 2 edited by:', history.map(h => h.user))
// Export for publishing
// Export for publishing ✅
const manuscript = await vfs.exportToMarkdown('/novel/chapters')
await vfs.close()
@ -234,7 +241,7 @@ async function gameDevProject() {
export default CombatSystem
`)
// Asset management
// Asset management ✅
await vfs.writeFile('/game/assets/sprites/elder_sage.png', spriteData)
await vfs.setMetadata('/game/assets/sprites/elder_sage.png', {
dimensions: '64x64',
@ -243,23 +250,23 @@ async function gameDevProject() {
license: 'CC-BY-4.0'
})
// Track dependencies
// Track dependencies ✅
await vfs.addRelationship('/game/quests/main_quest.json', '/game/npcs/elder_sage.json', 'uses')
await vfs.addRelationship('/game/scripts/combat.js', '/game/systems/stats.js', 'imports')
// Find all content related to combat
// Find all content related to combat ✅
const combatFiles = await vfs.findByConcept('Combat System')
// Get all NPCs in a specific location
// Get all NPCs in a specific location ✅
const villageNPCs = await vfs.searchEntities({
type: 'npc',
where: { 'attributes.location': 'Village Square' }
})
// Track game balance changes
// Track game balance changes ✅
const balanceHistory = await vfs.getHistory('/game/data/balance.json')
// Collaborative development tracking
// Collaborative development tracking ✅
await vfs.addTodo('/game/quests/main_quest.json', {
task: 'Add voice dialogue triggers',
priority: 'medium',
@ -267,7 +274,7 @@ async function gameDevProject() {
assignee: 'audio-team'
})
// Export for build system
// Export for build system ✅
const gameData = await vfs.exportToJSON('/game')
await vfs.close()
@ -288,7 +295,7 @@ async function softwareProject() {
await vfs.init()
await vfs.enableKnowledgeLayer()
// Import existing git repository
// Import existing git repository ✅ (Knowledge Layer provides wrapper)
await vfs.importFromGit('/local/repos/webapp', '/project')
// Define architectural concepts
@ -397,43 +404,43 @@ async function softwareProject() {
\`\`\`
`)
// Find all files needing security review
// Find all files needing security review ✅
const securityFiles = await vfs.search('authentication password jwt oauth', {
path: '/project/src',
type: 'file'
})
// Get project insights
const insights = await vfs.getInsights('/project')
// Get project insights 📝 (see USER_FUNCTIONS.md for getProjectInsights)
const insights = await getProjectInsights(vfs, '/project') // User function
console.log('Most modified files:', insights.hotspots)
console.log('Key concepts:', insights.concepts)
console.log('Team activity:', insights.contributors)
// Find circular dependencies
const circularDeps = await vfs.findCircularDependencies('/project/src')
// Find circular dependencies 📝 (see USER_FUNCTIONS.md)
const circularDeps = await findCircularDependencies(vfs, '/project/src') // User function
// Get test coverage relationships
const untested = await vfs.findUntestedCode('/project/src')
// Get test coverage relationships 📝 (see USER_FUNCTIONS.md)
const untested = await findUntestedCode(vfs, '/project/src') // User function
// Track technical debt
// Track technical debt ✅
const todos = await vfs.getAllTodos('/project')
const highPriorityDebt = todos.filter(t => t.priority === 'high' && t.status === 'pending')
// Generate dependency graph
const depGraph = await vfs.getDependencyGraph('/project/src')
// Generate dependency graph 📝 (see USER_FUNCTIONS.md)
const depGraph = await getDependencyGraph(vfs, '/project/src') // User function
// Find similar code (potential refactoring)
const similarCode = await vfs.findSimilarCode('/project/src/auth/login.ts', {
// Find similar code (potential refactoring) 📝 (see USER_FUNCTIONS.md)
const similarCode = await findSimilarCode(vfs, '/project/src/auth/login.ts', {
threshold: 0.8,
minLines: 10
})
}) // User function
// Export for CI/CD
// Export for CI/CD ✅ (Knowledge Layer provides wrapper)
await vfs.exportToGit('/project', '/tmp/build-output')
// Collaborative features
vfs.setUser('developer-alice')
const conflicts = await vfs.detectConflicts('/project/src/auth/login.ts')
// Collaborative features ✅ / 🔮
vfs.setUser('developer-alice') // ✅ Real method
// const conflicts = await vfs.detectConflicts('/project/src/auth/login.ts') // 🔮 Future feature
await vfs.close()
await brain.close()
@ -486,7 +493,7 @@ async function unifiedKnowledgeBase() {
role: 'detective'
}]))
// Cross-project entity tracking
// Cross-project entity tracking ✅
const elenaOccurrences = await vfs.findEntityOccurrences(sharedCharacter.id)
console.log('Elena appears across projects:', elenaOccurrences)
@ -497,36 +504,36 @@ async function unifiedKnowledgeBase() {
domain: 'software'
})
// Find auth implementations across all projects
// Find auth implementations across all projects ✅
const authImplementations = await vfs.findByConcept('Authentication')
// Returns: /webapp/src/auth.js, /game/scripts/player-auth.js, etc.
// Cross-project relationships
// Cross-project relationships ✅
await vfs.addRelationship('/novel/chapter1.md', '/game/story/intro.txt', 'inspires')
await vfs.addRelationship('/game/npcs/elena.json', '/novel/characters/elena.md', 'based_on')
// Universal search across all projects
// Universal search across all projects ✅
const results = await vfs.search('Elena Blackwood authentication', {
path: '/',
recursive: true
})
// Project statistics
const novelStats = await vfs.getProjectStats('/novel')
const gameStats = await vfs.getProjectStats('/game')
const webappStats = await vfs.getProjectStats('/webapp')
// Project statistics 📝 (see USER_FUNCTIONS.md for getProjectStats)
const novelStats = await getProjectStats(vfs, '/novel') // User function
const gameStats = await getProjectStats(vfs, '/game') // User function
const webappStats = await getProjectStats(vfs, '/webapp') // User function
console.log('Total files:', novelStats.fileCount + gameStats.fileCount + webappStats.fileCount)
console.log('Total size:', novelStats.totalSize + gameStats.totalSize + webappStats.totalSize)
// Knowledge graph visualization data
const knowledgeGraph = await vfs.getGlobalKnowledgeGraph()
// Knowledge graph visualization data 🔮 (future feature)
// const knowledgeGraph = await vfs.getGlobalKnowledgeGraph() // Not yet implemented
// Returns nodes (files, entities, concepts) and edges (relationships)
// Find connections between projects
const crossProjectLinks = await vfs.findCrossProjectLinks()
// Find connections between projects 🔮 (future feature)
// const crossProjectLinks = await vfs.findCrossProjectLinks() // Not yet implemented
// Unified timeline
// Unified timeline ✅
const timeline = await vfs.getTimeline({
from: '2025-01-01',
to: '2025-12-31'
@ -539,101 +546,135 @@ async function unifiedKnowledgeBase() {
## Advanced Features
### Semantic Code Analysis
### Semantic Code Analysis 📝
These are user functions - see [USER_FUNCTIONS.md](./USER_FUNCTIONS.md) for implementation templates:
```javascript
// Find security vulnerabilities
const vulnerabilities = await vfs.findPatterns([
// Find security vulnerabilities (user function example)
const vulnerabilities = await findPatterns(vfs, [
'eval(',
'innerHTML =',
'SQL injection',
'hardcoded password'
])
// Find code smells
const codeSmells = await vfs.analyzeCodeQuality('/src', {
// Find code smells (user function example)
const codeSmells = await analyzeCodeQuality(vfs, '/src', {
checkDuplication: true,
checkComplexity: true,
checkNaming: true
})
```
### AI-Powered Features
### AI-Powered Features 🔮
**Note:** These features require AI integration and are not yet available.
```javascript
// Generate documentation
const docs = await vfs.generateDocumentation('/src/auth/login.ts')
// Future: Generate documentation
// const docs = await vfs.generateDocumentation('/src/auth/login.ts')
// Suggest refactorings
const refactorings = await vfs.suggestRefactorings('/src/utils.js')
// Future: Suggest refactorings
// const refactorings = await vfs.suggestRefactorings('/src/utils.js')
// Auto-complete code
const completion = await vfs.completeCode('/src/api.ts', { line: 42, column: 10 })
// Future: Auto-complete code
// const completion = await vfs.completeCode('/src/api.ts', { line: 42, column: 10 })
```
### Migration and Backup
### Migration and Backup 🔮
**Note:** These features are planned but not yet implemented.
```javascript
// Backup with full history
await vfs.createBackup('/backup/2025-01-20.brainy')
// Future: Backup with full history
// await vfs.createBackup('/backup/2025-01-20.brainy')
// Migrate between storage backends
const migration = await vfs.migrate({
from: { type: 'file', path: './old-data' },
to: { type: 's3', bucket: 'new-bucket' }
})
// Future: Migrate between storage backends
// const migration = await vfs.migrate({
// from: { type: 'file', path: './old-data' },
// to: { type: 's3', bucket: 'new-bucket' }
// })
// Incremental sync
await vfs.sync('/local/path', '/vfs/path', {
bidirectional: true,
conflictStrategy: 'newest'
})
// Future: Incremental sync
// await vfs.sync('/local/path', '/vfs/path', {
// bidirectional: true,
// conflictStrategy: 'newest'
// })
```
### Performance at Scale
```javascript
// Handle millions of files
// Handle millions of files ✅
for (let i = 0; i < 1000000; i++) {
await vfs.writeFile(`/data/file${i}.txt`, `Content ${i}`)
// Uses chunking, compression, and efficient indexing
}
// Fast parallel operations
// Fast parallel operations ✅
await Promise.all([
vfs.writeFile('/file1.txt', 'data1'),
vfs.writeFile('/file2.txt', 'data2'),
vfs.writeFile('/file3.txt', 'data3')
])
// Bulk imports
await vfs.bulkImport('/massive/dataset', {
parallel: 10,
batchSize: 1000,
progress: (count, total) => console.log(`${count}/${total}`)
})
// Bulk write operations ✅
const files = [
{ path: '/data/file1.txt', content: 'Content 1' },
{ path: '/data/file2.txt', content: 'Content 2' },
// ... more files
]
await vfs.bulkWrite(files)
// Bulk imports 🔮 (future feature)
// await vfs.bulkImport('/massive/dataset', {
// parallel: 10,
// batchSize: 1000,
// progress: (count, total) => console.log(`${count}/${total}`)
// })
```
## Real Implementation Notes
## Implementation Status
All examples in this document use actual VFS APIs that are fully implemented:
### ✅ Fully Implemented Features
1. **Storage**: Real Brainy entities, not mock data
2. **Embeddings**: Real vector embeddings via brain.embed()
3. **Relationships**: Real graph relationships via brain.relate()
4. **Search**: Real semantic search via brain.search()
5. **Events**: Real event recording in Knowledge Layer
6. **Versions**: Real semantic versioning based on similarity
7. **Entities**: Real persistent entity tracking
8. **Concepts**: Real concept detection and management
9. **Git**: Real GitBridge import/export functionality
All methods marked with ✅ are production-ready:
This is production-ready code with:
- No stubs or mocks
- Complete error handling
- Full async/await support
- Proper resource cleanup
- Thread-safe operations
- Scalable architecture
1. **Core VFS Operations**: mkdir, writeFile, readFile, appendFile, stat, readdir, etc.
2. **Entity System**: createEntity, linkEntities, findEntityOccurrences, updateEntity, getEntityGraph
3. **Concept System**: createConcept, findByConcept
4. **Knowledge Layer**: Event recording, semantic versioning, collaboration tracking
5. **Search**: Triple Intelligence (vector + field + graph)
6. **Git Integration**: importFromGit, exportToGit
7. **Export Formats**: exportToMarkdown, exportToJSON
8. **Bulk Operations**: bulkWrite for efficient batch processing
9. **Project Management**: todos, metadata, relationships
The VFS + Knowledge Layer combination enables these scenarios and more, providing a foundation for intelligent applications that understand and manage knowledge.
### 📝 User Functions
Methods marked with 📝 are domain-specific functions that you can implement using VFS primitives. See [USER_FUNCTIONS.md](./USER_FUNCTIONS.md) for ready-to-use templates:
- **Code Analysis**: getDependencyGraph, findCircularDependencies, findUntestedCode, findSimilarCode
- **Creative Writing**: trackCharacterArc, generateStoryBible
- **Game Development**: validateGameData, generateLootTables
- **Project Management**: getProjectInsights, generateSprintReport
- **Export Formats**: exportToEpub, exportToStaticSite
### 🔮 Future Features
Methods marked with 🔮 require AI integration or are planned for future releases:
- **AI-Powered**: generateDocumentation, suggestRefactorings, completeCode
- **Advanced Analysis**: detectConflicts, getGlobalKnowledgeGraph, findCrossProjectLinks
- **Migration Tools**: createBackup, migrate, sync, bulkImport
## Real Implementation Guarantees
- **No Mocks**: Every ✅ method is fully functional
- **Real Storage**: Uses Brainy entities with embeddings
- **Real Search**: Triple Intelligence combining vectors, fields, and graphs
- **Real Relationships**: Graph-based connections via brain.relate()
- **Production Ready**: Complete error handling, async/await, resource cleanup
The VFS + Knowledge Layer combination provides a solid foundation for intelligent applications. Use the ✅ methods directly, implement 📝 functions as needed for your domain, and stay tuned for 🔮 features.