langchain-timbr 2.1.14__tar.gz → 3.0.0__tar.gz

{langchain_timbr-2.1.14 → langchain_timbr-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-timbr
-Version: 2.1.14
+Version: 3.0.0
 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.14 → langchain_timbr-3.0.0}/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.14'
-__version_tuple__ = version_tuple = (2, 1, 14)
+__version__ = version = '3.0.0'
+__version_tuple__ = version_tuple = (3, 0, 0)
 
 __commit_id__ = commit_id = None

{langchain_timbr-2.1.14 → langchain_timbr-3.0.0}/src/langchain_timbr/langchain/execute_timbr_query_chain.py

@@ -2,6 +2,8 @@ from typing import Optional, Union, Dict, Any
 from langchain.chains.base import Chain
 from langchain.llms.base import LLM
 
+from langchain_timbr.utils.timbr_utils import get_timbr_agent_options
+
 from ..utils.general import parse_list, to_boolean, to_integer, validate_timbr_connection_params
 from ..utils.timbr_utils import run_query, validate_sql
 from ..utils.timbr_llm_utils import generate_sql
@@ -16,6 +18,8 @@ class ExecuteTimbrQueryChain(Chain):
     returns the query results, handling retries and result validation. It uses an LLM
     for query generation and connects to Timbr via URL and token.
     """
+
+    _ontology: Optional[str] = None
     
     def __init__(
         self,
@@ -38,6 +42,7 @@ class ExecuteTimbrQueryChain(Chain):
         note: Optional[str] = '',
         db_is_case_sensitive: Optional[bool] = False,
         graph_depth: Optional[int] = 1,
+        agent: Optional[str] = None,
         verify_ssl: Optional[bool] = True,
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
@@ -67,6 +72,7 @@ class ExecuteTimbrQueryChain(Chain):
         :param note: Optional additional note to extend our llm prompt
         :param db_is_case_sensitive: Whether the database is case sensitive (default is False).
         :param graph_depth: Maximum number of relationship hops to traverse from the source concept during schema exploration (default is 1).
+        :param agent: Optional Timbr agent name for options setup.
         :param verify_ssl: Whether to verify SSL certificates (default is True).
         :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).
@@ -116,33 +122,64 @@ class ExecuteTimbrQueryChain(Chain):
         
         self._url = url if url is not None else config.url
         self._token = token if token is not None else config.token
-        self._ontology = ontology if ontology is not None else config.ontology
         
         # Validate required parameters
         validate_timbr_connection_params(self._url, self._token)
         
-        self._schema = schema
-        self._concept = concept
-        self._concepts_list = parse_list(concepts_list)
-        self._views_list = parse_list(views_list)
-        self._include_tags = parse_list(include_tags)
-        self._include_logic_concepts = to_boolean(include_logic_concepts)
-        self._exclude_properties = parse_list(exclude_properties)
-        self._should_validate_sql = to_boolean(should_validate_sql)
-        self._retries = to_integer(retries)
-        self._max_limit = to_integer(max_limit)
-        self._retry_if_no_results = to_boolean(retry_if_no_results)
-        self._no_results_max_retries = to_integer(no_results_max_retries)
-        self._note = note
-        self._db_is_case_sensitive = to_boolean(db_is_case_sensitive)
-        self._graph_depth = to_integer(graph_depth)
         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._max_limit = config.llm_default_limit # use default value so the self._get_conn_params() won't fail before agent options are processed
+
+        self._agent = agent
+        if self._agent:
+            agent_options = get_timbr_agent_options(self._agent, conn_params=self._get_conn_params())
+
+            self._ontology = agent_options.get("ontology") if "ontology" in agent_options else None
+            self._schema = agent_options.get("schema") if "schema" in agent_options else schema
+            self._concept = agent_options.get("concept") if "concept" in agent_options else None
+            self._concepts_list = parse_list(agent_options.get("concepts_list")) if "concepts_list" in agent_options else None
+            self._views_list = parse_list(agent_options.get("views_list")) if "views_list" in agent_options else None
+            self._include_tags = parse_list(agent_options.get("include_tags")) if "include_tags" in agent_options else None
+            self._include_logic_concepts = to_boolean(agent_options.get("include_logic_concepts")) if "include_logic_concepts" in agent_options else False
+            self._exclude_properties = parse_list(agent_options.get("exclude_properties")) if "exclude_properties" in agent_options else ['entity_id', 'entity_type', 'entity_label']
+            self._should_validate_sql = to_boolean(agent_options.get("should_validate_sql")) if "should_validate_sql" in agent_options else config.should_validate_sql
+            self._retries = to_integer(agent_options.get("retries") if "retries" in agent_options else retries)
+            self._max_limit = to_integer(agent_options.get("max_limit")) if "max_limit" in agent_options else config.llm_default_limit
+            self._retry_if_no_results = to_boolean(agent_options.get("retry_if_no_results")) if "retry_if_no_results" in agent_options else config.retry_if_no_results
+            self._no_results_max_retries = to_integer(agent_options.get("no_results_max_retries")) if "no_results_max_retries" in agent_options else 2
+            self._db_is_case_sensitive = to_boolean(agent_options.get("db_is_case_sensitive")) if "db_is_case_sensitive" in agent_options else False
+            self._graph_depth = to_integer(agent_options.get("graph_depth")) if "graph_depth" in agent_options else 1
+            self._note = agent_options.get("note") if "note" in agent_options else ''
+            if note:
+                self._note = ((self._note + '\n') if self._note else '') + note
+            self._enable_reasoning = to_boolean(agent_options.get("enable_reasoning")) if "enable_reasoning" in agent_options else config.enable_reasoning
+            if enable_reasoning is not None and enable_reasoning != self._enable_reasoning:
+                self._enable_reasoning = to_boolean(enable_reasoning)
+            self._reasoning_steps = to_integer(agent_options.get("reasoning_steps")) if "reasoning_steps" in agent_options else config.reasoning_steps
+            if reasoning_steps is not None and reasoning_steps != self._reasoning_steps:
+                self._reasoning_steps = to_integer(reasoning_steps)
+        else:
+            self._ontology = ontology if ontology is not None else config.ontology
+            self._schema = schema
+            self._concept = concept
+            self._concepts_list = parse_list(concepts_list)
+            self._views_list = parse_list(views_list)
+            self._include_tags = parse_list(include_tags)
+            self._include_logic_concepts = to_boolean(include_logic_concepts)
+            self._exclude_properties = parse_list(exclude_properties)
+            self._should_validate_sql = to_boolean(should_validate_sql)
+            self._retries = to_integer(retries)
+            self._max_limit = to_integer(max_limit)
+            self._retry_if_no_results = to_boolean(retry_if_no_results)
+            self._no_results_max_retries = to_integer(no_results_max_retries)
+            self._db_is_case_sensitive = to_boolean(db_is_case_sensitive)
+            self._graph_depth = to_integer(graph_depth)
+            self._note = note
+            self._enable_reasoning = to_boolean(enable_reasoning)
+            self._reasoning_steps = to_integer(reasoning_steps)
 
 
     @property
@@ -171,7 +208,7 @@ class ExecuteTimbrQueryChain(Chain):
         return {
             "url": self._url,
             "token": self._token,
-            "ontology": self._ontology,
+            "ontology": self._ontology if self._ontology is not None else config.ontology,
             "verify_ssl": self._verify_ssl,
             "is_jwt": self._is_jwt,
             "jwt_tenant_id": self._jwt_tenant_id,
@@ -247,6 +284,8 @@ class ExecuteTimbrQueryChain(Chain):
             concept_name = inputs.get("concept", self._concept)
             is_sql_valid = True
             error = None
+            identify_concept_reason = None
+            generate_sql_reason = None
             reasoning_status = None
             rows = []
             usage_metadata = {}
@@ -270,6 +309,8 @@ class ExecuteTimbrQueryChain(Chain):
                         is_sql_valid = True
 
                     error = generate_res.get("error")
+                    identify_concept_reason = generate_res.get("identify_concept_reason")
+                    generate_sql_reason = generate_res.get("generate_sql_reason")
                     usage_metadata = self._summarize_usage_metadata(usage_metadata, generate_res.get("usage_metadata", {}))
                 
                 is_sql_not_tried = not any(sql.lower().strip() == gen.lower().strip() for gen in generated)
@@ -305,6 +346,8 @@ class ExecuteTimbrQueryChain(Chain):
                 "concept": concept_name,
                 "error": error if not is_sql_valid else None,
                 "reasoning_status": reasoning_status,
+                "identify_concept_reason": identify_concept_reason,
+                "generate_sql_reason": generate_sql_reason,
                 self.usage_metadata_key: usage_metadata,
             }
 

{langchain_timbr-2.1.14 → langchain_timbr-3.0.0}/src/langchain_timbr/langchain/generate_answer_chain.py

@@ -2,6 +2,8 @@ from typing import Optional, Dict, Any
 from langchain.chains.base import Chain
 from langchain.llms.base import LLM
 
+from langchain_timbr.utils.timbr_utils import get_timbr_agent_options
+
 from ..utils.general import to_boolean, validate_timbr_connection_params
 from ..utils.timbr_llm_utils import answer_question
 from ..llm_wrapper.llm_wrapper import LlmWrapper
@@ -19,11 +21,12 @@ class GenerateAnswerChain(Chain):
         llm: Optional[LLM] = None,
         url: Optional[str] = None,
         token: Optional[str] = None,
+        note: Optional[str] = '',
+        agent: Optional[str] = None,
         verify_ssl: Optional[bool] = True,
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
         conn_params: Optional[dict] = None,
-        note: Optional[str] = '',
         debug: Optional[bool] = False,
         **kwargs,
     ):
@@ -31,11 +34,12 @@ class GenerateAnswerChain(Chain):
         :param llm: An LLM instance or a function that takes a prompt string and returns the LLM’s response (optional, will use LlmWrapper with env variables if not provided)
         :param url: Timbr server url (optional, defaults to TIMBR_URL environment variable)
         :param token: Timbr password or token value (optional, defaults to TIMBR_TOKEN environment variable)
+        :param note: Optional additional note to extend our llm prompt
+        :param agent: Optional Timbr agent name for options setup.
         :param verify_ssl: Whether to verify SSL certificates (default is True).
         :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 note: Optional additional note to extend our llm prompt
         
         ## Example
         ```
@@ -79,7 +83,17 @@ class GenerateAnswerChain(Chain):
         self._jwt_tenant_id = jwt_tenant_id
         self._debug = to_boolean(debug)
         self._conn_params = conn_params or {}
-        self._note = note
+
+        self._agent = agent
+        if self._agent:
+            agent_options = get_timbr_agent_options(self._agent, conn_params=self._get_conn_params())
+
+            self._note = agent_options.get("note") if "note" in agent_options else ''
+            if note:
+                self._note = ((self._note + '\n') if self._note else '') + note
+        
+        else:
+            self._note = note
 
 
     @property
@@ -100,7 +114,7 @@ class GenerateAnswerChain(Chain):
         return {
             "url": self._url,
             "token": self._token,
-            # "ontology": self._ontology,
+            "ontology": config.ontology,
             "verify_ssl": self._verify_ssl,
             "is_jwt": self._is_jwt,
             "jwt_tenant_id": self._jwt_tenant_id,

{langchain_timbr-2.1.14 → langchain_timbr-3.0.0}/src/langchain_timbr/langchain/generate_timbr_sql_chain.py

@@ -2,6 +2,8 @@ from typing import Optional, Union, Dict, Any
 from langchain.chains.base import Chain
 from langchain.llms.base import LLM
 
+from langchain_timbr.utils.timbr_utils import get_timbr_agent_options
+
 from ..utils.general import parse_list, to_boolean, to_integer, validate_timbr_connection_params
 from ..utils.timbr_llm_utils import generate_sql
 from ..llm_wrapper.llm_wrapper import LlmWrapper
@@ -15,6 +17,8 @@ class GenerateTimbrSqlChain(Chain):
     against Timbr ontology/knowledge graph databases. It uses an LLM to process prompts and
     connects to Timbr via URL and token for SQL generation.
     """
+
+    _ontology: Optional[str] = None
     
     def __init__(
         self,
@@ -35,6 +39,7 @@ class GenerateTimbrSqlChain(Chain):
         note: Optional[str] = '',
         db_is_case_sensitive: Optional[bool] = False,
         graph_depth: Optional[int] = 1,
+        agent: Optional[str] = None,
         verify_ssl: Optional[bool] = True,
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
@@ -62,6 +67,7 @@ class GenerateTimbrSqlChain(Chain):
         :param note: Optional additional note to extend our llm prompt
         :param db_is_case_sensitive: Whether the database is case sensitive (default is False).
         :param graph_depth: Maximum number of relationship hops to traverse from the source concept during schema exploration (default is 1).
+        :param agent: Optional Timbr agent name for options setup.
         :param verify_ssl: Whether to verify SSL certificates (default is True).
         :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).
@@ -111,31 +117,60 @@ class GenerateTimbrSqlChain(Chain):
         
         self._url = url if url is not None else config.url
         self._token = token if token is not None else config.token
-        self._ontology = ontology if ontology is not None else config.ontology
         
         # Validate required parameters
         validate_timbr_connection_params(self._url, self._token)
         
-        self._schema = schema
-        self._concept = concept
-        self._concepts_list = parse_list(concepts_list)
-        self._views_list = parse_list(views_list)
-        self._include_tags = parse_list(include_tags)
-        self._include_logic_concepts = to_boolean(include_logic_concepts)
-        self._should_validate_sql = to_boolean(should_validate_sql)
-        self._exclude_properties = parse_list(exclude_properties)
-        self._retries = to_integer(retries)
-        self._max_limit = to_integer(max_limit)
-        self._note = note
-        self._db_is_case_sensitive = to_boolean(db_is_case_sensitive)
-        self._graph_depth = to_integer(graph_depth)
         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._max_limit = config.llm_default_limit # use default value so the self._get_conn_params() won't fail before agent options are processed
+
+        self._agent = agent
+        if self._agent:
+            agent_options = get_timbr_agent_options(self._agent, conn_params=self._get_conn_params())
+
+            self._ontology = agent_options.get("ontology") if "ontology" in agent_options else None
+            self._schema = agent_options.get("schema") if "schema" in agent_options else schema
+            self._concept = agent_options.get("concept") if "concept" in agent_options else None
+            self._concepts_list = parse_list(agent_options.get("concepts_list")) if "concepts_list" in agent_options else None
+            self._views_list = parse_list(agent_options.get("views_list")) if "views_list" in agent_options else None
+            self._include_tags = parse_list(agent_options.get("include_tags")) if "include_tags" in agent_options else None
+            self._include_logic_concepts = to_boolean(agent_options.get("include_logic_concepts")) if "include_logic_concepts" in agent_options else False
+            self._exclude_properties = parse_list(agent_options.get("exclude_properties")) if "exclude_properties" in agent_options else ['entity_id', 'entity_type', 'entity_label']
+            self._should_validate_sql = to_boolean(agent_options.get("should_validate_sql")) if "should_validate_sql" in agent_options else config.should_validate_sql
+            self._retries = to_integer(agent_options.get("retries") if "retries" in agent_options else retries)
+            self._max_limit = to_integer(agent_options.get("max_limit")) if "max_limit" in agent_options else config.llm_default_limit
+            self._db_is_case_sensitive = to_boolean(agent_options.get("db_is_case_sensitive")) if "db_is_case_sensitive" in agent_options else False
+            self._graph_depth = to_integer(agent_options.get("graph_depth")) if "graph_depth" in agent_options else 1
+            self._note = agent_options.get("note") if "note" in agent_options else ''
+            if note:
+                self._note = ((self._note + '\n') if self._note else '') + note
+            self._enable_reasoning = to_boolean(agent_options.get("enable_reasoning")) if "enable_reasoning" in agent_options else config.enable_reasoning
+            if enable_reasoning is not None and enable_reasoning != self._enable_reasoning:
+                self._enable_reasoning = to_boolean(enable_reasoning)
+            self._reasoning_steps = to_integer(agent_options.get("reasoning_steps")) if "reasoning_steps" in agent_options else config.reasoning_steps
+            if reasoning_steps is not None and reasoning_steps != self._reasoning_steps:
+                self._reasoning_steps = to_integer(reasoning_steps)
+        else:
+            self._ontology = ontology if ontology is not None else config.ontology
+            self._schema = schema
+            self._concept = concept
+            self._concepts_list = parse_list(concepts_list)
+            self._views_list = parse_list(views_list)
+            self._include_tags = parse_list(include_tags)
+            self._include_logic_concepts = to_boolean(include_logic_concepts)
+            self._exclude_properties = parse_list(exclude_properties)
+            self._should_validate_sql = to_boolean(should_validate_sql)
+            self._retries = to_integer(retries)
+            self._max_limit = to_integer(max_limit)
+            self._db_is_case_sensitive = to_boolean(db_is_case_sensitive)
+            self._graph_depth = to_integer(graph_depth)
+            self._enable_reasoning = to_boolean(enable_reasoning)
+            self._reasoning_steps = to_integer(reasoning_steps)
+            self._note = note
 
 
     @property
@@ -163,7 +198,7 @@ class GenerateTimbrSqlChain(Chain):
         return {
             "url": self._url,
             "token": self._token,
-            "ontology": self._ontology,
+            "ontology": self._ontology if self._ontology is not None else config.ontology,
             "verify_ssl": self._verify_ssl,
             "is_jwt": self._is_jwt,
             "jwt_tenant_id": self._jwt_tenant_id,
@@ -206,6 +241,8 @@ class GenerateTimbrSqlChain(Chain):
             "concept": concept,
             "is_sql_valid": generate_res.get("is_sql_valid"),
             "error": generate_res.get("error"),
+            "identify_concept_reason": generate_res.get("identify_concept_reason"),
+            "generate_sql_reason": generate_res.get("generate_sql_reason"),
             "reasoning_status": generate_res.get("reasoning_status"),
             self.usage_metadata_key: generate_res.get("usage_metadata"),
         }

{langchain_timbr-2.1.14 → langchain_timbr-3.0.0}/src/langchain_timbr/langchain/identify_concept_chain.py

@@ -2,6 +2,8 @@ from typing import Optional, Union, Dict, Any
 from langchain.chains.base import Chain
 from langchain.llms.base import LLM
 
+from langchain_timbr.utils.timbr_utils import get_timbr_agent_options
+
 from ..utils.general import parse_list, to_boolean, to_integer, validate_timbr_connection_params
 from ..utils.timbr_llm_utils import determine_concept
 from ..llm_wrapper.llm_wrapper import LlmWrapper
@@ -16,6 +18,8 @@ class IdentifyTimbrConceptChain(Chain):
     within a Timbr ontology/knowledge graph that best matches the user's intent. It uses an LLM
     to process prompts and connects to Timbr via URL and token for concept identification.
     """
+
+    _ontology: Optional[str] = None
     
     def __init__(
         self,
@@ -30,6 +34,7 @@ class IdentifyTimbrConceptChain(Chain):
         should_validate: Optional[bool] = False,
         retries: Optional[int] = 3,
         note: Optional[str] = '',
+        agent: Optional[str] = None,
         verify_ssl: Optional[bool] = True,
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
@@ -49,6 +54,7 @@ class IdentifyTimbrConceptChain(Chain):
         :param should_validate: Whether to validate the identified concept before returning it
         :param retries: Number of retry attempts if the identified concept is invalid
         :param note: Optional additional note to extend our llm prompt
+        :param agent: Optional Timbr agent name for options setup.
         :param verify_ssl: Whether to verify SSL certificates (default is True).
         :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).
@@ -93,24 +99,40 @@ class IdentifyTimbrConceptChain(Chain):
         
         self._url = url if url is not None else config.url
         self._token = token if token is not None else config.token
-        self._ontology = ontology if ontology is not None else config.ontology
         
         # Validate required parameters
         validate_timbr_connection_params(self._url, self._token)
         
-        self._concepts_list = parse_list(concepts_list)
-        self._views_list = parse_list(views_list)
-        self._include_logic_concepts = to_boolean(include_logic_concepts)
-        self._include_tags = parse_list(include_tags)
-        self._should_validate = to_boolean(should_validate)
-        self._retries = to_integer(retries)
-        self._note = note
         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._agent = agent
+        if self._agent:
+            agent_options = get_timbr_agent_options(self._agent, conn_params=self._get_conn_params())
+
+            self._ontology = agent_options.get("ontology") if "ontology" in agent_options else None
+            self._concepts_list = parse_list(agent_options.get("concepts_list")) if "concepts_list" in agent_options else None
+            self._views_list = parse_list(agent_options.get("views_list")) if "views_list" in agent_options else None
+            self._include_logic_concepts = to_boolean(agent_options.get("include_logic_concepts")) if "include_logic_concepts" in agent_options else False
+            self._include_tags = parse_list(agent_options.get("include_tags")) if "include_tags" in agent_options else None
+            self._should_validate = to_boolean(agent_options.get("should_validate")) if "should_validate" in agent_options else False
+            self._retries = to_integer(agent_options.get("retries") if "retries" in agent_options else retries)
+            self._note = agent_options.get("note") if "note" in agent_options else ''
+            if note:
+                self._note = ((self._note + '\n') if self._note else '') + note
+        else:
+            self._ontology = ontology if ontology is not None else config.ontology
+            self._concepts_list = parse_list(concepts_list)
+            self._views_list = parse_list(views_list)
+            self._include_logic_concepts = to_boolean(include_logic_concepts)
+            self._include_tags = parse_list(include_tags)
+            self._should_validate = to_boolean(should_validate)
+            self._retries = to_integer(retries)
+            self._note = note
+        
 
     @property
     def usage_metadata_key(self) -> str:
@@ -131,7 +153,7 @@ class IdentifyTimbrConceptChain(Chain):
         return {
             "url": self._url,
             "token": self._token,
-            "ontology": self._ontology,
+            "ontology": self._ontology if self._ontology is not None else config.ontology,
             "verify_ssl": self._verify_ssl,
             "is_jwt": self._is_jwt,
             "jwt_tenant_id": self._jwt_tenant_id,

{langchain_timbr-2.1.14 → langchain_timbr-3.0.0}/src/langchain_timbr/langchain/timbr_sql_agent.py

@@ -31,6 +31,7 @@ class TimbrSqlAgent(BaseSingleActionAgent):
         note: Optional[str] = '',
         db_is_case_sensitive: Optional[bool] = False,
         graph_depth: Optional[int] = 1,
+        agent: Optional[str] = None,
         verify_ssl: Optional[bool] = True,
         is_jwt: Optional[bool] = False,
         jwt_tenant_id: Optional[str] = None,
@@ -60,6 +61,7 @@ class TimbrSqlAgent(BaseSingleActionAgent):
         :param note: Optional additional note to extend our llm prompt
         :param db_is_case_sensitive: Whether the database is case sensitive (default is False).
         :param graph_depth: Maximum number of relationship hops to traverse from the source concept during schema exploration (default is 1).
+        :param agent: Optional Timbr agent name for options setup.
         :param verify_ssl: Whether to verify SSL certificates (default is True).
         :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).
@@ -114,6 +116,7 @@ class TimbrSqlAgent(BaseSingleActionAgent):
             note=note,
             db_is_case_sensitive=to_boolean(db_is_case_sensitive),
             graph_depth=to_integer(graph_depth),
+            agent=agent,
             verify_ssl=to_boolean(verify_ssl),
             is_jwt=to_boolean(is_jwt),
             jwt_tenant_id=jwt_tenant_id,
@@ -129,11 +132,12 @@ class TimbrSqlAgent(BaseSingleActionAgent):
             llm=llm,
             url=url,
             token=token,
+            note=note,
+            agent=agent,
             verify_ssl=to_boolean(verify_ssl),
             is_jwt=to_boolean(is_jwt),
             jwt_tenant_id=jwt_tenant_id,
             conn_params=conn_params,
-            note=note,
             debug=to_boolean(debug),
         ) if self._generate_answer else None
 
@@ -181,6 +185,8 @@ class TimbrSqlAgent(BaseSingleActionAgent):
                     "schema": None,
                     "concept": None,
                     "reasoning_status": None,
+                    "identify_concept_reason": None,
+                    "generate_sql_reason": None,
                     "usage_metadata": {},
                 },
                 log="Empty input received"
@@ -210,6 +216,8 @@ class TimbrSqlAgent(BaseSingleActionAgent):
                     "error": result.get("error", None),
                     "reasoning_status": result.get("reasoning_status", None),
                     "usage_metadata": usage_metadata,
+                    "identify_concept_reason": None,
+                    "generate_sql_reason": None,
                 },
                 log=f"Successfully executed query on concept: {result.get('concept', '')}"
             )
@@ -224,6 +232,8 @@ class TimbrSqlAgent(BaseSingleActionAgent):
                     "schema": None,
                     "concept": None,
                     "reasoning_status": None,
+                    "identify_concept_reason": None,
+                    "generate_sql_reason": None,
                     "usage_metadata": {},
                 },
                 log=error_context
@@ -245,6 +255,8 @@ class TimbrSqlAgent(BaseSingleActionAgent):
                     "schema": None,
                     "concept": None,
                     "reasoning_status": None,
+                    "identify_concept_reason": None,
+                    "generate_sql_reason": None,
                     "usage_metadata": {},
                 },
                 log="Empty or whitespace-only input received"
@@ -286,6 +298,8 @@ class TimbrSqlAgent(BaseSingleActionAgent):
                     "concept": result.get("concept", ""),
                     "error": result.get("error", None),
                     "reasoning_status": result.get("reasoning_status", None),
+                    "identify_concept_reason": result.get("identify_concept_reason", None),
+                    "generate_sql_reason": result.get("generate_sql_reason", None),
                     "usage_metadata": usage_metadata,
                 },
                 log=f"Successfully executed query on concept: {result.get('concept', '')}"
@@ -301,6 +315,8 @@ class TimbrSqlAgent(BaseSingleActionAgent):
                     "schema": None,
                     "concept": None,
                     "reasoning_status": None,
+                    "identify_concept_reason": None,
+                    "generate_sql_reason": None,
                     "usage_metadata": {},
                 },
                 log=error_context
@@ -341,6 +357,7 @@ def create_timbr_sql_agent(
     note: Optional[str] = '',
     db_is_case_sensitive: Optional[bool] = False,
     graph_depth: Optional[int] = 1,
+    agent: Optional[str] = None,
     verify_ssl: Optional[bool] = True,
     is_jwt: Optional[bool] = False,
     jwt_tenant_id: Optional[str] = None,
@@ -372,6 +389,7 @@ def create_timbr_sql_agent(
     :param note: Optional additional note to extend our llm prompt
     :param db_is_case_sensitive: Whether the database is case sensitive (default is False).
     :param graph_depth: Maximum number of relationship hops to traverse from the source concept during schema exploration (default is 1).
+    :param agent: Optional Timbr agent name for options setup.
     :param verify_ssl: Whether to verify SSL certificates (default is True).
     :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).
@@ -440,6 +458,7 @@ def create_timbr_sql_agent(
         note=note,
         db_is_case_sensitive=db_is_case_sensitive,
         graph_depth=graph_depth,
+        agent=agent,
         verify_ssl=verify_ssl,
         is_jwt=is_jwt,
         jwt_tenant_id=jwt_tenant_id,