TypeSafeDocumentClassifier

Answer typed questions about each document with a TypeSafe System One model and store the answers in the document's metadata.

Key Features

• Uses TypeSafe System One decision models, such as Jev. These models don't generate text. They answer all questions about a document in one request and return calibrated probabilities.
• Supports three question types:
  • choice: Picks one label from a set of labels.
  • score: Rates the text on a scale of ordered levels.
  • noul: Returns the probability that a yes or no question is true.
• Stores the answers in the document's metadata, keyed by question ID, so you can filter or route documents by them later.
• Classifies the document's content or the value of one of its metadata fields.
• Returns documents that have no text or whose request failed in a separate output, with the reason in their metadata.
• Sends requests for several documents at the same time.
• Works with servers that implement the TypeSafe API, such as Ollaya, which runs open decision models on your own infrastructure.

Configuration

1. Drag the TypeSafeDocumentClassifier component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. Create a secret with your TypeSafe API key and set it as api_key. Use TYPESAFE_API_KEY as the environment variable name. For instructions, see Create Secrets.
4. Set questions to the questions you want the model to answer for each document. Each question needs an ID, a type, and instructions. Questions of type choice and score also need criteria:
   • For choice, criteria maps each label to a description of the label. To leave a label without a description, set it to null.
   • For score, criteria is a list of level descriptions, ordered from lowest to highest.
5. Optionally, set classification_field to classify a metadata field instead of the document's content, and metadata_field to change the field the answers are written to. The default is typesafe.
6. To use a self-hosted server, such as Ollaya, set api_base_url to the server's URL and model to one of its models.

Connections

TypeSafeDocumentClassifier receives a list of documents, for example from a converter or a preprocessor in an indexing pipeline. It sends the classified documents through its documents output. Connect this output to a DocumentWriter or to a router, such as MetadataRouter, that sends documents to different branches based on their metadata.

Documents that have no text to classify, or whose request failed, go to the failed_documents output. The reason is in each document's classification_error metadata field. If you set raise_on_failure to true, a failed request stops the pipeline with an error instead.

Answer Format

The answers are stored under meta.<metadata_field>, keyed by question ID. Each answer contains the question type and these fields:

Question type	Fields
choice	choice: The label the model picked. confidence: How confident the model is in its answer. probabilities: The probability of each label.
score	score: The score on the scale, where 0 is the lowest level. confidence: How confident the model is in its answer. legend: The description of each level, keyed by its position on the scale. probabilities: The probability of each level.
noul	noul: The probability that the answer to the question is yes.

For example, this is how the answers to three questions about a support ticket look:

{
  "department": {
    "type": "choice",
    "choice": "billing",
    "confidence": 0.9516,
    "probabilities": {"billing": 0.9677, "technical": 0.0221, "sales": 0.0102}
  },
  "urgency": {
    "type": "score",
    "score": 1.948,
    "confidence": 0.9389,
    "legend": {"0": "can wait", "1": "this week", "2": "today"},
    "probabilities": {"0": 0.0113, "1": 0.0295, "2": 0.9593}
  },
  "refund": {"type": "noul", "noul": 0.9498}
}

For the full question and answer format, see the TypeSafe documentation.

Source Code

To check this component's source code, open document_classifier.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  TypeSafeDocumentClassifier:
    type: haystack_integrations.components.classifiers.typesafe.document_classifier.TypeSafeDocumentClassifier
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - TYPESAFE_API_KEY
        strict: false
      model: jev-latest
      questions:
        department:
          type: choice
          instructions: Which department should handle this ticket?
          criteria:
            billing:
            technical:
            sales:
        urgency:
          type: score
          instructions: How urgent is this ticket?
          criteria:
          - can wait
          - this week
          - today
        refund:
          type: noul
          instructions: Is the customer asking for a refund?

Using the Component in an Index

This index classifies each document and writes the answers to its metadata, so you can filter on them at query time:

# haystack-pipeline
components:
  TypeSafeDocumentClassifier:
    type: haystack_integrations.components.classifiers.typesafe.document_classifier.TypeSafeDocumentClassifier
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - TYPESAFE_API_KEY
        strict: false
      model: jev-latest
      metadata_field: typesafe
      max_workers: 3
      raise_on_failure: false
      questions:
        department:
          type: choice
          instructions: Which department should handle this ticket?
          criteria:
            billing:
            technical:
            sales:
        refund:
          type: noul
          instructions: Is the customer asking for a refund?

  writer:
    type: haystack.components.writers.document_writer.DocumentWriter
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: ''
          embedding_dim: 768
          create_index: true
      policy: OVERWRITE

connections:
- sender: TypeSafeDocumentClassifier.documents
  receiver: writer.documents

max_runs_per_component: 100

metadata: {}

inputs:
  documents:
  - TypeSafeDocumentClassifier.documents

Parameters

Inputs

Parameter	Type	Description
documents	List[Document]	The documents to classify.

Outputs

Parameter	Type	Description
documents	List[Document]	The classified documents. Each document has the answers in its meta.<metadata_field> field, keyed by question ID.
failed_documents	List[Document]	The documents that have no text to classify or whose request failed. The reason is in each document's classification_error metadata field.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
questions	Dict[str, Question]		The questions to answer for each document, keyed by question ID. Each question has a type (choice, score, or noul), instructions, and, for choice and score questions, criteria.
model	str	jev-latest	The name of the System One model to use.
api_key	Secret	Secret.from_env_var("TYPESAFE_API_KEY")	The TypeSafe API key. Servers such as Ollaya accept any value that isn't empty, unless they're configured with a key.
api_base_url	Optional[str]	None	The base URL of the API. If not set, the component uses the TYPESAFE_BASE_URL environment variable or, if that's not set, https://api.typesafe.ai.
classification_field	Optional[str]	None	The name of the metadata field to classify. If not set, the component classifies the document's content.
metadata_field	str	typesafe	The name of the metadata field the answers are written to.
timeout	Optional[float]	None	The timeout in seconds for each request attempt. If not set, the timeout is 10 seconds.
max_retries	Optional[int]	None	The maximum number of retries after a failed request attempt. If not set, the component retries twice.
max_workers	int	3	The maximum number of requests sent at the same time. Must be at least 1.
raise_on_failure	bool	False	If True, the first failed request stops the pipeline with an error. If False, documents whose request failed go to the failed_documents output.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
documents	List[Document]		The documents to classify.

Related Information

• TypeSafeTextRouter
• Create Secrets
• Pipeline Components
• Integrations Overview