langchain-timbr 2.1.6__tar.gz → 2.1.7__tar.gz

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-timbr
-Version: 2.1.6
+Version: 2.1.7
 Summary: LangChain & LangGraph extensions that parse LLM prompts into Timbr semantic SQL and execute them.
 Project-URL: Homepage, https://github.com/WPSemantix/langchain-timbr
 Project-URL: Documentation, https://docs.timbr.ai/doc/docs/integration/langchain-sdk/

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/__init__.py

@@ -12,7 +12,7 @@
 from .timbr_llm_connector import TimbrLlmConnector
 from .llm_wrapper.llm_wrapper import LlmWrapper, LlmTypes
 
-from .utils.timbr_llm_utils import (
+from .utils.timbr_utils import (
     generate_key,
     encrypt_prompt,
     decrypt_prompt,

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '2.1.6'
-__version_tuple__ = version_tuple = (2, 1, 6)
+__version__ = version = '2.1.7'
+__version_tuple__ = version_tuple = (2, 1, 7)
 
 __commit_id__ = commit_id = None

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/config.py

@@ -30,5 +30,5 @@ llm_api_version = os.environ.get('LLM_API_VERSION', None)
 llm_scope = os.environ.get('LLM_SCOPE', "https://cognitiveservices.azure.com/.default")  # e.g. "api://<your-client-id>/.default"
 
 # Whether to enable reasoning during SQL generation
-with_reasoning = to_boolean(os.environ.get('WITH_REASONING', 'false'))
+enable_reasoning = to_boolean(os.environ.get('ENABLE_REASONING', 'false'))
 reasoning_steps = to_integer(os.environ.get('REASONING_STEPS', 2))

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langchain/execute_timbr_query_chain.py

@@ -42,7 +42,7 @@ class ExecuteTimbrQueryChain(Chain):
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
-        with_reasoning: Optional[bool] = config.with_reasoning,
+        enable_reasoning: Optional[bool] = config.enable_reasoning,
         reasoning_steps: Optional[int] = config.reasoning_steps,
         debug: Optional[bool] = False,
         **kwargs,
@@ -71,7 +71,7 @@ class ExecuteTimbrQueryChain(Chain):
         :param is_jwt: Whether to use JWT authentication (default is False).
         :param jwt_tenant_id: JWT tenant ID for multi-tenant environments (required when is_jwt=True).
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
-        :param with_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
         :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
         :param kwargs: Additional arguments to pass to the base
         :return: A list of rows from the Timbr query
@@ -141,7 +141,7 @@ class ExecuteTimbrQueryChain(Chain):
         self._jwt_tenant_id = jwt_tenant_id
         self._debug = to_boolean(debug)
         self._conn_params = conn_params or {}
-        self._with_reasoning = to_boolean(with_reasoning)
+        self._enable_reasoning = to_boolean(enable_reasoning)
         self._reasoning_steps = to_integer(reasoning_steps)
 
 
@@ -215,7 +215,7 @@ class ExecuteTimbrQueryChain(Chain):
             note=(self._note or '') + err_txt,
             db_is_case_sensitive=self._db_is_case_sensitive,
             graph_depth=self._graph_depth,
-            with_reasoning=self._with_reasoning,
+            enable_reasoning=self._enable_reasoning,
             reasoning_steps=self._reasoning_steps,
             debug=self._debug,
         )

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langchain/generate_timbr_sql_chain.py

@@ -39,7 +39,7 @@ class GenerateTimbrSqlChain(Chain):
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
-        with_reasoning: Optional[bool] = config.with_reasoning,
+        enable_reasoning: Optional[bool] = config.enable_reasoning,
         reasoning_steps: Optional[int] = config.reasoning_steps,
         debug: Optional[bool] = False,
         **kwargs,
@@ -66,7 +66,7 @@ class GenerateTimbrSqlChain(Chain):
         :param is_jwt: Whether to use JWT authentication (default is False).
         :param jwt_tenant_id: JWT tenant ID for multi-tenant environments (required when is_jwt=True).
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
-        :param with_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
         :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
         :param debug: Whether to enable debug mode for detailed logging
         :param kwargs: Additional arguments to pass to the base
@@ -134,7 +134,7 @@ class GenerateTimbrSqlChain(Chain):
         self._jwt_tenant_id = jwt_tenant_id
         self._debug = to_boolean(debug)
         self._conn_params = conn_params or {}
-        self._with_reasoning = to_boolean(with_reasoning)
+        self._enable_reasoning = to_boolean(enable_reasoning)
         self._reasoning_steps = to_integer(reasoning_steps)
 
 
@@ -191,7 +191,7 @@ class GenerateTimbrSqlChain(Chain):
             note=self._note,
             db_is_case_sensitive=self._db_is_case_sensitive,
             graph_depth=self._graph_depth,
-            with_reasoning=self._with_reasoning,
+            enable_reasoning=self._enable_reasoning,
             reasoning_steps=self._reasoning_steps,
             debug=self._debug,
         )

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langchain/timbr_sql_agent.py

@@ -35,7 +35,7 @@ class TimbrSqlAgent(BaseSingleActionAgent):
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
-        with_reasoning: Optional[bool] = config.with_reasoning,
+        enable_reasoning: Optional[bool] = config.enable_reasoning,
         reasoning_steps: Optional[int] = config.reasoning_steps,
         debug: Optional[bool] = False
     ):
@@ -64,7 +64,7 @@ class TimbrSqlAgent(BaseSingleActionAgent):
         :param is_jwt: Whether to use JWT authentication (default is False).
         :param jwt_tenant_id: JWT tenant ID for multi-tenant environments (required when is_jwt=True).
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
-        :param with_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
         :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
 
         ## Example
@@ -118,7 +118,7 @@ class TimbrSqlAgent(BaseSingleActionAgent):
             is_jwt=to_boolean(is_jwt),
             jwt_tenant_id=jwt_tenant_id,
             conn_params=conn_params,
-            with_reasoning=to_boolean(with_reasoning),
+            enable_reasoning=to_boolean(enable_reasoning),
             reasoning_steps=to_integer(reasoning_steps),
             debug=to_boolean(debug),
         )
@@ -345,7 +345,7 @@ def create_timbr_sql_agent(
     is_jwt: Optional[bool] = False,
     jwt_tenant_id: Optional[str] = None,
     conn_params: Optional[dict] = None,
-    with_reasoning: Optional[bool] = config.with_reasoning,
+    enable_reasoning: Optional[bool] = config.enable_reasoning,
     reasoning_steps: Optional[int] = config.reasoning_steps,
     debug: Optional[bool] = False
 ) -> AgentExecutor:
@@ -376,7 +376,7 @@ def create_timbr_sql_agent(
     :param is_jwt: Whether to use JWT authentication (default is False).
     :param jwt_tenant_id: JWT tenant ID for multi-tenant environments (required when is_jwt=True).
     :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
-    :param with_reasoning: Whether to enable reasoning during SQL generation (default is False).
+    :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
     :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
 
     Returns:
@@ -444,7 +444,7 @@ def create_timbr_sql_agent(
         is_jwt=is_jwt,
         jwt_tenant_id=jwt_tenant_id,
         conn_params=conn_params,
-        with_reasoning=with_reasoning,
+        enable_reasoning=enable_reasoning,
         reasoning_steps=reasoning_steps,
         debug=debug,
     )

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langchain/validate_timbr_sql_chain.py

@@ -40,6 +40,8 @@ class ValidateTimbrSqlChain(Chain):
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
+        enable_reasoning: Optional[bool] = config.enable_reasoning,
+        reasoning_steps: Optional[int] = config.reasoning_steps,
         debug: Optional[bool] = False,
         **kwargs,
     ):
@@ -64,6 +66,8 @@ class ValidateTimbrSqlChain(Chain):
         :param is_jwt: Whether to use JWT authentication (default is False).
         :param jwt_tenant_id: JWT tenant ID for multi-tenant environments (required when is_jwt=True).
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
         :param kwargs: Additional arguments to pass to the base
         
         ## Example
@@ -127,8 +131,10 @@ class ValidateTimbrSqlChain(Chain):
         self._verify_ssl = to_boolean(verify_ssl)
         self._is_jwt = to_boolean(is_jwt)
         self._jwt_tenant_id = jwt_tenant_id
-        self._debug = to_boolean(debug)
         self._conn_params = conn_params or {}
+        self._enable_reasoning = to_boolean(enable_reasoning)
+        self._reasoning_steps = to_integer(reasoning_steps)
+        self._debug = to_boolean(debug)
 
 
     @property
@@ -193,6 +199,8 @@ class ValidateTimbrSqlChain(Chain):
                 note=f"{prompt_extension}The original SQL query (`{sql}`) was invalid with this error from query {error}. Please take this in consideration while generating the query.",
                 db_is_case_sensitive=self._db_is_case_sensitive,
                 graph_depth=self._graph_depth,
+                enable_reasoning=self._enable_reasoning,
+                reasoning_steps=self._reasoning_steps,
                 debug=self._debug,
             )
             sql = generate_res.get("sql", "")
@@ -200,6 +208,7 @@ class ValidateTimbrSqlChain(Chain):
             concept = generate_res.get("concept", self._concept)
             usage_metadata.update(generate_res.get("usage_metadata", {}))
             is_sql_valid = generate_res.get("is_sql_valid")
+            reasoning_status = generate_res.get("reasoning_status")
             error = generate_res.get("error")
 
         return {
@@ -208,5 +217,6 @@ class ValidateTimbrSqlChain(Chain):
             "concept": concept,
             "is_sql_valid": is_sql_valid,
             "error": error,
+            "reasoning_status": reasoning_status,
             self.usage_metadata_key: usage_metadata,
         }

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langgraph/execute_timbr_query_node.py

@@ -36,7 +36,7 @@ class ExecuteSemanticQueryNode:
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
-        with_reasoning: Optional[bool] = config.with_reasoning,
+        enable_reasoning: Optional[bool] = config.enable_reasoning,
         reasoning_steps: Optional[int] = config.reasoning_steps,
         debug: Optional[bool] = False,
         **kwargs,
@@ -65,7 +65,7 @@ class ExecuteSemanticQueryNode:
         :param is_jwt: Whether to use JWT authentication (default is False).
         :param jwt_tenant_id: JWT tenant ID for multi-tenant environments (required when is_jwt=True).
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
-        :param with_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
         :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
         :return: A list of rows from the Timbr query
         """
@@ -93,7 +93,7 @@ class ExecuteSemanticQueryNode:
             is_jwt=is_jwt,
             jwt_tenant_id=jwt_tenant_id,
             conn_params=conn_params,
-            with_reasoning=with_reasoning,
+            enable_reasoning=enable_reasoning,
             reasoning_steps=reasoning_steps,
             debug=debug,
             **kwargs,

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langgraph/generate_timbr_sql_node.py

@@ -33,7 +33,7 @@ class GenerateTimbrSqlNode:
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
-        with_reasoning: Optional[bool] = config.with_reasoning,
+        enable_reasoning: Optional[bool] = config.enable_reasoning,
         reasoning_steps: Optional[int] = config.reasoning_steps,
         debug: Optional[bool] = False,
         **kwargs,
@@ -60,7 +60,7 @@ class GenerateTimbrSqlNode:
         :param is_jwt: Whether to use JWT authentication (default: False)
         :param jwt_tenant_id: Tenant ID for JWT authentication when using multi-tenant setup
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
-        :param with_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
         :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
         """
         self.chain = GenerateTimbrSqlChain(
@@ -85,7 +85,7 @@ class GenerateTimbrSqlNode:
             is_jwt=is_jwt,
             jwt_tenant_id=jwt_tenant_id,
             conn_params=conn_params,
-            with_reasoning=with_reasoning,
+            enable_reasoning=enable_reasoning,
             reasoning_steps=reasoning_steps,
             debug=debug,
             **kwargs,

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/langgraph/validate_timbr_query_node.py

@@ -33,6 +33,8 @@ class ValidateSemanticSqlNode:
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
+        enable_reasoning: Optional[bool] = False,
+        reasoning_steps: Optional[int] = 2,
         debug: Optional[bool] = False,
         **kwargs,
     ):
@@ -57,6 +59,8 @@ class ValidateSemanticSqlNode:
         :param is_jwt: Whether to use JWT authentication (default: False)
         :param jwt_tenant_id: Tenant ID for JWT authentication when using multi-tenant setup
         :param conn_params: Extra Timbr connection parameters sent with every request (e.g., 'x-api-impersonate-user').
+        :param enable_reasoning: Whether to enable reasoning during SQL generation (default is False).
+        :param reasoning_steps: Number of reasoning steps to perform if reasoning is enabled (default is 2).
         """
         self.chain = ValidateTimbrSqlChain(
             llm=llm,
@@ -79,6 +83,8 @@ class ValidateSemanticSqlNode:
             is_jwt=is_jwt,
             jwt_tenant_id=jwt_tenant_id,
             conn_params=conn_params,
+            enable_reasoning=enable_reasoning,
+            reasoning_steps=reasoning_steps,
             debug=debug,
             **kwargs,
         )

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/utils/prompt_service.py

@@ -184,6 +184,16 @@ class PromptService:
         return self._fetch_template("llm_prompts/generate_sql")
     
     
+    def get_generate_sql_reasoning_template(self) -> ChatPromptTemplate:
+        """
+        Get generate SQL reasoning template from API service (cached)
+        
+        Returns:
+            ChatPromptTemplate object
+        """
+        return self._fetch_template("llm_prompts/generate_sql_reasoning")
+
+    
     def get_generate_answer_template(self) -> ChatPromptTemplate:
         """
         Get generate answer template from API service (cached)
@@ -264,6 +274,22 @@ def get_generate_sql_prompt_template(
     return PromptTemplateWrapper(prompt_service, "get_generate_sql_template")
 
 
+def get_generate_sql_reasoning_prompt_template(
+    conn_params: Optional[dict] = None
+) -> PromptTemplateWrapper:
+    """
+    Get generate SQL reasoning prompt template wrapper
+    
+    Args:
+        conn_params: Connection parameters including url, token, is_jwt, and jwt_tenant_id
+
+    Returns:
+        PromptTemplateWrapper for generate SQL reasoning
+    """
+    prompt_service = PromptService(conn_params=conn_params)
+    return PromptTemplateWrapper(prompt_service, "get_generate_sql_reasoning_template")
+
+
 def get_qa_prompt_template(
     conn_params: Optional[dict] = None
 ) -> PromptTemplateWrapper:

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/utils/timbr_llm_utils.py

@@ -1,21 +1,18 @@
 from typing import Any, Optional
 from langchain.llms.base import LLM
-import base64, hashlib
-from cryptography.fernet import Fernet
 from datetime import datetime
 import concurrent.futures
 import json
-from langchain_core.messages import HumanMessage, SystemMessage
 
-from .timbr_utils import get_datasources, get_tags, get_concepts, get_concept_properties, validate_sql, get_properties_description, get_relationships_description
+from .timbr_utils import get_datasources, get_tags, get_concepts, get_concept_properties, validate_sql, get_properties_description, get_relationships_description, cache_with_version_check, encrypt_prompt
 from .prompt_service import (
     get_determine_concept_prompt_template,
     get_generate_sql_prompt_template,
+    get_generate_sql_reasoning_prompt_template,
     get_qa_prompt_template
 )
 from ..config import llm_timeout
 
-
 def _clean_snowflake_prompt(prompt: Any) -> None:
     import re
 
@@ -55,14 +52,6 @@ def _clean_snowflake_prompt(prompt: Any) -> None:
     prompt[1].content = clean_func(prompt[1].content)  # User message
 
 
-def generate_key() -> bytes:
-    """Generate a new Fernet secret key."""
-    passcode = b"lucylit2025"
-    hlib = hashlib.md5()
-    hlib.update(passcode)
-    return base64.urlsafe_b64encode(hlib.hexdigest().encode('utf-8'))
-
-
 def _call_llm_with_timeout(llm: LLM, prompt: Any, timeout: int = 60) -> Any:
     """
     Call LLM with timeout to prevent hanging.
@@ -91,35 +80,9 @@ def _call_llm_with_timeout(llm: LLM, prompt: Any, timeout: int = 60) -> Any:
         except Exception as e:
             raise e
 
-ENCRYPT_KEY = generate_key()
 MEASURES_DESCRIPTION = "The following columns are calculated measures and can only be aggregated with an aggregate function: COUNT/SUM/AVG/MIN/MAX (count distinct is not allowed)"
 TRANSITIVE_RELATIONSHIP_DESCRIPTION = "Transitive relationship columns allow you to access data through multiple relationship hops. These columns follow the pattern `<relationship_name>[<table_name>*<number>].<column_name>` where the number after the asterisk (*) indicates how many relationship levels to traverse. For example, `acquired_by[company*4].company_name` means 'go through up to 4 levels of the acquired_by relationship to get the company name', while columns ending with '_transitivity_level' indicate the actual relationship depth (Cannot be null or 0 - level 1 represents direct relationships, while levels 2, 3, 4, etc. represent indirect relationships through multiple hops. To filter by relationship type, use `_transitivity_level = 1` for direct relationships only, `_transitivity_level > 1` for indirect relationships only."
 
-def encrypt_prompt(prompt: Any, key: Optional[bytes] = ENCRYPT_KEY) -> bytes:
-    """Serialize & encrypt the prompt; returns a URL-safe token."""
-    # build prompt_text as before…
-    if isinstance(prompt, str):
-        text = prompt
-    elif isinstance(prompt, list):
-        parts = []
-        for message in prompt:
-            if hasattr(message, "content"):
-                parts.append(f"{message.type}: {message.content}")
-            else:
-                parts.append(str(message))
-        text = "\n".join(parts)
-    else:
-        text = str(prompt)
-
-    f = Fernet(key)
-    return f.encrypt(text.encode()).decode('utf-8')
-
-
-def decrypt_prompt(token: bytes, key: bytes) -> str:
-    """Decrypt the token and return the original prompt string."""
-    f = Fernet(key)
-    return f.decrypt(token).decode()
-
 
 def _prompt_to_string(prompt: Any) -> str:
     prompt_text = ''
@@ -187,6 +150,7 @@ def _get_response_text(response: Any) -> str:
 
     return response_text
 
+
 def _extract_usage_metadata(response: Any) -> dict:
     """
     Extract usage metadata from LLM response across different providers.
@@ -287,6 +251,7 @@ def _extract_usage_metadata(response: Any) -> dict:
     
     return usage_metadata
 
+
 def determine_concept(
     question: str,
     llm: LLM,
@@ -479,10 +444,11 @@ def _get_active_datasource(conn_params: dict) -> dict:
     return datasources[0] if datasources else None
 
 
-def _evaluate_sql_with_reasoning(
+def _evaluate_sql_enable_reasoning(
     question: str,
     sql_query: str,
     llm: LLM,
+    conn_params: dict,
     timeout: int,
 ) -> dict:
     """
@@ -491,49 +457,17 @@ def _evaluate_sql_with_reasoning(
     Returns:
         dict with 'assessment' ('correct'|'partial'|'incorrect') and 'reasoning'
     """
-    system_prompt = """You are an expert SQL and data analysis evaluator for Timbr.ai knowledge graph queries.
-
-**IMPORTANT CONTEXT:**
-- This system uses Timbr.ai, which extends SQL with semantic graph layer, including traversals, measures and more
-- Field names may use special Timbr syntax that is NOT standard SQL but is VALID in this system:
-  * `measure.<measure_name>` - References computed measures (e.g., measure.total_balance_amount)
-  * `<relationship>[target_table].<property>` - Graph traversal syntax (e.g., has_account[Account].account_name)
-  * These are translated by Timbr to standard SQL before execution
-- DO NOT mark queries as incorrect based on field name syntax - Timbr validates this before execution
-
-Evaluate whether the generated query correctly addresses the business question:
-- **correct**: The query fully and accurately answers the question
-- **partial**: The query is partially correct or incomplete
-- **incorrect**: The query does not address the question or is wrong
-
-Return your evaluation as a JSON object with this exact structure:
-{
-  "assessment": "<correct|partial|incorrect>",
-  "reasoning": "<short but precise sentence explaining your assessment>"
-}
-
-Be concise and objective."""
-
-    user_prompt = f"""**Business Question:**
-{question}
-
-**Generated SQL Query:**
-```sql
-{sql_query}
-```
-
-Please evaluate this result."""
-    
-    messages = [
-        SystemMessage(content=system_prompt),
-        HumanMessage(content=user_prompt)
-    ]
+    generate_sql_reasoning_template = get_generate_sql_reasoning_prompt_template(conn_params)
+    prompt = generate_sql_reasoning_template.format_messages(
+        question=question.strip(),
+        sql_query=sql_query.strip(),
+    )
 
-    apx_token_count = _calculate_token_count(llm, messages)
+    apx_token_count = _calculate_token_count(llm, prompt)
     if hasattr(llm, "_llm_type") and "snowflake" in llm._llm_type:
-        _clean_snowflake_prompt(messages)
+        _clean_snowflake_prompt(prompt)
     
-    response = _call_llm_with_timeout(llm, messages, timeout=timeout)
+    response = _call_llm_with_timeout(llm, prompt, timeout=timeout)
     
     # Extract JSON from response content (handle markdown code blocks)
     content = response.content.strip()
@@ -559,6 +493,87 @@ Please evaluate this result."""
     }
 
 
+@cache_with_version_check
+def _build_sql_generation_context(
+    conn_params: dict,
+    schema: str,
+    concept: str,
+    concept_metadata: dict,
+    graph_depth: int,
+    include_tags: Optional[str],
+    exclude_properties: Optional[list],
+    db_is_case_sensitive: bool,
+    max_limit: int,
+) -> dict:
+    """
+    Prepare the complete SQL generation context by gathering all necessary metadata.
+    
+    This includes:
+    - Datasource information
+    - Concept properties (columns, measures, relationships)
+    - Property tags
+    - Building column/measure/relationship descriptions
+    - Assembling the final context dictionary
+    
+    Returns:
+        dict containing all context needed for SQL generation prompts
+    """
+    datasource_type = _get_active_datasource(conn_params).get('target_type')
+
+    properties_desc = get_properties_description(conn_params=conn_params)
+    relationships_desc = get_relationships_description(conn_params=conn_params)
+  
+    concept_properties_metadata = get_concept_properties(
+        schema=schema,
+        concept_name=concept,
+        conn_params=conn_params,
+        properties_desc=properties_desc,
+        relationships_desc=relationships_desc,
+        graph_depth=graph_depth
+    )
+    columns = concept_properties_metadata.get('columns', [])
+    measures = concept_properties_metadata.get('measures', [])
+    relationships = concept_properties_metadata.get('relationships', {})
+    tags = get_tags(conn_params=conn_params, include_tags=include_tags).get('property_tags')
+
+    columns_str = _build_columns_str(columns, columns_tags=tags, exclude=exclude_properties)
+    measures_str = _build_columns_str(measures, tags, exclude=exclude_properties)
+    rel_prop_str = _build_rel_columns_str(relationships, columns_tags=tags, exclude_properties=exclude_properties)
+
+    if rel_prop_str:
+        measures_str += f"\n{rel_prop_str}"
+
+    # Determine if relationships have transitive properties
+    has_transitive_relationships = any(
+        rel.get('is_transitive')
+        for rel in relationships.values()
+    ) if relationships else False
+    
+    concept_description = f"- Description: {concept_metadata.get('description')}\n" if concept_metadata and concept_metadata.get('description') else ""
+    concept_tags = concept_metadata.get('tags') if concept_metadata and concept_metadata.get('tags') else ""
+    
+    cur_date = datetime.now().strftime("%Y-%m-%d")
+    
+    # Build context descriptions
+    sensitivity_txt = "- Ensure value comparisons are case-insensitive, e.g., use LOWER(column) = 'value'.\n" if db_is_case_sensitive else ""
+    measures_context = f"- {MEASURES_DESCRIPTION}: {measures_str}\n" if measures_str else ""
+    transitive_context = f"- {TRANSITIVE_RELATIONSHIP_DESCRIPTION}\n" if has_transitive_relationships else ""
+    
+    return {
+        'cur_date': cur_date,
+        'datasource_type': datasource_type or 'standard sql',
+        'schema': schema,
+        'concept': concept,
+        'concept_description': concept_description or "",
+        'concept_tags': concept_tags or "",
+        'columns_str': columns_str,
+        'measures_context': measures_context,
+        'transitive_context': transitive_context,
+        'sensitivity_txt': sensitivity_txt,
+        'max_limit': max_limit,
+    }
+
+
 def _generate_sql_with_llm(
     question: str,
     llm: LLM,
@@ -639,7 +654,7 @@ def generate_sql(
         note: Optional[str] = '',
         db_is_case_sensitive: Optional[bool] = False,
         graph_depth: Optional[int] = 1,
-        with_reasoning: Optional[bool] = False,
+        enable_reasoning: Optional[bool] = False,
         reasoning_steps: Optional[int] = 2,
         debug: Optional[bool] = False,
         timeout: Optional[int] = None,
@@ -679,50 +694,6 @@ def generate_sql(
     if not concept:
         raise Exception("No relevant concept found for the query.")
 
-    datasource_type = _get_active_datasource(conn_params).get('target_type')
-
-    properties_desc = get_properties_description(conn_params=conn_params)
-    relationships_desc = get_relationships_description(conn_params=conn_params)
-  
-    concept_properties_metadata = get_concept_properties(schema=schema, concept_name=concept, conn_params=conn_params, properties_desc=properties_desc, relationships_desc=relationships_desc, graph_depth=graph_depth)
-    columns, measures, relationships = concept_properties_metadata.get('columns', []), concept_properties_metadata.get('measures', []), concept_properties_metadata.get('relationships', {})
-    tags = get_tags(conn_params=conn_params, include_tags=include_tags).get('property_tags')
-
-    columns_str = _build_columns_str(columns, columns_tags=tags, exclude=exclude_properties)
-    measures_str = _build_columns_str(measures, tags, exclude=exclude_properties)
-    rel_prop_str = _build_rel_columns_str(relationships, columns_tags=tags, exclude_properties=exclude_properties)
-
-    if rel_prop_str:
-        measures_str += f"\n{rel_prop_str}"
-
-
-    # Build context descriptions
-    sensitivity_txt = "- Ensure value comparisons are case-insensitive, e.g., use LOWER(column) = 'value'.\n" if db_is_case_sensitive else ""
-    measures_context = f"- {MEASURES_DESCRIPTION}: {measures_str}\n" if measures_str else ""
-    has_transitive_relationships = any(
-        rel.get('is_transitive')
-        for rel in relationships.values()
-    ) if relationships else False
-    transitive_context = f"- {TRANSITIVE_RELATIONSHIP_DESCRIPTION}\n" if has_transitive_relationships else ""
-    concept_description = f"- Description: {concept_metadata.get('description')}\n" if concept_metadata and concept_metadata.get('description') else ""
-    concept_tags = concept_metadata.get('tags') if concept_metadata and concept_metadata.get('tags') else ""
-    cur_date = datetime.now().strftime("%Y-%m-%d")
-
-    # Build context dict for SQL generation
-    current_context = {
-        'cur_date': cur_date,
-        'datasource_type': datasource_type or 'standard sql',
-        'schema': schema,
-        'concept': concept,
-        'concept_description': concept_description or "",
-        'concept_tags': concept_tags or "",
-        'columns_str': columns_str,
-        'measures_context': measures_context,
-        'transitive_context': transitive_context,
-        'sensitivity_txt': sensitivity_txt,
-        'max_limit': max_limit,
-    }
-
     sql_query = None
     iteration = 0
     is_sql_valid = True
@@ -737,7 +708,16 @@ def generate_sql(
                 llm=llm,
                 conn_params=conn_params,
                 generate_sql_prompt=generate_sql_prompt,
-                current_context=current_context,
+                current_context=_build_sql_generation_context(
+                    conn_params=conn_params,
+                    schema=schema,
+                    concept=concept,
+                    concept_metadata=concept_metadata,
+                    graph_depth=graph_depth,
+                    include_tags=include_tags,
+                    exclude_properties=exclude_properties,
+                    db_is_case_sensitive=db_is_case_sensitive,
+                    max_limit=max_limit),
                 note=note + err_txt,
                 should_validate_sql=should_validate_sql,
                 timeout=timeout,
@@ -766,18 +746,19 @@ def generate_sql(
                 raise Exception(error)
     
     
-    if with_reasoning and sql_query is not None:
+    if enable_reasoning and sql_query is not None:
         for step in range(reasoning_steps):
             try:
                 # Step 1: Evaluate the current SQL
-                eval_result = _evaluate_sql_with_reasoning(
+                eval_result = _evaluate_sql_enable_reasoning(
                     question=question,
                     sql_query=sql_query,
                     llm=llm,
+                    conn_params=conn_params,
                     timeout=timeout,
                 )
                 
-                usage_metadata[f'sql_reasoning_step_{step}'] = {
+                usage_metadata[f'sql_reasoning_step_{step + 1}'] = {
                     "approximate": eval_result['apx_token_count'],
                     **eval_result['usage_metadata'],
                 }
@@ -791,24 +772,35 @@ def generate_sql(
                 # Step 2: Regenerate SQL with feedback
                 evaluation_note = note + f"\n\nThe previously generated SQL: `{sql_query}` was assessed as '{evaluation.get('assessment')}' because: {evaluation.get('reasoning', '*could not determine cause*')}. Please provide a corrected SQL query that better answers the question: '{question}'."
                 
+                # Increase graph depth for 2nd+ reasoning attempts, up to max of 3
+                context_graph_depth = min(3, int(graph_depth) + step) if graph_depth < 3 and step > 0 else graph_depth
                 regen_result = _generate_sql_with_llm(
                     question=question,
                     llm=llm,
                     conn_params=conn_params,
                     generate_sql_prompt=generate_sql_prompt,
-                    current_context=current_context,
+                    current_context=_build_sql_generation_context(
+                        conn_params=conn_params,
+                        schema=schema,
+                        concept=concept,
+                        concept_metadata=concept_metadata,
+                        graph_depth=context_graph_depth,
+                        include_tags=include_tags,
+                        exclude_properties=exclude_properties,
+                        db_is_case_sensitive=db_is_case_sensitive,
+                        max_limit=max_limit),
                     note=evaluation_note,
                     should_validate_sql=should_validate_sql,
                     timeout=timeout,
                     debug=debug,
                 )
                 
-                usage_metadata[f'generate_sql_reasoning_step_{step}'] = {
+                usage_metadata[f'generate_sql_reasoning_step_{step + 1}'] = {
                     "approximate": regen_result['apx_token_count'],
                     **regen_result['usage_metadata'],
                 }
                 if debug and 'p_hash' in regen_result:
-                    usage_metadata[f'generate_sql_reasoning_step_{step}']['p_hash'] = regen_result['p_hash']
+                    usage_metadata[f'generate_sql_reasoning_step_{step + 1}']['p_hash'] = regen_result['p_hash']
                 
                 sql_query = regen_result['sql']
                 is_sql_valid = regen_result['is_valid']

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/src/langchain_timbr/utils/timbr_utils.py

@@ -1,7 +1,10 @@
 from typing import Optional, Any
 import time
+import base64
+import hashlib
 from pytimbr_api import timbr_http_connector
 from functools import wraps
+from cryptography.fernet import Fernet
 
 from ..config import cache_timeout, ignore_tags, ignore_tags_prefix
 from .general import to_boolean
@@ -40,6 +43,42 @@ def _serialize_cache_key(*args, **kwargs):
     return (tuple(serialize(arg) for arg in args), tuple((k, serialize(v)) for k, v in kwargs.items()))
 
 
+def generate_key() -> bytes:
+    """Generate a new Fernet secret key."""
+    passcode = b"lucylit2025"
+    hlib = hashlib.md5()
+    hlib.update(passcode)
+    return base64.urlsafe_b64encode(hlib.hexdigest().encode('utf-8'))
+
+
+ENCRYPT_KEY = generate_key()
+
+
+def encrypt_prompt(prompt: Any, key: Optional[bytes] = ENCRYPT_KEY) -> bytes:
+    """Serialize & encrypt the prompt; returns a URL-safe token."""
+    if isinstance(prompt, str):
+        text = prompt
+    elif isinstance(prompt, list):
+        parts = []
+        for message in prompt:
+            if hasattr(message, "content"):
+                parts.append(f"{message.type}: {message.content}")
+            else:
+                parts.append(str(message))
+        text = "\n".join(parts)
+    else:
+        text = str(prompt)
+
+    f = Fernet(key)
+    return f.encrypt(text.encode()).decode('utf-8')
+
+
+def decrypt_prompt(token: bytes, key: bytes) -> str:
+    """Decrypt the token and return the original prompt string."""
+    f = Fernet(key)
+    return f.decrypt(token).decode()
+
+
 def cache_with_version_check(func):
     """Decorator to cache function results and invalidate if ontology version changes."""
 

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/tests/conftest.py

@@ -16,6 +16,7 @@ def config():
         "test_prompt": os.environ.get("TEST_PROMPT", "What are the total sales for consumer customers?"),
         "test_prompt_2": os.environ.get("TEST_PROMPT_2", "Get all customers"),
         "test_prompt_3": os.environ.get("TEST_PROMPT_3", "Get all products and materials"),
+        "test_reasoning_prompt": os.environ.get("TEST_REASONING_PROMPT", "show me 10 orders in 2021 that contain metal"),
         "verify_ssl": os.environ.get("VERIFY_SSL", "true"),
         "jwt_timbr_url": os.environ.get("JWT_TIMBR_URL", "https://staging.timbr.ai:443/"),
         "jwt_timbr_ontology": os.environ.get("JWT_TIMBR_ONTOLOGY", "supply_metrics"),

langchain_timbr-2.1.7/tests/integration/test_chain_reasoning.py

@@ -0,0 +1,84 @@
+from langchain_timbr import (
+  GenerateTimbrSqlChain,
+  ValidateTimbrSqlChain,
+  ExecuteTimbrQueryChain,
+  create_timbr_sql_agent
+)
+
+class TestLangchainChainsReasoningIntegration:
+    def _assert_reasoning(self, chain, result, usage_metadata_key=None):
+        assert 'reasoning_status' in result
+        assert result['reasoning_status'] in ['correct', 'partial', 'incorrect']
+        
+        usage_metadata = result.get(usage_metadata_key or chain.usage_metadata_key, {})
+        assert 'sql_reasoning_step_1' in usage_metadata
+
+        # if first reasoning was incorrect, there must be a re-generating sql & a second reasoning step
+        if 'sql_reasoning_step_2' in usage_metadata:
+          assert 'generate_sql_reasoning_step_1' in usage_metadata
+
+        # if the final result was incorrect - there must have two re-generation steps
+        if result['reasoning_status'] == 'incorrect':
+            assert 'generate_sql_reasoning_step_2' in usage_metadata
+
+    # SKIP THIS TESTS UNTIL API WILL BE UPDATED
+
+    def skip_test_generate_timbr_sql_chain(self, llm, config):
+        chain = GenerateTimbrSqlChain(
+            llm=llm,
+            url=config["timbr_url"],
+            token=config["timbr_token"],
+            ontology=config["timbr_ontology"],
+            verify_ssl=config["verify_ssl"],
+            enable_reasoning=True,
+        )
+        result = chain.invoke({ "prompt": config["test_reasoning_prompt"] })
+        print("GenerateTimbrSqlChain result:", result)
+        self._assert_reasoning(chain, result)
+
+    def skip_test_validate_timbr_sql_chain(self, llm, config):
+        chain = ValidateTimbrSqlChain(
+            llm=llm,
+            url=config["timbr_url"],
+            token=config["timbr_token"],
+            ontology=config["timbr_ontology"],
+            retries=1,  # Use a single retry for test speed
+            verify_ssl=config["verify_ssl"],
+            enable_reasoning=True,
+        )
+        inputs = {
+            "prompt": config["test_reasoning_prompt"],
+            "sql": "SELECT * FROM invalid_table",  # Intentionally invalid (or test with a valid one if available)
+        }
+        result = chain.invoke(inputs)
+        print("ValidateTimbrSqlChain result:", result)
+        self._assert_reasoning(chain, result)
+
+    def skip_test_execute_timbr_query_chain(self, llm, config):
+        chain = ExecuteTimbrQueryChain(
+            llm=llm,
+            url=config["timbr_url"],
+            token=config["timbr_token"],
+            ontology=config["timbr_ontology"],
+            verify_ssl=config["verify_ssl"],
+            enable_reasoning=True,
+        )
+        inputs = {
+            "prompt": config["test_reasoning_prompt"],
+        }
+        result = chain.invoke(inputs)
+        print("ExecuteTimbrQueryChain result:", result)
+        self._assert_reasoning(chain, result)
+
+    def skip_test_create_timbr_sql_agent(self, llm, config):
+        agent = create_timbr_sql_agent(
+            llm=llm,
+            url=config["timbr_url"],
+            token=config["timbr_token"],
+            ontology=config["timbr_ontology"],
+            verify_ssl=config["verify_ssl"],
+            enable_reasoning=True,
+        )
+        result = agent.invoke(config["test_reasoning_prompt"])
+        print("Timbr SQL Agent result:", result)
+        self._assert_reasoning(agent, result, usage_metadata_key="usage_metadata")

{langchain_timbr-2.1.6 → langchain_timbr-2.1.7}/tests/integration/test_langchain_chains.py

@@ -5,9 +5,10 @@ from langchain_timbr import (
     GenerateTimbrSqlChain,
     ValidateTimbrSqlChain,
     ExecuteTimbrQueryChain,
-    GenerateAnswerChain
+    GenerateAnswerChain,
+    generate_key,
+    decrypt_prompt,
 )
-from langchain_timbr.utils import timbr_llm_utils
 
 
 class TestIdentifyTimbrConceptChain:
@@ -147,7 +148,7 @@ class TestGenerateTimbrSqlChain:
         print("GenerateTimbrSqlChain result:", result)
         assert "sql" in result and result["sql"], "SQL should be generated"
         assert "concept" in result and result["concept"] == "customer", "Concept customer should be returned"
-        prompt = timbr_llm_utils.decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], timbr_llm_utils.generate_key())
+        prompt = decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], generate_key())
         assert "customer related info" in prompt, "Customer description should be in prompt"
         assert "concat of first and last name" in prompt, "Customer name description should be in prompt"
         assert "continent name" in prompt, "Order market description should be in prompt"
@@ -170,7 +171,7 @@ class TestGenerateTimbrSqlChain:
         print("GenerateTimbrSqlChain result:", result)
         assert "sql" in result and result["sql"], "SQL should be generated"
         assert "concept" in result and result["concept"] == "customer", "Concept customer should be returned"
-        prompt = timbr_llm_utils.decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], timbr_llm_utils.generate_key())
+        prompt = decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], generate_key())
         assert "customer related info" in prompt, "Customer description should be in prompt"
         assert "concat of first and last name" in prompt, "Customer name description should be in prompt"
         assert "continent name" in prompt, "Order market description should be in prompt"
@@ -193,7 +194,7 @@ class TestGenerateTimbrSqlChain:
         print("GenerateTimbrSqlChain result:", result)
         assert "sql" in result and result["sql"], "SQL should be generated"
         assert "concept" in result and result["concept"] == "customer_cube", "Concept customer_cube should be returned"
-        prompt = timbr_llm_utils.decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], timbr_llm_utils.generate_key())
+        prompt = decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], generate_key())
         assert "customer cube related info" in prompt, "Customer description should be in prompt"
         assert "concat of first and last name" in prompt, "Customer name description should be in prompt"
         assert "continent name" in prompt, "Order market description should be in prompt"
@@ -216,7 +217,7 @@ class TestGenerateTimbrSqlChain:
         assert "sql" in result and result["sql"], "SQL should be generated"
         assert "concept" in result and result["concept"] == "product", "Concept product should be returned"
         assert chain.usage_metadata_key in result, "Chain should return 'usage_metadata'"
-        prompt = timbr_llm_utils.decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], timbr_llm_utils.generate_key())
+        prompt = decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], generate_key())
         assert "commodity" in prompt, "Product tag value of synonym should be in prompt"
         assert "synonym" in prompt, "Product tag synonym should be in prompt"
         assert "length" in prompt, "Material tag should be in prompt"
@@ -240,7 +241,7 @@ class TestGenerateTimbrSqlChain:
         assert "sql" in result and result["sql"], "SQL should be generated"
         assert "concept" in result and result["concept"] == "product", "Concept product should be returned"
         assert chain.usage_metadata_key in result, "Chain should return 'usage_metadata'"
-        prompt = timbr_llm_utils.decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], timbr_llm_utils.generate_key())
+        prompt = decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], generate_key())
         assert "commodity" in prompt, "Product tag value of synonym should be in prompt"
         assert "synonym" in prompt, "Product tag synonym should be in prompt"
         assert "length" in prompt, "Material tag should be in prompt"
@@ -265,7 +266,7 @@ class TestGenerateTimbrSqlChain:
         assert "sql" in result and result["sql"], "SQL should be generated"
         assert "concept" in result and result["concept"] == "product_cube", "Concept product_cube should be returned"
         assert chain.usage_metadata_key in result, "Chain should return 'usage_metadata'"
-        prompt = timbr_llm_utils.decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], timbr_llm_utils.generate_key())
+        prompt = decrypt_prompt(result["generate_sql_usage_metadata"]["generate_sql"]["p_hash"], generate_key())
         assert "commodity cube" in prompt, "Product tag value of synonym should be in prompt"
         assert "synonym" in prompt, "Product tag synonym should be in prompt"
         assert "length" in prompt, "Material tag should be in prompt"