TypeSafeTextRouter

Route a text to the output connection of the label a TypeSafe System One model picks for it.

Key Features

• Routes text with a System One decision model, such as Jev. The model answers a single choice question over your labels and returns calibrated probabilities.
• Creates one output connection per label.
• Optionally adds a low_confidence output. When you set min_confidence, texts whose answer confidence is below the threshold go to this output, so you can send uncertain texts to a fallback such as an LLM or a human. For details, see confidence-gated routing in the TypeSafe documentation.
• Works with any server that implements the TypeSafe API, such as Ollaya, which runs open decision models locally.

Configuration

1. Drag the TypeSafeTextRouter component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Set labels to the labels to route between. Each label becomes an output connection. Pass a mapping of label to description to tell the model what each label means.
   • Set instructions to the question the model answers by picking one of the labels.
   • Optionally, set min_confidence to a value between 0 and 1 to add the low_confidence output.
   • If you use a self-hosted TypeSafe-compatible server, set api_base_url to its URL.
4. On the Authentication tab, connect your TypeSafe API key. The component reads it from the TYPESAFE_API_KEY secret by default. For details, see Add Secrets.

Connections

TypeSafeTextRouter receives a text string and routes it to one of its named output connections. Each label gets its own output. If you set min_confidence, uncertain texts go to the low_confidence output. Connect each output to the retriever or processing component for that branch.

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
      model: jev-latest
      instructions: Which team should handle this support request?
      labels:
        billing: Payments, invoices, refunds and charges
        technical: Bugs, crashes and errors in the product
      min_confidence: 0.6

Using the Component in a Pipeline

This pipeline routes the query to a billing or technical index. Queries the model isn't confident about go to a general index:

# haystack-pipeline
components:
  TypeSafeTextRouter:
    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
      instructions: Which team should handle this support request?
      labels:
        billing: Payments, invoices, refunds and charges
        technical: Bugs, crashes and errors in the product
      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-index

  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-index

  general_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: general-index

connections:
- sender: TypeSafeTextRouter.billing
  receiver: billing_retriever.query
- sender: TypeSafeTextRouter.technical
  receiver: technical_retriever.query
- sender: TypeSafeTextRouter.low_confidence
  receiver: general_retriever.query

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - TypeSafeTextRouter.text

Parameters

Inputs

Parameter	Type	Description
text	str	The text to route.

Outputs

The outputs are dynamic and depend on the labels configured at initialization. There is one output per label, plus a low_confidence output if min_confidence is set.

Parameter	Type	Description
<label>	str	The input text, routed to the connection of the label the model picked.
low_confidence	str	The input text, if min_confidence is set and the answer's confidence is below it.

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 becoming an output connection. Pass a mapping of label to description to tell the model what each label means. low_confidence is reserved and can't be used as a label.
instructions	str	Which category does this text belong to?	The question the model answers by picking one of the labels.
model	str	jev-latest	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 non-empty value unless they are configured with a key.
api_base_url	Optional[str]	None	Base URL of the API. If None, the TYPESAFE_BASE_URL environment variable is used, or https://api.typesafe.ai if it is unset.
min_confidence	Optional[float]	None	Threshold between 0 and 1 for the answer's confidence. Texts below it are sent to the low_confidence output. If None, every text goes to a label output.
timeout	Optional[float]	None	Timeout in seconds for each request attempt. If None, the SDK default of 10 seconds is used.
max_retries	Optional[int]	None	Maximum number of retries after a failed request attempt. If None, the SDK default of two is used.

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
• TextLanguageRouter
• Pipeline Components