Skip to main content

Knowledge Search

Knowledge Search lets DocuDevs cite trusted facts from an indexed case while it extracts data from an incoming document. Instead of relying solely on the uploaded file, the extraction prompt can call a retrieval tool that queries your curated knowledge base (cases synchronized to the DocuDevs search index). This is ideal whenever documents contain shorthand identifiers, catalog numbers, or sparse descriptions that must be cross-referenced.

Unlike standard document extraction—which only considers the uploaded content—Knowledge Search injects results from your case index directly into the prompt chain. The worker automatically keeps the organization context, so every search remains tenant-scoped.

When to use it​

Use Knowledge Search when:

  • Product catalogs or policy libraries evolve faster than your documents, and you need authoritative reference data during extraction.
  • You maintain a case per customer or brand and want cross-document consistency (e.g., canonical marketing names, compliance tags, localized variants).
  • You already curated a case that feeds the DocuDevs knowledge index via the indexing worker.

Stay with normal extraction when the uploaded file already contains every fact you need, or when you do not have a corresponding knowledge base.

How it works​

  • Step 1 — Prepare a case: Create a case and upload reference documents via the DocuDevs UI or CLI (docudevs cases create, docudevs cases upload-document). Promote it to a knowledge base with docudevs knowledge-base add <case_id>.
  • Step 2 — Discover the case ID: docudevs knowledge-base list (or the API GET /knowledge-bases) returns the IDs you can target. The Python SDK exposes the same CRUD surface as list_knowledge_bases, get_knowledge_base, promote_knowledge_base, and delete_knowledge_base on DocuDevsClient.
  • Step 3 — Attach a tool descriptor: Pass {"type":"KNOWLEDGE_BASE_SEARCH","config":{"caseId":"<id>","topK":5}} alongside your extraction request.
  • Step 4 — Process documents: The worker resolves the descriptor into a knowledge search tool wired to your case-specific index.
  • Step 5 — Review search hits: Download the job result or open the processing timeline in DocuDevs to confirm when the knowledge search tool ran and what context it injected.

Tip: topK defaults to 5. Increase it when the knowledge base stores short entries (SKUs, abbreviations) and you want broader recall.

Example scenario: Specialty catalog enrichment​

You maintain a "Signature Appliances" case (kb-kitchen-pro) that stores the canonical marketing copy, safety class, and localization guidance for every SKU. When suppliers send intake spreadsheets, you want DocuDevs to fill in the approved names and regulatory labels before the data hits your PIM. The following snippets show how to attach the Knowledge Search tool via REST, Python (with Pydantic models), and the DocuDevs CLI.

import asyncio
from pathlib import Path
from pydantic import BaseModel, Field

from docudevs import DocuDevsClient, json_schema

class CatalogRow(BaseModel):
    sku: str = Field(pattern=r"^SKU-\d{5}$")
    canonical_name: str = Field(max_length=80)
    localized_display_name: str = Field(max_length=40)
    regulatory_class: str
    marketing_summary: str | None = None

class CatalogResult(BaseModel):
    records: list[CatalogRow]

async def enrich_products():
    client = DocuDevsClient(token="YOUR_API_KEY")
    payload = Path("samples/products.csv").read_bytes()

    # Define the knowledge search tool as a simple dict
    tool = {
        "type": "KNOWLEDGE_BASE_SEARCH",
        "config": {
            "caseId": "kb-kitchen-pro",
            "topK": 8,
        }
    }

    job_id = await client.submit_and_process_document(
        document=payload,
        document_mime_type="text/csv",
        prompt=(
            "Fill canonical_name, localized_display_name (<=40 chars), regulatory_class, "
            "and marketing_summary using the Signature Appliances knowledge base."
        ),
        schema=json_schema(CatalogResult),
        tools=[tool],
    )

    raw = await client.wait_until_ready(job_id, result_format="json")
    result = CatalogResult(**raw)
    print(result.records[0])

asyncio.run(enrich_products())

The Pydantic models ensure downstream code only sees validated names and compliance metadata. If a record fails validation (e.g., localized name exceeds 40 characters) you can catch the exception and decide whether to re-run with different prompts.

Knowledge Base Evaluation​

For deeper analysis scenarios — such as compliance checking, document completeness audits, or cross-document reasoning — use the KNOWLEDGE_BASE_EVALUATE tool type. Unlike the lightweight search tool, evaluation gives the LLM access to full document summaries and content, with a strategy pre-phase that determines the optimal approach.

Configuration​

{
  "tools": [
    {
      "type": "KNOWLEDGE_BASE_EVALUATE",
      "config": {
        "caseId": "123",
        "strategy": "auto"
      }
    }
  ]
}

Available Strategies​

StrategyDescriptionBest for
autoLLM reviews document summaries and picks the best strategyGeneral use — recommended default
full_readBrowses summaries, then reads full document textSmall document sets, compliance audits
searchSemantic + vector search onlyLarge cases, specific fact retrieval
hybridAll tools available (browse, read, search)Complex multi-document reasoning

How Auto Strategy Works​

  1. The system first retrieves AI-generated summaries of all documents in the case
  2. A strategy-resolution LLM reviews the summaries and the extraction task
  3. Based on document count, types, and the task requirements, it selects full_read, search, or hybrid
  4. Only the selected tools are made available to the extraction LLM

Tools Provided to the LLM​

ToolStrategiesDescription
kb_browse_summariesfull_read, hybridLists AI-generated summaries for all case documents
kb_read_documentfull_read, hybridReads the full OCR text of a specific document by ID
kb_searchsearch, hybridSemantic + vector search across all case documents
When to use Evaluate vs Search

Use KNOWLEDGE_BASE_SEARCH when you need fast, targeted lookups (e.g., "find the price for item X"). Use KNOWLEDGE_BASE_EVALUATE when the LLM needs to reason across documents or discover what's missing (e.g., "verify all required compliance sections are present").

When the reference data is a records dataset (a catalogue, a chart of accounts, a vendor master) use the RECORDS_SEARCH tool type. The model looks up a value from the document among your records and gets back the most similar ones with their category labels, so a schema field such as the GL account of an invoice line or the catalogue product of an order line can be resolved while the document is extracted.

{
  "tools": [
    {
      "type": "RECORDS_SEARCH",
      "config": {
        "caseId": "51",
        "topK": 10,
        "subtree": "4.12",
        "attributes": {"brand": "Acme"}
      }
    }
  ]
}
Config keyMeaning
caseIdRequired. A records knowledge base of your organization.
topKHits per lookup, 1 to 50 (default 10). The model can ask for fewer, never more.
subtreeOptional category code; only records labelled in that subtree are returned.
attributesOptional {name: value} map of strings; only records with matching metadata are returned.

Unknown keys are rejected. The request fails with 400 when the case is not a records knowledge base, 404 when it is not found. Each hit contains the record key, the matched text (chunk), the label and its labelPath, and the score. Search uses the knowledge base's active embedding provider and its search settings, and fails instead of falling back when the provider cannot be resolved.

tool = {"type": "RECORDS_SEARCH", "config": {"caseId": "51", "topK": 5}}
job_id = await client.submit_and_process_document(
    document=payload,
    document_mime_type="application/pdf",
    prompt="For each invoice line, fill product_key with the catalogue record that matches the item.",
    schema=json_schema(InvoiceLines),
    tools=[tool],
)

To match many values in one run, use a classify job with the record target.

Records Match​

RECORDS_MATCH resolves one value to one record of a records knowledge base: the GL account of an invoice line, or the vendor a supplier name refers to. The model compares the value with the most similar records and returns the chosen record, or declined with a reason.

{"type": "RECORDS_MATCH", "config": {"caseId": "51", "topK": 10, "llmLevel": "MINI"}}
Config keyMeaning
caseIdRequired. A records knowledge base of your organization.
topKCandidate records the model compares, 1 to 50 (default 10).
llmLevelDEFAULT, NANO, MINI (default) or HIGH.

The result holds key, label, labelPath, declined and reason. Matching writes nothing: it creates no records, labels or memo entries. When the knowledge base has no active embedding generation the tool is not offered, and nothing falls back to another vector space. To match many values at once, use a classify job with the record target.

Operational notes​

  • Security: Every tool invocation is scoped to the authenticated organization and the supplied caseId. There is no cross-tenant leakage.
  • Fallback behavior: If the worker cannot resolve the tool (missing case ID, search credentials), the job still runs but skips retrieval.

Once your case index is healthy, Knowledge Search becomes a drop-in upgrade for high-precision extractions—no need to redesign prompts or templates. Attach the tool descriptor, deploy, and watch your enrichment accuracy climb.