langchain/docs/docs/integrations/tools/timbr.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "id": "2ce4bdbc",
   "metadata": {
    "vscode": {
     "languageId": "raw"
    }
   },
   "source": [
    "---\n",
    "sidebar_label: timbr\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6f91f20",
   "metadata": {},
   "source": [
    "# Timbr\n",
    "\n",
    "[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.\n",
    "\n",
    "This notebook provides a quick overview for getting started with Timbr tools and agents. For more information about Timbr visit [Timbr.ai](https://timbr.ai/) or the [Timbr Documentation](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/)\n",
    "\n",
    "## Overview\n",
    "\n",
    "### Integration details\n",
    "\n",
    "Timbr package for LangChain is [langchain-timbr](https://pypi.org/project/langchain-timbr), which provides seamless integration with Timbr's semantic layer for natural language to SQL conversion.\n",
    "\n",
    "### Tool features\n",
    "\n",
    "| Tool Name | Description |\n",
    "| :--- | :--- |\n",
    "| `IdentifyTimbrConceptChain` | Identify relevant concepts from user prompts |\n",
    "| `GenerateTimbrSqlChain` | Generate SQL queries from natural language prompts |\n",
    "| `ValidateTimbrSqlChain` | Validate SQL queries against Timbr knowledge graph schemas |\n",
    "| `ExecuteTimbrQueryChain` | Execute SQL queries against Timbr knowledge graph databases |\n",
    "| `GenerateAnswerChain` | Generate human-readable answers from query results |\n",
    "| `TimbrSqlAgent` | End-to-end SQL agent for natural language queries |\n",
    "\n",
    "### TimbrSqlAgent Parameters\n",
    "\n",
    "The `TimbrSqlAgent` is a pre-built agent that combines all the above tools for end-to-end natural language to SQL processing.\n",
    "\n",
    "For the complete list of parameters and detailed documentation, see: [TimbrSqlAgent Documentation](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/#timbr-sql-agent)\n",
    "\n",
    "| Parameter | Type | Required | Description |\n",
    "| :--- | :--- | :--- | :--- |\n",
    "| `llm` | BaseChatModel | Yes | Language model instance (ChatOpenAI, ChatAnthropic, etc.) |\n",
    "| `url` | str | Yes | Timbr application URL |\n",
    "| `token` | str | Yes | Timbr API token |\n",
    "| `ontology` | str | Yes | Knowledge graph ontology name |\n",
    "| `schema` | str | No | Database schema name |\n",
    "| `concept` | str | No | Specific concept to focus on |\n",
    "| `concepts_list` | List[str] | No | List of relevant concepts |\n",
    "| `views_list` | List[str] | No | List of available views |\n",
    "| `note` | str | No | Additional context or instructions |\n",
    "| `retries` | int | No | Number of retry attempts (default: 3) |\n",
    "| `should_validate_sql` | bool | No | Whether to validate generated SQL (default: True) |\n",
    "\n",
    "## Setup\n",
    "\n",
    "The integration lives in the `langchain-timbr` package.\n",
    "\n",
    "In this example, we'll use OpenAI for the LLM provider."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f85b4089",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install --quiet -U langchain-timbr[openai]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b15e9266",
   "metadata": {},
   "source": [
    "### Credentials\n",
    "\n",
    "You'll need Timbr credentials to use the tools. Get your API token from your Timbr application's API settings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0b178a2-8816-40ca-b57c-ccdd86dde9c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "import getpass\n",
    "import os\n",
    "\n",
    "# Set up Timbr credentials\n",
    "if not os.environ.get(\"TIMBR_URL\"):\n",
    "    os.environ[\"TIMBR_URL\"] = input(\"Timbr URL:\\n\")\n",
    "\n",
    "if not os.environ.get(\"TIMBR_TOKEN\"):\n",
    "    os.environ[\"TIMBR_TOKEN\"] = getpass.getpass(\"Timbr API Token:\\n\")\n",
    "\n",
    "if not os.environ.get(\"TIMBR_ONTOLOGY\"):\n",
    "    os.environ[\"TIMBR_ONTOLOGY\"] = input(\"Timbr Ontology:\\n\")\n",
    "\n",
    "if not os.environ.get(\"OPENAI_API_KEY\"):\n",
    "    os.environ[\"OPENAI_API_KEY\"] = getpass.getpass(\"OpenAI API Key:\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c97218f-f366-479d-8bf7-fe9f2f6df73f",
   "metadata": {},
   "source": [
    "## Instantiation\n",
    "\n",
    "Instantiate Timbr tools and agents. First, let's set up the LLM and basic Timbr chains:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8b3ddfe9-ca79-494c-a7ab-1f56d9407a64",
   "metadata": {},
   "outputs": [],
   "source": [
    "from langchain_timbr import (\n",
    "    ExecuteTimbrQueryChain,\n",
    "    GenerateAnswerChain,\n",
    "    TimbrSqlAgent,\n",
    "    LlmWrapper,\n",
    "    LlmTypes,\n",
    ")\n",
    "\n",
    "# Set up the LLM\n",
    "# from langchain_openai import ChatOpenAI\n",
    "# llm = ChatOpenAI(model=\"gpt-4o\", temperature=0)\n",
    "\n",
    "# Alternative: Use Timbr's LlmWrapper for an easy LLM setup\n",
    "llm = LlmWrapper(\n",
    "    llm_type=LlmTypes.OpenAI, api_key=os.environ[\"OPENAI_API_KEY\"], model=\"gpt-4o\"\n",
    ")\n",
    "\n",
    "# Instantiate Timbr chains\n",
    "execute_timbr_query_chain = ExecuteTimbrQueryChain(\n",
    "    llm=llm,\n",
    "    url=os.environ[\"TIMBR_URL\"],\n",
    "    token=os.environ[\"TIMBR_TOKEN\"],\n",
    "    ontology=os.environ[\"TIMBR_ONTOLOGY\"],\n",
    ")\n",
    "\n",
    "generate_answer_chain = GenerateAnswerChain(\n",
    "    llm=llm, url=os.environ[\"TIMBR_URL\"], token=os.environ[\"TIMBR_TOKEN\"]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "74147a1a",
   "metadata": {},
   "source": [
    "## Invocation\n",
    "\n",
    "### Execute SQL queries from natural language\n",
    "\n",
    "You can use the individual chains to perform specific operations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65310a8b-eb0c-4d9e-a618-4f4abe2414fc",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Execute a natural language query\n",
    "result = execute_timbr_query_chain.invoke(\n",
    "    {\"prompt\": \"What are the total sales for last month?\"}\n",
    ")\n",
    "\n",
    "print(\"SQL Query:\", result[\"sql\"])\n",
    "print(\"Results:\", result[\"rows\"])\n",
    "print(\"Concept:\", result[\"concept\"])\n",
    "\n",
    "# Generate a human-readable answer from the results\n",
    "answer_result = generate_answer_chain.invoke(\n",
    "    {\"prompt\": \"What are the total sales for last month?\", \"rows\": result[\"rows\"]}\n",
    ")\n",
    "\n",
    "print(\"Human-readable answer:\", answer_result[\"answer\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6e73897",
   "metadata": {},
   "source": [
    "## Use within an agent\n",
    "\n",
    "### Using TimbrSqlAgent\n",
    "\n",
    "The `TimbrSqlAgent` provides an end-to-end solution that combines concept identification, SQL generation, validation, execution, and answer generation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f90e33a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "from langchain.agents import AgentExecutor\n",
    "\n",
    "# Create a TimbrSqlAgent with all parameters\n",
    "timbr_agent = TimbrSqlAgent(\n",
    "    llm=llm,\n",
    "    url=os.environ[\"TIMBR_URL\"],\n",
    "    token=os.environ[\"TIMBR_TOKEN\"],\n",
    "    ontology=os.environ[\"TIMBR_ONTOLOGY\"],\n",
    "    concepts_list=[\"Sales\", \"Orders\"],  # optional\n",
    "    views_list=[\"sales_view\"],  # optional\n",
    "    note=\"Focus on monthly aggregations\",  # optional\n",
    "    retries=3,  # optional\n",
    "    should_validate_sql=True,  # optional\n",
    ")\n",
    "\n",
    "# Use the agent for end-to-end natural language to answer processing\n",
    "agent_result = AgentExecutor.from_agent_and_tools(\n",
    "    agent=timbr_agent,\n",
    "    tools=[],  # No tools needed as we're directly using the chain\n",
    "    verbose=True,\n",
    ").invoke(\"Show me the top 5 customers by total sales amount this year\")\n",
    "\n",
    "print(\"Final Answer:\", agent_result[\"answer\"])\n",
    "print(\"Generated SQL:\", agent_result[\"sql\"])\n",
    "print(\"Usage Metadata:\", agent_result.get(\"usage_metadata\", {}))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "659f9fbd-6fcf-445f-aa8c-72d8e60154bd",
   "metadata": {},
   "source": [
    "### Sequential Chains\n",
    "\n",
    "You can combine multiple Timbr chains using LangChain's SequentialChain for custom workflows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "af3123ad-7a02-40e5-b58e-7d56e23e5830",
   "metadata": {},
   "outputs": [],
   "source": [
    "from langchain.chains import SequentialChain\n",
    "\n",
    "# Create a sequential pipeline\n",
    "pipeline = SequentialChain(\n",
    "    chains=[execute_timbr_query_chain, generate_answer_chain],\n",
    "    input_variables=[\"prompt\"],\n",
    "    output_variables=[\"answer\", \"sql\", \"rows\"],\n",
    ")\n",
    "\n",
    "# Execute the pipeline\n",
    "pipeline_result = pipeline.invoke(\n",
    "    {\"prompt\": \"What are the average order values by customer segment?\"}\n",
    ")\n",
    "\n",
    "print(\"Pipeline Result:\", pipeline_result)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fdbf35b5-3aaf-4947-9ec6-48c21533fb95",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example: Accessing usage metadata from Timbr operations\n",
    "result_with_metadata = execute_timbr_query_chain.invoke(\n",
    "    {\"prompt\": \"How many orders were placed last quarter?\"}\n",
    ")\n",
    "\n",
    "# Extract usage metadata\n",
    "usage_metadata = result_with_metadata.get(\"execute_timbr_usage_metadata\", {})\n",
    "determine_concept_usage = usage_metadata.get(\"determine_concept\", {})\n",
    "generate_sql_usage = usage_metadata.get(\"generate_sql\", {})\n",
    "\n",
    "print(determine_concept_usage)\n",
    "\n",
    "print(\n",
    "    \"Concept determination token estimate:\",\n",
    "    determine_concept_usage.get(\"approximate\", \"N/A\"),\n",
    ")\n",
    "print(\n",
    "    \"Concept determination tokens:\",\n",
    "    determine_concept_usage.get(\"token_usage\", {}).get(\"total_tokens\", \"N/A\"),\n",
    ")\n",
    "\n",
    "print(\"SQL generation token estimate:\", generate_sql_usage.get(\"approximate\", \"N/A\"))\n",
    "print(\n",
    "    \"SQL generation tokens:\",\n",
    "    generate_sql_usage.get(\"token_usage\", {}).get(\"total_tokens\", \"N/A\"),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ac8146c",
   "metadata": {},
   "source": [
    "## API reference\n",
    "\n",
    "- [PyPI](https://pypi.org/project/langchain-timbr)\n",
    "- [GitHub](https://github.com/WPSemantix/langchain-timbr)\n",
    "- [LangChain Timbr Documentation](https://docs.timbr.ai/doc/docs/integration/langchain-sdk/)\n",
    "- [LangGraph Timbr Documentation](https://docs.timbr.ai/doc/docs/integration/langgraph-sdk)\n",
    "- [Timbr Official Website](https://timbr.ai/)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}