langchain-timbr 5.2.1

LangChain & LangGraph extensions that parse LLM prompts into Timbr semantic SQL and execute them.

Timbr LangChain LLM SDK

Timbr LangChain LLM SDK is a Python SDK that extends LangChain and LangGraph with custom agents, chains, and nodes for seamless integration with the Timbr semantic layer. It enables converting natural language prompts into optimized semantic-SQL queries and executing them directly against your data.

Dependencies

• Access to a timbr-server
• Python 3.10 or newer

Installation

Using pip

python -m pip install langchain-timbr

Install with selected LLM providers

One of: openai, anthropic, google, azure_openai, snowflake, databricks, vertex_ai, bedrock (or 'all')

python -m pip install 'langchain-timbr[<your selected providers, separated by comma w/o space>]'

Using pip from github

pip install git+https://github.com/WPSemantix/langchain-timbr

Documentation

For comprehensive documentation and usage examples, please visit:

• Timbr LangChain Documentation
• Timbr LangGraph Documentation

Configuration

The SDK uses environment variables for configuration. All configurations are optional - when set, they serve as default values for langchain-timbr provided tools. Below are all available configuration options:

Configuration Options

Timbr Connection Settings

• TIMBR_URL - The URL of your Timbr server
• TIMBR_TOKEN - Authentication token for accessing the Timbr server
• TIMBR_ONTOLOGY - The ontology to use (also accepts ONTOLOGY as an alias)
• IS_JWT - Whether the token is a JWT token (true/false)
• JWT_TENANT_ID - Tenant ID for JWT authentication

Cache and Data Processing

• CACHE_TIMEOUT - Timeout for caching operations in seconds
• IGNORE_TAGS - Comma-separated list of tags to ignore during processing
• IGNORE_TAGS_PREFIX - Comma-separated list of tag prefixes to ignore during processing

LLM Configuration

• LLM_TYPE - The type of LLM provider to use
• LLM_MODEL - The specific model to use with the LLM provider
• LLM_API_KEY - API key or client secret for the LLM provider
• LLM_TEMPERATURE - Temperature setting for LLM responses (controls randomness)
• LLM_ADDITIONAL_PARAMS - Additional parameters to pass to the LLM
• LLM_TIMEOUT - Timeout for LLM requests in seconds
• LLM_TENANT_ID - LLM provider tenant/directory ID (Used for Service Principal authentication)
• LLM_CLIENT_ID - LLM provider client ID (Used for Service Principal authentication)
• LLM_CLIENT_SECRET - LLM provider client secret (Used for Service Principal authentication)
• LLM_ENDPOINT - LLM provider OpenAI endpoint URL
• LLM_API_VERSION - LLM provider API version
• LLM_SCOPE - LLM provider authentication scope

Monitoring & History

• TIMBR_ENABLE_TRACE - Enable detailed trace logging for agent/chain execution (true/false, default: false)
• TIMBR_ENABLE_HISTORY - Enable query history tracking (true/false, default: false)
• TIMBR_HISTORY_SAVE_RESULTS - Whether to save query result rows in history (true/false, default: false)

Monitoring & Tracing

The SDK supports optional execution tracing and query history recording. These can be enabled via environment variables (see above) or set directly on TimbrSqlAgent:

from langchain_timbr import TimbrSqlAgent

agent = TimbrSqlAgent(
    llm=llm,
    url="https://your-timbr-server",
    token="your-token",
    ontology="your_ontology",
    enable_trace=True,        # Enable chain-level trace logging
    enable_history=True,      # Enable query history storage
    save_results=True,        # Save result rows in history
    conversation_id="conv-123",  # Group calls into a multi-turn conversation
)

Parameter	Type	Default	Description
enable_trace	Optional[bool]	TIMBR_ENABLE_TRACE	Enable detailed trace logging per chain step
enable_history	Optional[bool]	TIMBR_ENABLE_HISTORY	Store query execution history
save_results	Optional[bool]	TIMBR_HISTORY_SAVE_RESULTS	Include result rows in history entries
conversation_id	Optional[str]	None	Associate multiple agent calls under one conversation

Benchmarking

The SDK includes a benchmarking utility to evaluate LLM query accuracy against a named benchmark defined in your Timbr server.

from langchain_timbr.utils.benchmark import run_benchmark

results = run_benchmark(
    benchmark_name="my_benchmark",
    url="https://your-timbr-server",
    token="your-token",
    ontology="your_ontology",
    execution="full",             # "full" or "generate_sql_only"
    number_of_iterations=1,
    use_deterministic=True,       # Row-comparison scoring
    use_llm_judge=False,          # LLM-as-judge scoring
    llm_params={                  # Optional: override LLM at runtime
        "llm_type": "openai",
        "llm_model": "gpt-4o",
        "api_key": "sk-...",
    },
)

The llm_params dict accepts: llm_type, llm_model / model, llm_api_key / api_key. Temperature and timeout are managed automatically.

Results are returned as a dict keyed by question ID, with a "_summary" key containing aggregate statistics. Each result includes a selected_entity field identifying which ontology entity was used.

Conversation Memory

• TIMBR_ENABLE_MEMORY - Enable conversation memory for follow-up question detection (true/false, default: false)
• TIMBR_MEMORY_WINDOW_SIZE - Number of past conversation turns to consider when detecting follow-ups (default: 3)