brainy/docs/architecture/triple-intelligence.md

---
title: Triple Intelligence
slug: concepts/triple-intelligence
public: true
category: concepts
template: concept
order: 1
description: Unified vector similarity, graph traversal, and metadata filtering in one query. Auto-optimizes between parallel execution and progressive filtering.
next:
  - concepts/noun-types
  - api/reference
---

# Triple Intelligence System

The Triple Intelligence System is Brainy's revolutionary query engine that unifies vector similarity, graph relationships, and metadata filtering into a single, optimized query interface.

## Overview

Traditional databases force you to choose between vector search, graph traversal, OR metadata filtering. Brainy combines all three intelligences into one magical API that automatically optimizes execution for maximum performance.

## Query Interface

### Unified Query Structure

`find()` accepts a single `FindParams` object (or a natural-language string). One
object combines all three intelligences:

```typescript
interface FindParams {
  // Vector intelligence — semantic similarity
  query?: string                 // Natural-language / semantic query (embedded, matched via HNSW + text index)
  vector?: number[]              // Pre-computed embedding for direct vector search

  // Metadata intelligence — structured field filters
  type?: NounType | NounType[]   // Filter by entity type
  subtype?: string | string[]    // Filter by per-product subtype
  where?: Record<string, any>    // Field predicates with bare operators (gte, lt, in, contains, exists…)

  // Graph intelligence — relationship traversal
  connected?: {
    to?: string                  // Reachable to this entity
    from?: string                // Reachable from this entity
    via?: VerbType | VerbType[]  // Relationship type(s) to traverse (alias: type)
    depth?: number               // Max traversal depth (default: 1)
    direction?: 'in' | 'out' | 'both'
  }

  // Proximity — nearest neighbours of a known entity
  near?: { id: string; threshold?: number }

  // Control
  limit?: number                 // Max results (default: 10)
  offset?: number                // Skip N results
  orderBy?: string               // Field to sort by (e.g. 'createdAt')
  order?: 'asc' | 'desc'         // Sort direction
}
```

### Example Queries

#### Natural Language Queries with find()
```typescript
// Brainy understands natural language and extracts intent
const results = await brain.find("research papers about neural networks from 2023")
// Automatically interprets: document type, topic, time range

// Complex temporal and numeric queries
const reports = await brain.find("quarterly reports from Q3 2024 with revenue over 10M")
// Automatically extracts: report type, date range, numeric filters

// Multi-condition natural language
const articles = await brain.find("verified articles by John Smith about machine learning published this year")
// Automatically identifies: author, topic, verification status, time range
```

#### Simple Vector Search
```typescript
const results = await brain.find("machine learning concepts")
```

#### Combined Intelligence Query
```typescript
const results = await brain.find({
  query: "neural networks",
  where: {
    category: "research",
    year: { gte: 2023 }
  },
  connected: {
    to: "deep-learning-team",
    depth: 2
  },
  limit: 20
})
```

## Query Optimization

### Automatic Plan Generation

The Triple Intelligence engine analyzes each query to create an optimal execution plan:

1. **Selectivity Analysis**: Identifies the most selective filters
2. **Cost Estimation**: Estimates computational cost for each operation
3. **Strategy Selection**: Chooses between parallel or progressive execution
4. **Plan Caching**: Caches successful plans for similar queries

### Execution Strategies

#### Parallel Execution
All three search types execute simultaneously:
- **Best for**: Balanced queries with multiple signals
- **Performance**: Maximum speed through parallelization
- **Use case**: Complex queries needing all intelligence types

```typescript
// Parallel execution for balanced query
const results = await brain.find({
  query: "AI research",          // ~1000 potential matches
  where: { kind: "paper" },       // ~500 potential matches
  connected: { to: "stanford" }   // ~200 potential matches
})
// All three execute in parallel, results fused
```

#### Progressive Filtering
Operations chain for maximum efficiency:
- **Best for**: Queries with highly selective filters
- **Performance**: Reduces search space at each step
- **Use case**: Large datasets with specific criteria

```typescript
// Progressive execution for selective query
const results = await brain.find({
  where: { userId: "user123" },   // Very selective (1-10 matches)
  query: "recent posts",           // Applied to filtered set
  limit: 5
})
// Metadata filter first, then vector search on results
```

## Fusion Ranking

### Score Combination

When multiple intelligence types return results, scores are intelligently combined:

```typescript
fusionScore = (
  vectorScore * vectorWeight +    // Semantic relevance (0.4)
  graphScore * graphWeight +      // Relationship strength (0.3)
  fieldScore * fieldWeight        // Exact match confidence (0.3)
) / totalWeight
```

### Adaptive Weights

Weights adjust based on query characteristics:
- **Text-heavy query**: Higher vector weight
- **Relationship query**: Higher graph weight  
- **Specific filters**: Higher field weight

## Natural Language Processing

### Pattern Recognition

Brainy includes 220+ embedded patterns for natural language understanding:

```typescript
// Natural language automatically parsed
const results = await brain.find(
  "show me recent AI papers from Stanford published this year"
)
// Automatically converts to:
// {
//   query: "AI papers",
//   where: {
//     institution: "Stanford",
//     published: { gte: "2024-01-01" }
//   }
// }
```

### Intent Detection

The NLP processor identifies query intent:
- **Informational**: "what is", "how does"
- **Navigational**: "find", "show me"
- **Transactional**: "create", "update"
- **Analytical**: "compare", "analyze"

## Performance Optimization

### Query Plan Caching

Successful execution plans are cached:
```typescript
// First call parses the natural-language query and builds an execution plan
await brain.find("machine learning papers")

// A structurally similar query reuses that plan, skipping plan generation
await brain.find("deep learning papers")
```

### Self-Optimization

Brainy uses itself to optimize queries:
- Query patterns stored in separate brain instance
- Execution times tracked and analyzed
- Plans automatically improved based on performance

### Index Utilization

Triple Intelligence leverages all available indexes:
- **HNSW Index**: For vector similarity
- **Metadata Index**: For metadata filtering
- **Graph Index**: For relationship traversal

## Advanced Features

### Explain Mode

Diagnose how a query's `where` fields map to the index. Run `brain.explain()`
first whenever `find()` returns surprising or empty results:

```typescript
const plan = await brain.explain({
  query: "quantum computing",
  where: { category: "research" }
})

console.log(plan.fieldPlan)
// [
//   { field: 'category', path: 'column-store', notes: '...' }
// ]

console.log(plan.warnings)
// e.g. ['Field "category" has no index entries. find() will return [] silently...']
```

### Result Ordering

Sort results by any stored field with `orderBy` / `order`:

```typescript
const results = await brain.find({
  query: "news articles",
  where: { verified: true },
  orderBy: 'createdAt',  // Newest first
  order: 'desc'
})
```

### Similarity Threshold

Find the nearest neighbours of a known entity and keep only close matches with
`near`:

```typescript
const results = await brain.find({
  near: { id: anchorId, threshold: 0.9 },  // Only results >= 0.9 similarity
  limit: 10
})
```

## Best Practices

### Query Design

1. **Start specific**: Use selective filters when possible
2. **Combine intelligently**: Don't force all three types if not needed
3. **Use limits**: Always specify reasonable result limits
4. **Cache results**: For repeated queries, cache at application level

### Performance Tips

1. **Index first**: Ensure fields used in `where` clauses are indexed
2. **Batch operations**: Use batch methods for bulk queries
3. **Monitor plans**: Use explain mode to understand performance
4. **Optimize patterns**: Train custom patterns for your domain

### Common Patterns

#### Semantic Search with Filtering
```typescript
// Find similar content with constraints
const results = await brain.find({
  query: searchText,
  where: {
    status: 'published',
    language: 'en'
  }
})
```

#### Related Items Discovery
```typescript
// Find items related to a specific item
const results = await brain.find({
  connected: {
    to: itemId,
    depth: 2,
    via: VerbType.RelatedTo
  },
  limit: 20
})
```

#### Time-based Queries
```typescript
// Recent items matching criteria
const results = await brain.find({
  where: {
    timestamp: { gte: Date.now() - 86400000 }
  },
  query: "trending topics",
  orderBy: 'timestamp',
  order: 'desc'
})
```

## Natural Language Processing

The `find()` method includes advanced NLP capabilities powered by 220+ embedded patterns that understand natural language queries.

### Supported Query Types

```typescript
// Temporal queries
await brain.find("documents from last week")
await brain.find("reports created yesterday")
await brain.find("articles published in Q3 2024")
await brain.find("data from January to March")

// Numeric filters
await brain.find("products with price under $100")
await brain.find("articles with more than 1000 views")
await brain.find("reports showing revenue over 10M")

// Combined conditions
await brain.find("verified research papers about AI from 2024 with high citations")
await brain.find("recent customer reviews with rating above 4 stars")
await brain.find("blog posts by John Smith about machine learning published this month")

// Relationship queries
await brain.find("documents related to project X")
await brain.find("people who work at TechCorp")
await brain.find("products similar to iPhone")
```

### How It Works

1. **Intent Detection**: Identifies what the user is looking for
2. **Entity Extraction**: Extracts names, dates, numbers, categories
3. **Temporal Parsing**: Converts "last week", "Q3 2024" to date ranges
4. **Filter Generation**: Creates appropriate where clauses
5. **Query Fusion**: Combines NLP understanding with vector search

### Pattern Coverage

Brainy includes 220+ pre-computed patterns covering:
- **Temporal**: 40+ patterns for dates and time ranges
- **Numeric**: 30+ patterns for comparisons and ranges
- **Relationships**: 25+ patterns for connections
- **Actions**: 35+ patterns for verbs and intents
- **Entities**: 40+ patterns for people, places, things
- **Domain-specific**: 50+ patterns for tech, business, social

## API Reference

See the [Triple Intelligence API](../api/triple-intelligence.md) for complete method documentation.