Commit graph

2 commits

Author SHA1 Message Date
1a98e4276a feat: queryAggregate() + HAVING, plus aggregate backfill, traversal depth/via, extraction typing (BR-ADV-FEATURES-BUN)
New report APIs:
- brain.queryAggregate(name, params) returns the clean AggregateResult[] shape
  ({ groupKey, metrics, count }) directly, instead of the search-Result wrapper that
  find({ aggregate }) returns.
- HAVING: find({ aggregate, having }) and queryAggregate filter groups by computed
  metric values (e.g. revenue > 1000), complementing where (which filters group keys).
  Evaluated per group: O(groups), independent of entity count.

Fixes (all reproducible on Node; surfaced under Cortex+Bun by Memory):
- Aggregate backfill-on-define: defining an aggregate over a store that already holds
  matching entities returned []. It now backfills from existing entities on first query
  (storage-agnostic via getNouns), so it works under durable backends that reopen
  pre-populated. groupBy:['noun'] resolves to the entity type; find({ aggregate }) rows
  expose groupKey/metrics/count at the top level.
- Multi-hop find({ connected: { depth, via } }) honors depth and via at every hop
  (was 1-hop only, with verb filtering applied to hop 1 only); BFS bounded by limit.
- extractEntities no longer bleeds a neighbour's type indicator across candidates; each
  candidate is typed by its own span. Also fixes the "Dr." title pattern.

Adds real-embedding regression tests; full unit suite green.
2026-05-26 13:55:43 -07:00
8cca096d7e feat: expose neural entity extraction APIs (v5.7.6 - Workshop request)
Addresses Workshop team's request for direct access to neural extraction classes.

**Changes:**

1. **New Exports** (src/index.ts):
   - `NeuralEntityExtractor` - Full extraction orchestrator
   - `SmartExtractor` - Entity type classifier (4-signal ensemble)
   - `SmartRelationshipExtractor` - Relationship type classifier
   - Types: `ExtractedEntity`, `ExtractionResult`, `RelationshipExtractionResult`, etc.

2. **Package.json Subpath Exports**:
   ```typescript
   // Enable direct imports:
   import { NeuralEntityExtractor } from '@soulcraft/brainy/neural/entityExtractor'
   import { SmartExtractor } from '@soulcraft/brainy/neural/SmartExtractor'
   import { SmartRelationshipExtractor } from '@soulcraft/brainy/neural/SmartRelationshipExtractor'
   ```

3. **New brain.extractEntities() Method** (brainy.ts:3254):
   - Alias for `brain.extract()` with clearer naming
   - Documented with examples and architecture details
   - 4-signal ensemble: ExactMatch (40%) + Embedding (35%) + Pattern (20%) + Context (5%)

4. **Comprehensive Documentation** (docs/neural-extraction.md):
   - Complete neural extraction guide (200+ lines)
   - API reference for all extraction classes
   - Performance optimization tips
   - Import preview mode documentation
   - Confidence scoring explanation
   - 42 NounType detection methods
   - Troubleshooting guide
   - Real-world examples

5. **README Updates**:
   - Added "Entity Extraction" section with examples
   - Links to neural extraction guide
   - Import preview mode link

**Features:**
-  Fast extraction: ~15-20ms per entity
- 🎯 4-signal ensemble architecture
- 📊 Format intelligence (Excel, CSV, PDF, YAML, DOCX, JSON, Markdown)
- 🌍 42 universal noun types + 127 verb types
- 💾 LRU caching built-in
- 🧪 Production-tested in import pipeline

**Usage:**

```typescript
// Simple API (recommended)
const entities = await brain.extractEntities('John Smith founded Acme Corp', {
  types: [NounType.Person, NounType.Organization],
  confidence: 0.7
})

// Advanced API (custom configuration)
import { SmartExtractor } from '@soulcraft/brainy'

const extractor = new SmartExtractor(brain, { minConfidence: 0.8 })
const result = await extractor.extract('CEO', {
  formatContext: { format: 'excel', columnHeader: 'Title' }
})
```

**Backward Compatible:** All existing APIs unchanged. New exports are pure additions.

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

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-13 09:01:56 -08:00