TypeSafeTextRouter

Route text to different pipeline branches based on the label a TypeSafe System One model picks for it.

Key Features

• Uses TypeSafe System One decision models, such as Jev. The model picks one of the labels you define and returns how confident it is in its choice.
• Creates one output for each label, so you can connect each label to a different branch of your pipeline.
• Optionally sends text the model isn't confident about to a separate low_confidence output. You can connect this output to a fallback, such as an LLM. For details, see confidence-gated routing in the TypeSafe documentation.
• Works with servers that implement the TypeSafe API, such as Ollaya, which runs open decision models on your own infrastructure.

Configuration

1. Drag the TypeSafeTextRouter 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 labels to the labels you want to route between. Each label becomes an output of the component. To tell the model what each label means, map each label to a description. You can't use low_confidence as a label.
5. Set instructions to the question the model answers by picking a label, for example, Which team should handle this support request?.
6. Optionally, set min_confidence to a value between 0 and 1. Text with a confidence below this value goes to the low_confidence output.
7. 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

TypeSafeTextRouter receives a single string, usually the query. It sends the string unchanged through the output of the label the model picks. Connect each label output to the component that handles that kind of text, such as a retriever or a prompt builder.

If you set min_confidence, the component also has a low_confidence output. Connect it to a fallback branch, for example, a branch that uses an LLM to handle the query.

Source Code

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

Usage Examples

Basic Configuration

  TypeSafeTextRouter:
    type: haystack_integrations.components.routers.typesafe.text_router.TypeSafeTextRouter
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - TYPESAFE_API_KEY
        strict: false
      labels:
        billing: Payments, invoices, refunds, and charges
        technical: Bugs, crashes, and errors in the product
      instructions: Which team should handle this support request?
      min_confidence: 0.6

Using the Component in a Pipeline

This pipeline sends each support question to a retriever that searches the matching team's documentation. Questions the model isn't confident about go to the low_confidence output, which isn't connected, so the pipeline returns them as they are:

# haystack-pipeline
components:
  router:
    type: haystack_integrations.components.routers.typesafe.text_router.TypeSafeTextRouter
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - TYPESAFE_API_KEY
        strict: false
      model: jev-latest
      labels:
        billing: Payments, invoices, refunds, and charges
        technical: Bugs, crashes, and errors in the product
      instructions: Which team should handle this support request?
      min_confidence: 0.6

  billing_retriever:
    type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
    init_parameters:
      top_k: 10
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: billing-docs

  technical_retriever:
    type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
    init_parameters:
      top_k: 10
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: technical-docs

connections:
- sender: router.billing
  receiver: billing_retriever.query
- sender: router.technical
  receiver: technical_retriever.query

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - router.text

Parameters

Inputs

Parameter	Type	Description
text	str	The text to route.

Outputs

The component has one output for each label in labels, plus a low_confidence output if you set min_confidence. For each run, only one output receives the text.

Parameter	Type	Description
<label>	str	The input text, if the model picked this label.
low_confidence	str	The input text, if the model's confidence is below min_confidence. Available only if you set min_confidence.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
labels	Union[List[str], Dict[str, Optional[str]]]		The labels to route between. Each label becomes an output. Pass a dictionary that maps each label to a description to tell the model what each label means.
instructions	str	Which category does this text belong to?	The question the model answers by picking one of the labels.
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.
min_confidence	Optional[float]	None	A threshold between 0 and 1 for the model's confidence. Text with a lower confidence goes to the low_confidence output. If not set, all text goes to a label output.
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.

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
text	str		The text to route.

Related Information

• TypeSafeDocumentClassifier
• Create Secrets
• Pipeline Components
• Integrations Overview