langchain-timbr 2.1.6__py3-none-any.whl → 2.1.7__py3-none-any.whl

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/_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/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/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/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/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/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/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/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/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/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/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/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.dist-info → langchain_timbr-2.1.7.dist-info}/METADATA

@@ -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.7.dist-info/RECORD

@@ -0,0 +1,28 @@
+langchain_timbr/__init__.py,sha256=qNyk3Rt-8oWr_OGuU_E-6siNZXuCnvVEkj65EIuVbbQ,824
+langchain_timbr/_version.py,sha256=MO-pKnEzeW3zl7_c60hrWWrquNyRCaWfqqY8EMXwxVA,704
+langchain_timbr/config.py,sha256=c3A_HIw1b1Y6tc4EaXHZRJ_OptGLzl5bQGzx4ec_tgM,1605
+langchain_timbr/timbr_llm_connector.py,sha256=mdkWskpvmXZre5AzVFn6KfPnVH5YN5MIwfEoXWBLMgY,13170
+langchain_timbr/langchain/__init__.py,sha256=ejcsZKP9PK0j4WrrCCcvBXpDpP-TeRiVb21OIUJqix8,580
+langchain_timbr/langchain/execute_timbr_query_chain.py,sha256=snfx22QE0hM3pjvoApUBFGvtIqNt2Yy1PFnx4uuRScs,16316
+langchain_timbr/langchain/generate_answer_chain.py,sha256=nteA4QZp9CAOskTBl_CokwaMlqnR2g2GvKz2mLs9WVY,4871
+langchain_timbr/langchain/generate_timbr_sql_chain.py,sha256=G2uEPB4NbZcDIkWtoxVlPNcuaaUcEmUcP39_4U5aYK0,9811
+langchain_timbr/langchain/identify_concept_chain.py,sha256=kuzg0jJQpFGIiaxtNhdQ5K4HXveLVwONFNsoipPCteE,7169
+langchain_timbr/langchain/timbr_sql_agent.py,sha256=fCYAYjvE_9xVtp-xicOGKRbvtjK8gRipXkSl9mKTcio,20810
+langchain_timbr/langchain/validate_timbr_sql_chain.py,sha256=rq3fVmNyt_D1vfRbvn21f_lACSqPiHdVMri4Gofw5nY,10264
+langchain_timbr/langgraph/__init__.py,sha256=mKBFd0x01jWpRujUWe-suX3FFhenPoDxrvzs8I0mum0,457
+langchain_timbr/langgraph/execute_timbr_query_node.py,sha256=Tz7N3tCGJgot7v23SxYZaoG2o0kxXanv0wLcT1pJwyc,5994
+langchain_timbr/langgraph/generate_response_node.py,sha256=opwscNEXabaSyCFLbzGQFkDFEymJurhNU9aAtm1rnOk,2375
+langchain_timbr/langgraph/generate_timbr_sql_node.py,sha256=kd_soT3w3V0fGDI52R_iL0S1jlTApUawWxRJFQ6yo_Q,5370
+langchain_timbr/langgraph/identify_concept_node.py,sha256=aiLDFEcz_vM4zZ_ULe1SvJKmI-e4Fb2SibZQaEPz_eY,3649
+langchain_timbr/langgraph/validate_timbr_query_node.py,sha256=utdy8cj3Pe6cd3OSAUjpCh7gwQI8EaenUW7bmptC7iQ,5191
+langchain_timbr/llm_wrapper/llm_wrapper.py,sha256=j94DqIGECXyfAVayLC7VaNxs_8n1qYFiHY2Qvt2B3Bc,17537
+langchain_timbr/llm_wrapper/timbr_llm_wrapper.py,sha256=sDqDOz0qu8b4WWlagjNceswMVyvEJ8yBWZq2etBh-T0,1362
+langchain_timbr/utils/general.py,sha256=KkehHvIj8GoQ_0KVXLcUVeaYaTtkuzgXmYYx2TXJhI4,10253
+langchain_timbr/utils/prompt_service.py,sha256=QVmfA9cHO2IPVsKG8V5cuMm2gPfvRq2VzLcx04sqT88,12197
+langchain_timbr/utils/temperature_supported_models.json,sha256=d3UmBUpG38zDjjB42IoGpHTUaf0pHMBRSPY99ao1a3g,1832
+langchain_timbr/utils/timbr_llm_utils.py,sha256=7jg5TxTMkdLKZPvGbS49bTSmX6z8gbP84iKb_JALTy8,34646
+langchain_timbr/utils/timbr_utils.py,sha256=x-z46NQn8nhRR8PJ5l23uh0qEpDWbhD8x4r-DyY4IYY,18864
+langchain_timbr-2.1.7.dist-info/METADATA,sha256=aV12qFam0Klb2tGTr5we4lb9PzFRQFEEMsOZ0wcMYgQ,10724
+langchain_timbr-2.1.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+langchain_timbr-2.1.7.dist-info/licenses/LICENSE,sha256=0ITGFk2alkC7-e--bRGtuzDrv62USIiVyV2Crf3_L_0,1065
+langchain_timbr-2.1.7.dist-info/RECORD,,

langchain_timbr-2.1.6.dist-info/RECORD

@@ -1,28 +0,0 @@
-langchain_timbr/__init__.py,sha256=gxd6Y6QDmYZtPlYVdXtPIy501hMOZXHjWh2qq4qzt_s,828
-langchain_timbr/_version.py,sha256=EwjLAOHxpsOZpfhlwgV2gSqwFh_1AQNnM-WrOk4-4zg,704
-langchain_timbr/config.py,sha256=CdDuUKbI_sdjNkGVk_QEmeqQHjFlJjBY1VI19JuBG2o,1601
-langchain_timbr/timbr_llm_connector.py,sha256=mdkWskpvmXZre5AzVFn6KfPnVH5YN5MIwfEoXWBLMgY,13170
-langchain_timbr/langchain/__init__.py,sha256=ejcsZKP9PK0j4WrrCCcvBXpDpP-TeRiVb21OIUJqix8,580
-langchain_timbr/langchain/execute_timbr_query_chain.py,sha256=6USOkCJih0yGk7PgYW_zTHJfip4DpFcvkD-VhI2dMp0,16302
-langchain_timbr/langchain/generate_answer_chain.py,sha256=nteA4QZp9CAOskTBl_CokwaMlqnR2g2GvKz2mLs9WVY,4871
-langchain_timbr/langchain/generate_timbr_sql_chain.py,sha256=XmEkEU4q8t66GJZE-pWAAWqYYFFfv9ej6DzjRiTVNRw,9797
-langchain_timbr/langchain/identify_concept_chain.py,sha256=kuzg0jJQpFGIiaxtNhdQ5K4HXveLVwONFNsoipPCteE,7169
-langchain_timbr/langchain/timbr_sql_agent.py,sha256=tIcr2SCSb5LnOA3zreZbzOvVgR8e2NFv4HaLVcLUNCg,20790
-langchain_timbr/langchain/validate_timbr_sql_chain.py,sha256=OcE_7yfb9xpD-I4OS7RG1bY4-yi1UicjvGegOv_vkQU,9567
-langchain_timbr/langgraph/__init__.py,sha256=mKBFd0x01jWpRujUWe-suX3FFhenPoDxrvzs8I0mum0,457
-langchain_timbr/langgraph/execute_timbr_query_node.py,sha256=UddbYiQya_-QlZm-QdImxpvzfiNiRDHyiLAHdpTEzXc,5984
-langchain_timbr/langgraph/generate_response_node.py,sha256=opwscNEXabaSyCFLbzGQFkDFEymJurhNU9aAtm1rnOk,2375
-langchain_timbr/langgraph/generate_timbr_sql_node.py,sha256=TekD9D0rM4aKuzS50Kzwkbshei5NHbTTVTXUC41dnyU,5360
-langchain_timbr/langgraph/identify_concept_node.py,sha256=aiLDFEcz_vM4zZ_ULe1SvJKmI-e4Fb2SibZQaEPz_eY,3649
-langchain_timbr/langgraph/validate_timbr_query_node.py,sha256=-2fuieCz1hv6ua-17zfonme8LQ_OoPnoOBTdGSXkJgs,4793
-langchain_timbr/llm_wrapper/llm_wrapper.py,sha256=j94DqIGECXyfAVayLC7VaNxs_8n1qYFiHY2Qvt2B3Bc,17537
-langchain_timbr/llm_wrapper/timbr_llm_wrapper.py,sha256=sDqDOz0qu8b4WWlagjNceswMVyvEJ8yBWZq2etBh-T0,1362
-langchain_timbr/utils/general.py,sha256=KkehHvIj8GoQ_0KVXLcUVeaYaTtkuzgXmYYx2TXJhI4,10253
-langchain_timbr/utils/prompt_service.py,sha256=QT7kiq72rQno77z1-tvGGD7HlH_wdTQAl_1teSoKEv4,11373
-langchain_timbr/utils/temperature_supported_models.json,sha256=d3UmBUpG38zDjjB42IoGpHTUaf0pHMBRSPY99ao1a3g,1832
-langchain_timbr/utils/timbr_llm_utils.py,sha256=6CHCwMHOPZtLjxh49a4UoxGxgTmuOUO3R8sJMHsGKxI,34970
-langchain_timbr/utils/timbr_utils.py,sha256=SvmQ0wYicODNhmo8c-5_KPDBAfrBVBkUfoO8sPItQhk,17759
-langchain_timbr-2.1.6.dist-info/METADATA,sha256=imT7XLtey6gdk7WJlp6ZcYnndjCE6hAJ6QPzQmgcyJo,10724
-langchain_timbr-2.1.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-langchain_timbr-2.1.6.dist-info/licenses/LICENSE,sha256=0ITGFk2alkC7-e--bRGtuzDrv62USIiVyV2Crf3_L_0,1065
-langchain_timbr-2.1.6.dist-info/RECORD,,