langchain-ai
diff --git a/‎docs/docs/integrations/providers/timbr.mdx
Lines changed: 170 additions & 0 deletions b/‎docs/docs/integrations/providers/timbr.mdx
Lines changed: 170 additions & 0 deletions
@@ -0,0 +1,170 @@
+# Timbr
+
+[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 pre-built 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. This connector 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
+
+## Quickstart
+
+### Installation
+
+#### Install the package
+
+```bash
+pip install langchain-timbr
+```
+
+#### Optional: Install with selected LLM provider
+
+Choose one of: openai, anthropic, google, azure_openai, snowflake, databricks (or 'all')
+
+```bash
+pip install 'langchain-timbr[<your selected providers, separated by comma without spaces>]'
+```
+
+## 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
+# 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-4o"
+export LLM_TEMPERATURE="0.1"
+export LLM_ADDITIONAL_PARAMS='{"max_tokens": 1000}'
+```
+
+## Usage
+
+Import and utilize your intended chain/node, or use TimbrLlmConnector to manually integrate with Timbr's semantic layer. For a complete agent working example, see the [Timbr tool page](/docs/integrations/tools/timbr).
+
+### ExecuteTimbrQueryChain example
+
+```python
+from langchain_timbr import ExecuteTimbrQueryChain
+
+# 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-4o", 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-4o")
+
+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
+```
+
+### Multiple chains using SequentialChain example
+
+```python
+from langchain.chains import SequentialChain
+from langchain_timbr import ExecuteTimbrQueryChain, GenerateAnswerChain
+from langchain_openai import ChatOpenAI
+
+# 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-4o", 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-4o")
+
+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?"})
+```
+
+## 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)