> ## Documentation Index > Fetch the complete documentation index at: https://docs.langchain.com/llms.txt > Use this file to discover all available pages before exploring further. # Timbr integration > Integrate with the Timbr graph using LangChain Python. > [Timbr](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/) integrates natural language inputs with Timbr's ontology-driven semantic layer. Leveraging Timbr's robust ontology capabilities, the SDK integrates with Timbr data models and leverages semantic relationships and annotations, enabling users to query data using business-friendly language. > Timbr provides a prebuilt SQL agent, `TimbrSqlAgent`, which can be used for end-to-end purposes from user prompt, through semantic SQL query generation and validation, to query execution and result analysis. > For customizations and partial usage, you can use LangChain chains and LangGraph nodes with our 5 main tools: > * `IdentifyTimbrConceptChain` & `IdentifyConceptNode` - Identify relevant concepts from user prompts > * `GenerateTimbrSqlChain` & `GenerateTimbrSqlNode` - Generate SQL queries from natural language prompts > * `ValidateTimbrSqlChain` & `ValidateSemanticSqlNode` - Validate SQL queries against Timbr knowledge graph schemas > * `ExecuteTimbrQueryChain` & `ExecuteSemanticQueryNode` - Execute (semantic and regular) SQL queries against Timbr knowledge graph databases > * `GenerateAnswerChain` & `GenerateResponseNode` - Generate human-readable answers based on a given prompt and data rows > Additionally, `langchain-timbr` provides `TimbrLlmConnector` for manual integration with Timbr's semantic layer using LLM providers. For a comprehensive example of the `langchain-timbr` integration, see the [demo notebook](https://github.com/WPSemantix/Timbr-GenAI/tree/main/LangChain/LangChain_Timbr_Demo.ipynb). ## Setting up ### Installation #### Install the package ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} pip install langchain-timbr ``` #### Optional: Install with selected LLM provider Choose one of: `openai, anthropic, google, azure_openai, snowflake, databricks, vertex_ai (or 'all')` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} pip install 'langchain-timbr[]' ``` We default to OpenAI models in this guide. ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import getpass import os if "OPENAI_API_KEY" not in os.environ: os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI API Key:") ``` ## Configuration Starting from `langchain-timbr` v2.0.0, all chains, agents, and nodes support optional environment-based configuration. You can set the following environment variables to provide default values and simplify setup for the provided tools: ### Timbr connection parameters * `TIMBR_URL`: Default Timbr server URL * `TIMBR_TOKEN`: Default Timbr authentication token * `TIMBR_ONTOLOGY`: Default ontology/knowledge graph name When these environment variables are set, the corresponding parameters (`url`, `token`, `ontology`) become optional in all chain and agent constructors and will use the environment values as defaults. ### LLM configuration parameters * **LLM\_TYPE**: The type of LLM provider (one of langchain\_timbr LlmTypes enum: 'openai-chat', 'anthropic-chat', 'chat-google-generative-ai', 'azure-openai-chat', 'snowflake-cortex', 'chat-databricks') * **LLM\_API\_KEY**: The API key for authenticating with the LLM provider * **LLM\_MODEL**: The model name or deployment to use * **LLM\_TEMPERATURE**: Temperature setting for the LLM * **LLM\_ADDITIONAL\_PARAMS**: Additional parameters as dict or JSON string When LLM environment variables are set, the `llm` parameter becomes optional and will use the `LlmWrapper` with environment configuration. Example environment setup: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # Timbr connection export TIMBR_URL="https://your-timbr-app.com/" export TIMBR_TOKEN="tk_XXXXXXXXXXXXXXXXXXXXXXXX" export TIMBR_ONTOLOGY="timbr_knowledge_graph" # LLM configuration export LLM_TYPE="openai-chat" export LLM_API_KEY="your-openai-api-key" export LLM_MODEL="gpt-5.5" export LLM_TEMPERATURE="0.1" export LLM_ADDITIONAL_PARAMS='{"max_tokens": 1000}' ``` ## Querying the semantic layer We can now use Timbr's chains to query the semantic layer. Import and utilize your intended chain/node, or use TimbrLlmConnector to manually integrate with Timbr's semantic layer. ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain_timbr import ExecuteTimbrQueryChain from langchain_openai import ChatOpenAI ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # You can use the standard LangChain ChatOpenAI/ChatAnthropic models # or any other LLM model based on langchain_core.language_models.chat.BaseChatModel llm = ChatOpenAI(model="gpt-5.5", temperature=0, openai_api_key="open-ai-api-key") # Optional alternative: Use Timbr's LlmWrapper, which provides generic connections to different LLM providers from langchain_timbr import LlmWrapper, LlmTypes llm = LlmWrapper(llm_type=LlmTypes.OpenAI, api_key="open-ai-api-key", model="gpt-5.5") ``` ### ExecuteTimbrQueryChain example ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} execute_timbr_query_chain = ExecuteTimbrQueryChain( llm=llm, url="https://your-timbr-app.com/", token="tk_XXXXXXXXXXXXXXXXXXXXXXXX", ontology="timbr_knowledge_graph", schema="dtimbr", # optional concept="Sales", # optional concepts_list=["Sales","Orders"], # optional views_list=["sales_view"], # optional note="We only need sums", # optional retries=3, # optional should_validate_sql=True # optional ) result = execute_timbr_query_chain.invoke({"prompt": "What are the total sales for last month?"}) rows = result["rows"] sql = result["sql"] concept = result["concept"] schema = result["schema"] error = result.get("error", None) usage_metadata = result.get("execute_timbr_usage_metadata", {}) determine_concept_usage = usage_metadata.get('determine_concept', {}) generate_sql_usage = usage_metadata.get('generate_sql', {}) # Each usage_metadata item contains: # * 'approximate': Estimated token count calculated before invoking the LLM # * 'input_tokens'/'output_tokens'/'total_tokens'/etc.: Actual token usage metrics returned by the LLM ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} {'rows': [{'total_sales': 150000}], 'sql': 'SELECT SUM(amount) as total_sales FROM sales WHERE date >= DATEADD(month, -1, GETDATE())', 'concept': 'Sales', 'schema': 'dtimbr'} ``` ### Using multiple chains with SequentialChain You can combine multiple Timbr chains to create more complex workflows. ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain_classic.chains import SequentialChain from langchain_timbr import ExecuteTimbrQueryChain, GenerateAnswerChain execute_timbr_query_chain = ExecuteTimbrQueryChain( llm=llm, url='https://your-timbr-app.com/', token='tk_XXXXXXXXXXXXXXXXXXXXXXXX', ontology='timbr_knowledge_graph', ) generate_answer_chain = GenerateAnswerChain( llm=llm, url='https://your-timbr-app.com/', token='tk_XXXXXXXXXXXXXXXXXXXXXXXX', ) pipeline = SequentialChain( chains=[execute_timbr_query_chain, generate_answer_chain], input_variables=["prompt"], output_variables=["answer", "sql"] ) result = pipeline.invoke({"prompt": "What are the total sales for last month?"}) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} {'prompt': 'What are the total sales for last month?', 'answer': 'Based on the query results, the total sales for last month amount to $150,000.', 'sql': 'SELECT SUM(amount) as total_sales FROM sales WHERE date >= DATEADD(month, -1, GETDATE())'} ``` ## Using the TimbrLlmConnector For manual integration with Timbr's semantic layer, you can use the `TimbrLlmConnector` which includes the following methods: * `get_ontologies` - List Timbr's semantic knowledge graphs * `get_concepts` - List selected knowledge graph ontology representation concepts * `get_views` - List selected knowledge graph ontology representation views * `determine_concept` - Identify relevant concepts from user prompts * `generate_sql` - Generate SQL queries from natural language prompts * `validate_sql` - Validate SQL queries against Timbr knowledge graph schemas * `run_timbr_query` - Execute (semantic and regular) SQL queries against Timbr knowledge graph databases * `run_llm_query` - Execute agent pipeline to determine concept, generate SQL, and run query from natural language prompt ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain_timbr import TimbrLlmConnector connector = TimbrLlmConnector( llm=llm, url="https://your-timbr-app.com/", token="tk_XXXXXXXXXXXXXXXXXXXXXXXX", ontology="timbr_knowledge_graph" ) # Get available concepts concepts = connector.get_concepts() print("Available concepts:", concepts) # Run a complete query pipeline result = connector.run_llm_query("What are the top 5 customers by revenue?") print("Query result:", result) ``` ## Additional resources * [PyPI](https://pypi.org/project/langchain-timbr) * [GitHub](https://github.com/WPSemantix/langchain-timbr) * [LangChain Timbr Docs](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/) * [LangGraph Timbr Docs](https://docs.timbr.ai/doc/docs/integration/langgraph-sdk) ***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/graphs/timbr.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).