brainy/docs/architecture/noun-verb-taxonomy.md

Noun-Verb Taxonomy Architecture

Overview

Brainy 2.0 introduces a revolutionary Noun-Verb Taxonomy that models data as entities (nouns) and relationships (verbs), creating a semantic knowledge graph that mirrors how humans naturally think about information.

Why Noun-Verb?

Traditional databases force you to think in tables, documents, or nodes. Brainy lets you think naturally:

• Nouns: Things that exist (people, documents, products, concepts)
• Verbs: How things relate (creates, owns, references, similar-to)

This simple mental model scales from basic storage to complex knowledge graphs while remaining intuitive.

Core Concepts

Nouns (Entities)

Nouns represent any entity in your system:

// Add any entity as a noun
const personId = await brain.addNoun("John Smith, Senior Engineer", {
  type: "person",
  department: "engineering",
  skills: ["TypeScript", "React", "Node.js"]
})

const documentId = await brain.addNoun("Q3 2024 Financial Report", {
  type: "document",
  category: "financial",
  confidential: true,
  created: "2024-10-01"
})

const conceptId = await brain.addNoun("Machine Learning", {
  type: "concept",
  domain: "technology",
  complexity: "advanced"
})

Noun Properties

Every noun automatically gets:

• Unique ID: System-generated or custom
• Vector Embedding: For semantic similarity
• Metadata: Flexible JSON properties
• Timestamps: Created/updated tracking
• Indexing: Automatic field indexing

Verbs (Relationships)

Verbs define how nouns relate to each other:

// Create relationships between entities
await brain.addVerb(personId, documentId, "authored", {
  role: "primary_author",
  contribution: "80%"
})

await brain.addVerb(documentId, conceptId, "discusses", {
  sections: ["methodology", "results"],
  depth: "detailed"
})

await brain.addVerb(personId, conceptId, "expert_in", {
  years_experience: 5,
  certification: "Advanced ML Certification"
})

Verb Properties

Every verb includes:

• Source: The noun initiating the relationship
• Target: The noun receiving the relationship
• Type: The relationship type/name
• Direction: Directional or bidirectional
• Metadata: Relationship-specific data
• Strength: Optional relationship weight

Benefits

1. Natural Mental Model

// Think naturally about your data
const taskId = await brain.addNoun("Implement payment system")
const userId = await brain.addNoun("Alice Johnson")
const projectId = await brain.addNoun("E-commerce Platform")

// Express relationships clearly
await brain.addVerb(userId, taskId, "assigned_to")
await brain.addVerb(taskId, projectId, "part_of")
await brain.addVerb(userId, projectId, "manages")

2. Semantic Understanding

The noun-verb model preserves meaning:

// The system understands semantic relationships
const results = await brain.find("tasks assigned to Alice")
// Automatically understands: assigned_to verb + Alice noun

const related = await brain.find("people who manage projects with payment tasks")
// Traverses: person -> manages -> project -> contains -> task

3. Flexible Schema

No rigid schema requirements:

// Add any noun type without schema changes
await brain.addNoun("New IoT Sensor", { 
  type: "device",
  protocol: "MQTT",
  location: "Building A"
})

// Create new relationship types on the fly
await brain.addVerb(sensorId, buildingId, "monitors", {
  metrics: ["temperature", "humidity"],
  interval: "5 minutes"
})

4. Graph Traversal

Navigate relationships naturally:

// Find all documents authored by team members
const teamDocs = await brain.find({
  connected: {
    from: teamId,
    through: ["member_of", "authored"],
    depth: 2
  }
})

// Find similar products purchased by similar users
const recommendations = await brain.find({
  connected: {
    from: userId,
    through: ["similar_to", "purchased"],
    depth: 2,
    type: "product"
  }
})

5. Temporal Relationships

Track how relationships change over time:

// Relationships with temporal data
await brain.addVerb(employeeId, companyId, "worked_at", {
  from: "2020-01-01",
  to: "2023-12-31",
  position: "Senior Developer"
})

await brain.addVerb(employeeId, newCompanyId, "works_at", {
  from: "2024-01-01",
  position: "Tech Lead"
})

// Query historical relationships
const employment = await brain.find("where did John work in 2022")

Real-World Use Cases

Knowledge Management

// Documents and their relationships
const paperId = await brain.addNoun("Neural Networks Paper", {
  type: "research_paper",
  year: 2024
})

const authorId = await brain.addNoun("Dr. Sarah Chen", {
  type: "researcher"
})

const topicId = await brain.addNoun("Deep Learning", {
  type: "topic"
})

// Rich relationship network
await brain.addVerb(authorId, paperId, "authored")
await brain.addVerb(paperId, topicId, "covers")
await brain.addVerb(paperId, otherPaperId, "cites")
await brain.addVerb(authorId, topicId, "researches")

// Query the knowledge graph
const related = await brain.find("papers about deep learning by Sarah Chen")

Social Networks

// Users and connections
const user1 = await brain.addNoun("Alice", { type: "user" })
const user2 = await brain.addNoun("Bob", { type: "user" })
const post = await brain.addNoun("Great article on AI!", { type: "post" })

// Social interactions
await brain.addVerb(user1, user2, "follows")
await brain.addVerb(user2, user1, "follows") // Mutual
await brain.addVerb(user1, post, "created")
await brain.addVerb(user2, post, "liked")
await brain.addVerb(user2, post, "shared")

// Find social patterns
const influencers = await brain.find("users with most followers who post about AI")

E-commerce

// Products and purchases
const product = await brain.addNoun("Wireless Headphones", {
  type: "product",
  price: 99.99,
  category: "electronics"
})

const customer = await brain.addNoun("Customer #12345", {
  type: "customer",
  tier: "premium"
})

// Purchase relationships
await brain.addVerb(customer, product, "purchased", {
  date: "2024-01-15",
  quantity: 1,
  price: 99.99
})

await brain.addVerb(customer, product, "reviewed", {
  rating: 5,
  text: "Excellent sound quality!"
})

// Recommendation queries
const recs = await brain.find("products purchased by customers who bought headphones")

Project Management

// Projects, tasks, and teams
const project = await brain.addNoun("Website Redesign", { type: "project" })
const task = await brain.addNoun("Update homepage", { type: "task" })
const developer = await brain.addNoun("Jane Developer", { type: "person" })
const designer = await brain.addNoun("John Designer", { type: "person" })

// Work relationships
await brain.addVerb(task, project, "belongs_to")
await brain.addVerb(developer, task, "assigned_to")
await brain.addVerb(designer, developer, "collaborates_with")
await brain.addVerb(task, otherTask, "depends_on")

// Project queries
const blockers = await brain.find("tasks that depend on incomplete tasks")
const workload = await brain.find("people assigned to multiple active projects")

Advanced Patterns

Bidirectional Relationships

// Some relationships are naturally bidirectional
await brain.addVerb(user1, user2, "friend_of", { bidirectional: true })
// Automatically creates inverse relationship

Weighted Relationships

// Add strength/weight to relationships
await brain.addVerb(doc1, doc2, "similar_to", {
  similarity_score: 0.95,
  algorithm: "cosine"
})

// Use weights in queries
const stronglyRelated = await brain.find({
  connected: {
    type: "similar_to",
    minWeight: 0.8
  }
})

Relationship Chains

// Follow relationship chains
const results = await brain.find({
  connected: {
    from: userId,
    chain: [
      { type: "owns", to: "company" },
      { type: "produces", to: "product" },
      { type: "uses", to: "technology" }
    ]
  }
})
// Finds: technologies used by products made by companies owned by user

Meta-Relationships

// Relationships about relationships
const verbId = await brain.addVerb(user1, user2, "recommends")
await brain.addVerb(user3, verbId, "endorses", {
  reason: "Accurate recommendation",
  trust_score: 0.9
})

Query Patterns

Finding Nouns

// By type
const people = await brain.find({ where: { type: "person" } })

// By properties
const documents = await brain.find({
  where: {
    type: "document",
    confidential: false,
    created: { $gte: "2024-01-01" }
  }
})

// By similarity
const similar = await brain.find({
  like: "machine learning research",
  where: { type: "document" }
})

Finding Verbs

// Get all relationships for a noun
const relationships = await brain.getVerbs(nounId)

// Find specific relationship types
const authorships = await brain.find({
  verb: {
    type: "authored",
    from: authorId
  }
})

// Find by relationship properties
const recentPurchases = await brain.find({
  verb: {
    type: "purchased",
    where: {
      date: { $gte: "2024-01-01" }
    }
  }
})

Combined Queries

// Find nouns through relationships
const results = await brain.find({
  // Start with similar documents
  like: "AI research",
  // That are authored by
  connected: {
    through: "authored",
    // People who work at
    where: {
      connected: {
        to: "Stanford",
        type: "works_at"
      }
    }
  }
})

Performance Optimizations

Noun Indexing

• Automatic vector indexing for similarity
• Field indexing for metadata queries
• Full-text indexing for content search

Verb Indexing

• Relationship type indexing
• Source/target indexing
• Temporal indexing for time-based queries

Query Optimization

• Automatic query plan optimization
• Parallel execution of independent operations
• Result caching for repeated queries

Best Practices

1. Use Descriptive Types: Make noun and verb types self-documenting
2. Rich Metadata: Include relevant metadata for better querying
3. Consistent Naming: Use consistent verb names across your application
4. Temporal Data: Include timestamps for time-based analysis
5. Bidirectional When Appropriate: Mark symmetric relationships as bidirectional

Migration from Traditional Models

From Relational (SQL)

// Instead of JOIN queries
// SELECT * FROM users JOIN orders ON users.id = orders.user_id

// Use noun-verb relationships
const userId = await brain.addNoun("User", userData)
const orderId = await brain.addNoun("Order", orderData)
await brain.addVerb(userId, orderId, "placed")

// Query naturally
const userOrders = await brain.find({
  connected: { from: userId, type: "placed" }
})

From Document (NoSQL)

// Instead of embedded documents
// { user: { orders: [...] } }

// Use explicit relationships
const userId = await brain.addNoun("User", userData)
for (const order of orders) {
  const orderId = await brain.addNoun("Order", order)
  await brain.addVerb(userId, orderId, "has_order")
}

From Graph Databases

// Similar to graph databases but with added benefits:
// 1. Automatic vector embeddings for similarity
// 2. Natural language querying
// 3. Unified with metadata filtering

// Enhanced graph queries
const results = await brain.find("similar users who purchased similar products")

Universal Knowledge Coverage

The Noun-Verb taxonomy is designed to represent all human knowledge through a finite set of fundamental types that can be combined infinitely.

Core Noun Types

1. Person - Individual entities

await brain.addNoun("Albert Einstein", {
  type: "person",
  role: "physicist",
  born: "1879-03-14",
  nationality: "German-American"
})

Covers: Individuals, users, authors, employees, customers, contacts

2. Organization - Collective entities

await brain.addNoun("OpenAI", {
  type: "organization",
  industry: "AI research",
  founded: 2015,
  size: "500-1000"
})

Covers: Companies, institutions, teams, governments, communities

3. Place - Spatial entities

await brain.addNoun("San Francisco", {
  type: "place",
  category: "city",
  coordinates: [37.7749, -122.4194],
  population: 873965
})

Covers: Locations, addresses, regions, venues, virtual spaces

4. Thing - Physical objects

await brain.addNoun("Tesla Model 3", {
  type: "thing",
  category: "vehicle",
  manufacturer: "Tesla",
  year: 2024
})

Covers: Products, devices, equipment, artifacts, physical items

5. Concept - Abstract ideas

await brain.addNoun("Machine Learning", {
  type: "concept",
  domain: "technology",
  complexity: "advanced",
  related: ["AI", "statistics"]
})

Covers: Ideas, theories, principles, methodologies, philosophies

6. Document - Information containers

await brain.addNoun("Quarterly Report Q3 2024", {
  type: "document",
  format: "PDF",
  confidential: true,
  pages: 47
})

Covers: Files, articles, reports, media, records, content

7. Event - Temporal occurrences

await brain.addNoun("Product Launch 2024", {
  type: "event",
  date: "2024-09-15",
  attendees: 500,
  virtual: false
})

Covers: Meetings, incidents, milestones, activities, happenings

8. Process - Sequences of actions

await brain.addNoun("Customer Onboarding", {
  type: "process",
  steps: 5,
  duration: "3 days",
  automated: true
})

Covers: Workflows, procedures, algorithms, lifecycles, methods

9. Metric - Measurable values

await brain.addNoun("Revenue Growth Rate", {
  type: "metric",
  value: 0.23,
  unit: "percentage",
  period: "quarterly"
})

Covers: KPIs, measurements, statistics, scores, quantities

10. State - Conditions or status

await brain.addNoun("System Operational", {
  type: "state",
  category: "health",
  severity: "normal",
  since: Date.now()
})

Covers: Status, conditions, phases, modes, configurations

Core Verb Types

1. Creates - Genesis relationships

await brain.addVerb(authorId, documentId, "creates")

Variations: authors, produces, generates, builds, develops

2. Owns - Possession relationships

await brain.addVerb(userId, assetId, "owns")

Variations: has, possesses, controls, manages, maintains

3. Contains - Compositional relationships

await brain.addVerb(folderId, fileId, "contains")

Variations: includes, comprises, consists-of, has-part

4. Relates - Association relationships

await brain.addVerb(concept1Id, concept2Id, "relates")

Variations: connects, associates, links, corresponds

5. Transforms - Change relationships

await brain.addVerb(processId, inputId, "transforms", { 
  to: outputId 
})

Variations: converts, processes, modifies, evolves

6. Interacts - Action relationships

await brain.addVerb(userId, systemId, "interacts")

Variations: uses, accesses, engages, communicates

7. Depends - Dependency relationships

await brain.addVerb(moduleAId, moduleBId, "depends")

Variations: requires, needs, relies-on, prerequisites

8. Flows - Movement relationships

await brain.addVerb(sourceId, destinationId, "flows")

Variations: moves, transfers, migrates, sends

9. Evaluates - Assessment relationships

await brain.addVerb(reviewerId, proposalId, "evaluates")

Variations: reviews, rates, measures, analyzes

10. Temporal - Time-based relationships

await brain.addVerb(event1Id, event2Id, "precedes")

Variations: follows, during, overlaps, schedules

Why This Covers All Knowledge

1. Mathematical Completeness

The noun-verb model forms a complete graph structure where:

• Any entity can be represented as a noun
• Any relationship can be represented as a verb
• Complex knowledge emerges from simple combinations

2. Semantic Completeness

Every piece of human knowledge falls into one of these categories:

• Entities (who, what, where) → Nouns
• Actions (how, when, why) → Verbs
• Attributes (properties) → Metadata
• Context (conditions) → Graph structure

3. Compositional Power

Simple types combine to represent complex knowledge:

// Complex knowledge from simple building blocks
const researchPaper = await brain.addNoun("AI Ethics Study", {
  type: "document"
})

const researcher = await brain.addNoun("Dr. Smith", {
  type: "person"
})

const institution = await brain.addNoun("MIT", {
  type: "organization"
})

const concept = await brain.addNoun("AI Ethics", {
  type: "concept"
})

// Rich knowledge graph emerges
await brain.addVerb(researcher, researchPaper, "authors")
await brain.addVerb(researcher, institution, "affiliated")
await brain.addVerb(researchPaper, concept, "explores")
await brain.addVerb(institution, researchPaper, "publishes")

4. Domain Independence

The same types work across all domains:

Science:

await brain.addNoun("H2O", { type: "thing", category: "molecule" })
await brain.addNoun("Photosynthesis", { type: "process" })
await brain.addVerb(moleculeId, processId, "participates")

Business:

await brain.addNoun("Q3 Revenue", { type: "metric", value: 10000000 })
await brain.addNoun("Sales Team", { type: "organization" })
await brain.addVerb(teamId, metricId, "achieves")

Social:

await brain.addNoun("John", { type: "person" })
await brain.addNoun("Community Group", { type: "organization" })
await brain.addVerb(personId, groupId, "joins")

5. Temporal Coverage

Handles all temporal aspects:

// Past
await brain.addVerb(personId, companyId, "worked", {
  from: "2010", to: "2020"
})

// Present
await brain.addVerb(personId, projectId, "manages", {
  since: "2024-01-01"
})

// Future
await brain.addVerb(eventId, venueId, "scheduled", {
  date: "2025-06-15"
})

6. Hierarchical Representation

Supports all levels of abstraction:

// Micro level
await brain.addNoun("Electron", { type: "thing", scale: "quantum" })

// Macro level
await brain.addNoun("Solar System", { type: "place", scale: "astronomical" })

// Abstract level
await brain.addNoun("Justice", { type: "concept", domain: "philosophy" })

Extensibility

While the core types cover all knowledge, you can extend with domain-specific subtypes:

// Extend person for medical domain
await brain.addNoun("Patient #12345", {
  type: "person",
  subtype: "patient",
  medicalRecord: "MR-12345"
})

// Extend document for legal domain
await brain.addNoun("Contract ABC", {
  type: "document",
  subtype: "contract",
  jurisdiction: "California"
})

// Custom verb for specific domain
await brain.addVerb(lawyerId, contractId, "negotiates", {
  verbSubtype: "legal-action",
  billableHours: 10
})

Knowledge Completeness Proof

The noun-verb taxonomy achieves Turing completeness for knowledge representation:

1. Storage: Any data can be stored as nouns
2. Computation: Any transformation can be expressed as verbs
3. State: Metadata captures all properties
4. Relations: Graph structure captures all connections
5. Time: Temporal metadata handles all time aspects
6. Semantics: Embeddings capture meaning and similarity

This makes Brainy capable of representing:

• Scientific knowledge
• Business intelligence
• Social networks
• Historical records
• Creative content
• Technical documentation
• Personal information
• And any other form of human knowledge

Conclusion

The Noun-Verb taxonomy in Brainy 2.0 provides a natural, flexible, and powerful way to model any domain. By thinking in terms of entities and their relationships, you can build everything from simple data stores to complex knowledge graphs while maintaining code clarity and query simplicity.

See Also

• Triple Intelligence
• Natural Language Queries
• API Reference