Entity Extraction

Use TypeGraph extraction to turn documents, events, and thread turns into entities, facts, and provenance links.

Extract From Documents

Documents are chunked and embedded. When graphExtraction is enabled, the configured extractor receives the content and ontology and returns entities and facts linked back to document chunks.

document-extraction.ts

const result = await typegraph.document.ingest(
  [{
    id: 'kb:sso-runbook',
    name: 'SSO Runbook',
    description: 'Runbook for diagnosing enterprise SSO issues.',
    content: 'Acme reported SAML failures after rotating their IdP certificate...',
    metadata: { product: 'sso' },
  }],
  {
    bucketId: 'support',
    graphExtraction: true,
  },
)

Extract From Events

Events are time-anchored business occurrences. Event content, attached documents, and thread turns use the same internal document/chunk extraction path for consistent provenance.

event-extraction.ts

await typegraph.event.ingest(
  {
    id: 'support:incident:inc_123',
    name: 'Acme SSO incident',
    description: 'Acme reported SSO login failures after certificate rotation.',
    occurredAt: new Date('2026-05-08T12:00:00Z'),
    participants: [
      entityRef('organization', 'org_acme'),
      entityRef('system', 'sso'),
    ],
    content: 'Acme users cannot log in through SAML after IdP certificate rotation.',
    metadata: { provider: 'zendesk', ticketId: 'inc_123' },
  },
  { graphExtraction: true },
)

Constrain With Ontology

Ontology is supplied on deploy/init. TypeGraph ships presets, and you can provide a B2B/SaaS-specific ontology to constrain entity and relation types.

ontology.ts

const ontology = {
  version: '2026-05-08',
  entities: {
    organization: { description: 'A customer, vendor, partner, or internal company.' },
    contact: { description: 'A human contact at an organization.' },
    product: { description: 'A product, feature, or SKU.' },
    issue: { description: 'A customer problem, blocker, bug, or request.' },
  },
  relations: {
    EXPERIENCES: { from: ['organization'], to: ['issue'] },
    OWNS: { from: ['contact'], to: ['issue', 'product'] },
    BLOCKED_BY: { from: ['organization', 'issue'], to: ['issue', 'product'] },
  },
}

const typegraph = await typegraphInit({
  tenantId: TenantId('tenant_acme'),
  vectorStore,
  embedding,
  searchEmbedding: embedding,
  llm,
  ontology,
})

Bring Your Own Extractor

The public extractor interface is pass/fail: accept the expected input and return the expected entities, facts, warnings, and raw output. Single-pass or multi-pass pipeline details are private to your extractor.

custom-extractor.ts

const extractor = {
  name: 'ticket-extractor',
  capabilities: {
    supportsBatch: true,
    supportsStreaming: false,
    requiresStructuredOutput: false,
    multimodal: ['text'],
    preservesOntology: true,
  },
  async extract(input, ctx) {
    // Use your own deterministic, LLM, regex, or hybrid pipeline.
    return {
      entities: [
        {
          type: 'organization',
          id: 'org_acme',
          name: 'Acme Corp',
          description: 'Enterprise customer.',
          metadata: { source: input.episode.id },
        },
      ],
      facts: [
        {
          source: { type: 'organization', id: 'org_acme' },
          relation: 'EXPERIENCES',
          target: { type: 'issue', id: 'issue_sso_failure' },
          description: 'Acme is experiencing SSO login failures.',
          metadata: { confidence: 0.91 },
        },
      ],
      warnings: [],
    }
  },
}

Search Extracted Graph Evidence

Search extracted evidence by including graph-backed resources and giving the graph weight. Use explain to debug candidate counts, resource timings, graph traces, and skipped resources.

search-extracted-graph.ts

const response = await typegraph.search('Which customers are blocked by SSO?', {
  resources: ['events', 'documents', 'entities', 'facts'],
  weights: { semantic: 0.7, bm25: 0.4, graph: 1, recency: 0.6 },
  explain: true,
})

Back to All Guides

const result = await typegraph.document.ingest( [{ id: 'kb:sso-runbook', name: 'SSO Runbook', description: 'Runbook for diagnosing enterprise SSO issues.', content: 'Acme reported SAML failures after rotating their IdP certificate...', metadata: { product: 'sso' }, }], { bucketId: 'support', graphExtraction: true, }, )

await typegraph.event.ingest( { id: 'support:incident:inc_123', name: 'Acme SSO incident', description: 'Acme reported SSO login failures after certificate rotation.', occurredAt: new Date('2026-05-08T12:00:00Z'), participants: [ entityRef('organization', 'org_acme'), entityRef('system', 'sso'), ], content: 'Acme users cannot log in through SAML after IdP certificate rotation.', metadata: { provider: 'zendesk', ticketId: 'inc_123' }, }, { graphExtraction: true }, )

const ontology = { version: '2026-05-08', entities: { organization: { description: 'A customer, vendor, partner, or internal company.' }, contact: { description: 'A human contact at an organization.' }, product: { description: 'A product, feature, or SKU.' }, issue: { description: 'A customer problem, blocker, bug, or request.' }, }, relations: { EXPERIENCES: { from: ['organization'], to: ['issue'] }, OWNS: { from: ['contact'], to: ['issue', 'product'] }, BLOCKED_BY: { from: ['organization', 'issue'], to: ['issue', 'product'] }, }, } const typegraph = await typegraphInit({ tenantId: TenantId('tenant_acme'), vectorStore, embedding, searchEmbedding: embedding, llm, ontology, })

const extractor = { name: 'ticket-extractor', capabilities: { supportsBatch: true, supportsStreaming: false, requiresStructuredOutput: false, multimodal: ['text'], preservesOntology: true, }, async extract(input, ctx) { // Use your own deterministic, LLM, regex, or hybrid pipeline. return { entities: [ { type: 'organization', id: 'org_acme', name: 'Acme Corp', description: 'Enterprise customer.', metadata: { source: input.episode.id }, }, ], facts: [ { source: { type: 'organization', id: 'org_acme' }, relation: 'EXPERIENCES', target: { type: 'issue', id: 'issue_sso_failure' }, description: 'Acme is experiencing SSO login failures.', metadata: { confidence: 0.91 }, }, ], warnings: [], } }, }

const response = await typegraph.search('Which customers are blocked by SSO?', { resources: ['events', 'documents', 'entities', 'facts'], weights: { semantic: 0.7, bm25: 0.4, graph: 1, recency: 0.6 }, explain: true, })