pytrilogy 0.0.3.108__py3-none-any.whl → 0.0.3.109__py3-none-any.whl

{pytrilogy-0.0.3.108.dist-info → pytrilogy-0.0.3.109.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrilogy
-Version: 0.0.3.108
+Version: 0.0.3.109
 Summary: Declarative, typed query language that compiles to SQL.
 Home-page: 
 Author: 
@@ -28,6 +28,8 @@ Provides-Extra: bigquery
 Requires-Dist: sqlalchemy-bigquery; extra == "bigquery"
 Provides-Extra: snowflake
 Requires-Dist: snowflake-sqlalchemy; extra == "snowflake"
+Provides-Extra: ai
+Requires-Dist: httpx; extra == "ai"
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
@@ -113,6 +115,31 @@ ORDER BY
 LIMIT 10;
 ```
 
+## Trilogy is Easy to Write
+For humans *and* AI. Enjoy flexible, one-shot query generation without any DB access or security risks. 
+
+(full code in the python API section.)
+
+```python
+query = text_to_query(
+    executor.environment,
+    "number of flights by month in 2005",
+    Provider.OPENAI,
+    "gpt-5-chat-latest",
+    api_key,
+)
+
+# get a ready to run query
+print(query)
+# typical output
+'''where local.dep_time.year = 2020  
+select
+    local.dep_time.month,
+    count(local.id2) as number_of_flights
+order by
+    local.dep_time.month asc;'''
+```
+
 ## Goals
 
 Versus SQL, Trilogy aims to: 
@@ -264,6 +291,47 @@ for row in results:
         print(x)
 ```
 
+### LLM Usage
+
+Connect to your favorite provider and generate queries with confidence and high accuracy.
+
+```python
+from trilogy import Environment, Dialects
+from trilogy.ai import Provider, text_to_query
+import os
+
+executor = Dialects.DUCK_DB.default_executor(
+    environment=Environment(working_path=Path(__file__).parent)
+)
+
+api_key = os.environ.get(OPENAI_API_KEY)
+if not api_key:
+    raise ValueError("OPENAI_API_KEY required for gpt generation")
+# load a model
+executor.parse_file("flight.preql")
+# create tables in the DB if needed
+executor.execute_file("setup.sql")
+# generate a query
+query = text_to_query(
+    executor.environment,
+    "number of flights by month in 2005",
+    Provider.OPENAI,
+    "gpt-5-chat-latest",
+    api_key,
+)
+
+# print the generated trilogy query
+print(query)
+# run it
+results = executor.execute_text(query)[-1].fetchall()
+assert len(results) == 12
+
+for row in results:
+    # all monthly flights are between 5000 and 7000
+    assert row[1] > 5000 and row[1] < 7000, row
+
+```
+
 ### CLI Usage
 
 Trilogy can be run through a CLI tool, also named 'trilogy'.

{pytrilogy-0.0.3.108.dist-info → pytrilogy-0.0.3.109.dist-info}/RECORD

@@ -1,12 +1,25 @@
-pytrilogy-0.0.3.108.dist-info/licenses/LICENSE.md,sha256=5ZRvtTyCCFwz1THxDTjAu3Lidds9WjPvvzgVwPSYNDo,1042
-trilogy/__init__.py,sha256=G8KCrVGJJPcAMI2euUHspq_x_yiArkE3DddwfS2LspU,304
+pytrilogy-0.0.3.109.dist-info/licenses/LICENSE.md,sha256=5ZRvtTyCCFwz1THxDTjAu3Lidds9WjPvvzgVwPSYNDo,1042
+trilogy/__init__.py,sha256=KT6UoNoE4ZPq_JfCkzB6yZ8a543YyAWsBDGNZxY8LEg,304
 trilogy/constants.py,sha256=g_zkVCNjGop6coZ1kM8eXXAzCnUN22ldx3TYFz0E9sc,1747
 trilogy/engine.py,sha256=3MiADf5MKcmxqiHBuRqiYdsXiLj7oitDfVvXvHrfjkA,2178
-trilogy/executor.py,sha256=KgCAQhHPT-j0rPkBbALX0f84W9-Q-bkjHayGuavg99w,16490
+trilogy/executor.py,sha256=-VeOV0bTGmchHRHpRwFJDyl8FElUxDpwUTUix7hhIFM,17429
 trilogy/parser.py,sha256=o4cfk3j3yhUFoiDKq9ZX_GjBF3dKhDjXEwb63rcBkBM,293
 trilogy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trilogy/render.py,sha256=qQWwduymauOlB517UtM-VGbVe8Cswa4UJub5aGbSO6c,1512
 trilogy/utility.py,sha256=euQccZLKoYBz0LNg5tzLlvv2YHvXh9HArnYp1V3uXsM,763
+trilogy/ai/__init__.py,sha256=H6gpzScruX2xgZNRDMjQ31Wy45irJbdebX1fU_gOwI8,581
+trilogy/ai/constants.py,sha256=Aj-_mFqskcXqIlBjX_A9eqH0V9M8mqX3uJwUhr9puak,5064
+trilogy/ai/conversation.py,sha256=I11xmUZikuKmh-W-jt38OvtyhpHwhpQ6Eeut6dkjI-c,3467
+trilogy/ai/enums.py,sha256=vghPPx0W-DioQSgq4T0MGL-8ekFh6O6d52dHo7KsKtg,118
+trilogy/ai/execute.py,sha256=DTARZxm_btCJq4Yd_jPRHJAcbsMLbjEsjR7KKyKBkTI,1335
+trilogy/ai/models.py,sha256=Au4QnTIlv7e-p3XgTJYZqTSndPMGRIbOvCUWlekE81A,683
+trilogy/ai/prompts.py,sha256=Uag0DJcKs7QWFGX7I3QFSm9o_4oYgASFyhNm4SJncVA,1788
+trilogy/ai/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trilogy/ai/providers/anthropic.py,sha256=Wj2kEmz2CPuCdgUAqC8mYYrqaICTknnVN4QukTkr8tQ,4036
+trilogy/ai/providers/base.py,sha256=PgrD3y9-S42GAfyZUm8cNLgHQx7Wew_kCcVj9WKoImo,693
+trilogy/ai/providers/google.py,sha256=WnAqD84pLPMs5iAgjEOX8BpxowRCzJNEbxPyc_c_AtE,5252
+trilogy/ai/providers/openai.py,sha256=_lhY795q6XMKSyh4pAskQ8Ft2fMgD8tDWWhwlPh5FB0,3273
+trilogy/ai/providers/utils.py,sha256=yttP6y2E_XzdytBCwhaKekfXfxM6gE6MRce4AtyLL60,2047
 trilogy/authoring/__init__.py,sha256=TABMOETSMERrWuyDLR0nK4ISlqR0yaqeXrmuOdrSvAY,3060
 trilogy/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trilogy/core/constants.py,sha256=nizWYDCJQ1bigQMtkNIEMNTcN0NoEAXiIHLzpelxQ24,201
@@ -119,8 +132,8 @@ trilogy/std/money.preql,sha256=XWwvAV3WxBsHX9zfptoYRnBigcfYwrYtBHXTME0xJuQ,2082
 trilogy/std/net.preql,sha256=WZCuvH87_rZntZiuGJMmBDMVKkdhTtxeHOkrXNwJ1EE,416
 trilogy/std/ranking.preql,sha256=LDoZrYyz4g3xsII9XwXfmstZD-_92i1Eox1UqkBIfi8,83
 trilogy/std/report.preql,sha256=LbV-XlHdfw0jgnQ8pV7acG95xrd1-p65fVpiIc-S7W4,202
-pytrilogy-0.0.3.108.dist-info/METADATA,sha256=E94F8AfVcTrL90hRjztXep11eyghshWEcY6Kg6_NDwg,11839
-pytrilogy-0.0.3.108.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pytrilogy-0.0.3.108.dist-info/entry_points.txt,sha256=ewBPU2vLnVexZVnB-NrVj-p3E-4vukg83Zk8A55Wp2w,56
-pytrilogy-0.0.3.108.dist-info/top_level.txt,sha256=cAy__NW_eMAa_yT9UnUNlZLFfxcg6eimUAZ184cdNiE,8
-pytrilogy-0.0.3.108.dist-info/RECORD,,
+pytrilogy-0.0.3.109.dist-info/METADATA,sha256=U_r100YWYUQoWKW48qdPDL2eZVxvDOia7fKkfOOiK3I,13460
+pytrilogy-0.0.3.109.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pytrilogy-0.0.3.109.dist-info/entry_points.txt,sha256=ewBPU2vLnVexZVnB-NrVj-p3E-4vukg83Zk8A55Wp2w,56
+pytrilogy-0.0.3.109.dist-info/top_level.txt,sha256=cAy__NW_eMAa_yT9UnUNlZLFfxcg6eimUAZ184cdNiE,8
+pytrilogy-0.0.3.109.dist-info/RECORD,,

trilogy/__init__.py

@@ -4,6 +4,6 @@ from trilogy.dialect.enums import Dialects
 from trilogy.executor import Executor
 from trilogy.parser import parse
 
-__version__ = "0.0.3.108"
+__version__ = "0.0.3.109"
 
 __all__ = ["parse", "Executor", "Dialects", "Environment", "CONFIG"]

trilogy/ai/__init__.py

@@ -0,0 +1,19 @@
+from trilogy.ai.conversation import Conversation
+from trilogy.ai.enums import Provider
+from trilogy.ai.execute import text_to_query
+from trilogy.ai.models import LLMMessage
+from trilogy.ai.prompts import create_query_prompt
+from trilogy.ai.providers.anthropic import AnthropicProvider
+from trilogy.ai.providers.google import GoogleProvider
+from trilogy.ai.providers.openai import OpenAIProvider
+
+__all__ = [
+    "Conversation",
+    "LLMMessage",
+    "OpenAIProvider",
+    "GoogleProvider",
+    "AnthropicProvider",
+    "create_query_prompt",
+    "text_to_query",
+    "Provider",
+]

trilogy/ai/constants.py

@@ -0,0 +1,92 @@
+from trilogy.core.enums import FunctionClass, FunctionType
+from trilogy.core.functions import FUNCTION_REGISTRY
+
+RULE_PROMPT = """Trilogy statements define a semantic model or query. If a user is asking for data, they want a SELECT.
+Semantic model statements:
+- import <> imports a model to reuse. The output of imports will be visible in fields available to use.
+- key|property|auto|metric defines fields locally. The output will also be visible in fields available to use, so you generally don't need to edit these unless requested.
+- datasource statements define a datasource, which is a mapping of fields to a SQL database table. The left side is the SQL column name, the right side is the field name.
+
+SELECT RULES:
+- No FROM, JOIN, GROUP BY, SUB SELECTS, DISTINCT, UNION, or SELECT *.
+- All fields exist in a global namespace; field paths look like `order.product.id`. Always use the full path. NEVER include a from clause.
+- If a field has a grain defined, and that grain is not in the query output, aggregate it to get desired result. 
+- If a field has a 'alias_for' defined, it is shorthand for that calculation. Use the field name instead of the calculation in your query to be concise. 
+- Newly created fields at the output of the select must be aliased with as (e.g. `sum(births) as all_births`). 
+- Aliases cannot happen inside calculations or in the where/having/order clause. Never alias fields with existing names. 'sum(revenue) as total_revenue' is valid, but '(sum(births) as total_revenue) +1 as revenue_plus_one' is not.
+- Implicit grouping: NEVER include a group by clause. Grouping is by non-aggregated fields in the SELECT clause.
+- You can dynamically group inline to get groups at different grains - ex:  `sum(metric) by dim1, dim2 as sum_by_dim1_dm2` for alternate grouping. If you are grouping a defined aggregate
+- Count must specify a field (no `count(*)`) Counts are automatically deduplicated. Do not ever use DISTINCT.
+- Since there are no underlying tables, sum/count of a constant should always specify a grain field (e.g. `sum(1) by x as count`). 
+- Aggregates in SELECT must be filtered via HAVING. Use WHERE for pre-aggregation filters.
+- Use `field ? condition` for inline filters (e.g. `sum(x ? x > 0)`).
+- Always use a reasonable `LIMIT` for final queries unless the request is for a time series or line chart.
+- Window functions: `rank entity [optional over group] by field desc` (e.g. `rank name over state by sum(births) desc as top_name`) Do not use parentheses for over.
+- Functions. All function names have parenthese (e.g. `sum(births)`, `date_part('year', dep_time)`). For no arguments, use empty parentheses (e.g. `current_date()`).
+- For lag/lead, offset is first: lag/lead offset field order by expr asc/desc.
+- For lag/lead with a window clause: lag/lead offset field by window_clause order by expr asc/desc.
+- Use `::type` casting, e.g., `"2020-01-01"::date`.
+- Date_parts have no quotes; use `date_part(order_date, year)` instead of `date_part(order_date, 'year')`.
+- Comments use `#` only, per line.
+- Two example queries: "where year between 1940 and 1950
+  select
+      name,
+      state,
+      sum(births) AS all_births,
+      sum(births ? state = 'VT') AS vermont_births,
+      rank name over state by all_births desc AS state_rank,
+      rank name by sum(births) by name desc AS all_rank
+  having 
+      all_rank<11
+      and state = 'ID'
+  order by 
+    all_rank asc
+    limit 5;", "where dep_time between '2002-01-01'::datetime and '2010-01-31'::datetime
+  select
+      carrier.name,
+      count(id2) AS total_flights,
+      total_flights / date_diff(min(dep_time.date), max(dep_time.date), DAY) AS average_daily_flights
+  order by 
+    total_flights desc;"""
+
+
+def render_function(function_type: FunctionType, example: str | None = None):
+    info = FUNCTION_REGISTRY[function_type]
+
+    if info.arg_count == -1:
+        # Infinite/variable number of arguments
+        base = f"{function_type.value}(<arg1>, <arg2>, ..., <argN>)"
+    elif info.arg_count == 0:
+        # No arguments
+        base = f"{function_type.value}()"
+    else:
+        # Fixed number of arguments
+        base = f"{function_type.value}({', '.join([f'<arg{p}>' for p in range(1, info.arg_count + 1)])})"
+
+    if example:
+        base += f" e.g. {example}"
+    return base
+
+
+FUNCTION_EXAMPLES = {
+    FunctionType.DATE_ADD: "date_add('2020-01-01'::date, month, 1)",
+    FunctionType.DATE_DIFF: "date_diff('2020-01-01'::date, '2020-01-02'::date, day)",
+    FunctionType.DATE_PART: "date_part('2020-01-01'::date, year)",
+    FunctionType.DATE_SUB: "date_sub('2020-01-01'::date, day, 1)",
+    FunctionType.DATE_TRUNCATE: "date_trunc('2020-01-01'::date, month)",
+    FunctionType.CURRENT_TIMESTAMP: "now()",
+}
+
+FUNCTIONS = "\n".join(
+    [
+        render_function(v, example=FUNCTION_EXAMPLES.get(v))
+        for x, v in FunctionType.__members__.items()
+        if v in FUNCTION_REGISTRY
+    ]
+)
+
+AGGREGATE_FUNCTIONS = [
+    x
+    for x, info in FunctionType.__members__.items()
+    if x in FunctionClass.AGGREGATE_FUNCTIONS.value
+]

trilogy/ai/conversation.py

@@ -0,0 +1,99 @@
+from dataclasses import dataclass
+from typing import Literal, Union
+
+from trilogy import Environment
+from trilogy.ai.models import LLMMessage, LLMRequestOptions
+from trilogy.ai.prompts import TRILOGY_LEAD_IN, create_query_prompt
+from trilogy.ai.providers.base import LLMProvider
+from trilogy.core.exceptions import (
+    InvalidSyntaxException,
+    NoDatasourceException,
+    UndefinedConceptException,
+    UnresolvableQueryException,
+)
+from trilogy.core.query_processor import process_query
+
+
+@dataclass
+class Conversation:
+
+    messages: list[LLMMessage]
+    provider: LLMProvider
+    id: str | None = None
+
+    @classmethod
+    def create(
+        cls,
+        provider: LLMProvider,
+        model_prompt: str = TRILOGY_LEAD_IN,
+        id: str | None = None,
+    ) -> "Conversation":
+        system_message = LLMMessage(role="system", content=model_prompt)
+        messages = [system_message]
+        return cls(id=id, messages=messages, provider=provider)
+
+    def add_message(
+        self,
+        message: Union[LLMMessage, str],
+        role: Literal["user", "assistant"] = "user",
+    ) -> None:
+        """
+        Add a message to the conversation.
+
+        Args:
+            message: Either an LLMMessage object or a string content
+            role: The role for the message if a string is provided (default: 'user')
+        """
+        if isinstance(message, str):
+            message = LLMMessage(role=role, content=message)
+        self.messages.append(message)
+
+    def get_response(self) -> LLMMessage:
+        options = LLMRequestOptions()
+        response = self.provider.generate_completion(options, history=self.messages)
+        response_message = LLMMessage(role="assistant", content=response.text)
+        self.add_message(response_message)
+        return response_message
+
+    def extract_response(self, content: str) -> str:
+        # get contents in triple backticks
+        content = content.replace('"""', "```")
+        if "```" in content:
+            parts = content.split("```")
+            if len(parts) >= 3:
+                return parts[1].strip()
+        return content
+
+    def generate_query(
+        self, user_input: str, environment: Environment, attempts: int = 4
+    ) -> str:
+        attempts = 0
+        self.add_message(create_query_prompt(user_input, environment), role="user")
+        e = None
+        while attempts < 4:
+            attempts += 1
+
+            response_message = self.get_response()
+            response = self.extract_response(response_message.content)
+            if not response.strip()[-1] == ";":
+                response += ";"
+            try:
+                env, raw = environment.parse(response)
+                process_query(statement=raw[-1], environment=environment)
+                return response
+            except (
+                InvalidSyntaxException,
+                NoDatasourceException,
+                UnresolvableQueryException,
+                UndefinedConceptException,
+                SyntaxError,
+            ) as e2:
+                e = e2
+                self.add_message(
+                    f"The previous response could not be parsed due to the error: {str(e)}. Please generate a new query with the issues fixed. Use the same response format.",
+                    role="user",
+                )
+
+        raise Exception(
+            f"Failed to generate a valid query after {attempts} attempts. Last error: {str(e)}. Full conversation: {self.messages}"
+        )

trilogy/ai/enums.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class Provider(Enum):
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"

trilogy/ai/execute.py

@@ -0,0 +1,50 @@
+from trilogy import Environment
+from trilogy.ai.conversation import Conversation
+from trilogy.ai.enums import Provider
+from trilogy.ai.providers.base import LLMProvider
+
+
+def text_to_query(
+    environment: Environment,
+    user_input: str,
+    provider: Provider,
+    model: str,
+    secret: str | None = None,
+) -> str:
+    llm_provider: LLMProvider
+
+    if provider == Provider.OPENAI:
+        from trilogy.ai.providers.openai import OpenAIProvider
+
+        llm_provider = OpenAIProvider(
+            name="openai",
+            api_key=secret,
+            model=model,
+        )
+    elif provider == Provider.ANTHROPIC:
+        from trilogy.ai.providers.anthropic import AnthropicProvider
+
+        llm_provider = AnthropicProvider(
+            name="anthropic",
+            api_key=secret,
+            model=model,
+        )
+    elif provider == Provider.GOOGLE:
+        from trilogy.ai.providers.google import GoogleProvider
+
+        llm_provider = GoogleProvider(
+            name="google",
+            api_key=secret,
+            model=model,
+        )
+    else:
+        raise ValueError(f"Unsupported provider: {provider}")
+    conversation = Conversation.create(
+        provider=llm_provider,
+    )
+
+    response = conversation.generate_query(
+        user_input=user_input, environment=environment
+    )
+
+    return response

trilogy/ai/models.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+
+@dataclass
+class UsageDict:
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+@dataclass
+class LLMResponse:
+    text: str
+    usage: UsageDict
+
+
+@dataclass
+class LLMRequestOptions:
+    max_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    top_p: Optional[float] = None
+
+
+@dataclass
+class LLMMessage:
+    role: Literal["user", "assistant", "system"]
+    content: str
+    model_info: Optional[dict] = None
+    hidden: bool = False  # Used to hide messages in the UI
+
+    def __post_init__(self):
+        if self.model_info is None:
+            self.model_info = {}

trilogy/ai/prompts.py

@@ -0,0 +1,30 @@
+from trilogy import Environment
+from trilogy.ai.constants import AGGREGATE_FUNCTIONS, FUNCTIONS, RULE_PROMPT
+from trilogy.authoring import Concept, DataType
+
+TRILOGY_LEAD_IN = f'''You are a world-class expert in Trilogy, a SQL inspired language with similar syntax and a built in semantic layer. Use the following syntax description to help answer whatever questions they have. Often, they will be asking you to generate a query for them.
+
+Key Trilogy Syntax Rules:
+{RULE_PROMPT}
+
+Aggregate Functions:
+{AGGREGATE_FUNCTIONS}
+
+Functions:  
+{FUNCTIONS}
+
+Valid types:  
+{[x.value for x in DataType]}
+
+For any response to the user, use this format -> put your actual response within triple double quotes with thinking and justification before it, in this format (replace placeholders with relevant content): Reasoning: {{reasoning}} """{{response}}"""
+'''
+
+
+def concepts_to_fields_prompt(concepts: list[Concept]) -> str:
+    return ", ".join([f"[name: {c.address} | type: {c.datatype}" for c in concepts])
+
+
+def create_query_prompt(query: str, environment: Environment) -> str:
+    fields = concepts_to_fields_prompt(list(environment.concepts.values()))
+    return f'''
+Using these base and aliased calculations, derivations thereof created with valid Trilogy, and any extra context you have: {fields}, create the best valid Trilogy query to answer the following user input: "{query}" Return the query within triple double quotes with your thinking and justification before it, so of this form as a jinja template: Reasoning: {{reasoning_placeholder}} """{{trilogy}}""". Example: Because the user asked for sales by year, and revenue is the best sales related field available, we can aggregate revenue by year: """SELECT order.year, sum(revenue) as year_revenue order by order.year asc;"""'''

trilogy/ai/providers/anthropic.py

@@ -0,0 +1,105 @@
+from os import environ
+from typing import List, Optional
+
+from trilogy.ai.enums import Provider
+from trilogy.ai.models import LLMMessage, LLMResponse, UsageDict
+
+from .base import LLMProvider, LLMRequestOptions
+from .utils import RetryOptions, fetch_with_retry
+
+DEFAULT_MAX_TOKENS = 10000
+
+
+class AnthropicProvider(LLMProvider):
+    def __init__(
+        self,
+        name: str,
+        model: str,
+        api_key: str | None = None,
+        retry_options: Optional[RetryOptions] = None,
+    ):
+        api_key = api_key or environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "API key argument or environment variable ANTHROPIC_API_KEY is required"
+            )
+        super().__init__(name, api_key, model, Provider.ANTHROPIC)
+        self.base_completion_url = "https://api.anthropic.com/v1/messages"
+        self.base_model_url = "https://api.anthropic.com/v1/models"
+        self.models: List[str] = []
+        self.type = Provider.ANTHROPIC
+        self.retry_options = retry_options or RetryOptions(
+            max_retries=5,
+            initial_delay_ms=5000,
+            retry_status_codes=[429, 500, 502, 503, 504],
+            on_retry=lambda attempt, delay_ms, error: print(
+                f"Anthropic API retry attempt {attempt} after {delay_ms}ms delay due to error: {str(error)}"
+            ),
+        )
+
+    def generate_completion(
+        self, options: LLMRequestOptions, history: List[LLMMessage]
+    ) -> LLMResponse:
+        try:
+            import httpx
+        except ImportError:
+            raise ImportError(
+                "Missing httpx. Install pytrilogy[ai] to use AnthropicProvider."
+            )
+
+        # Separate system messages from user/assistant messages
+        system_messages = [msg.content for msg in history if msg.role == "system"]
+        conversation_messages = [
+            {"role": msg.role, "content": msg.content}
+            for msg in history
+            if msg.role != "system"
+        ]
+
+        try:
+
+            def make_request():
+                with httpx.Client(timeout=60) as client:
+                    payload = {
+                        "model": self.model,
+                        "messages": conversation_messages,
+                        "max_tokens": options.max_tokens or 10000,
+                        # "temperature": options.temperature or 0.7,
+                        # "top_p": options.top_p if hasattr(options, "top_p") else 1.0,
+                    }
+
+                    # Add system parameter if there are system messages
+                    if system_messages:
+                        # Combine multiple system messages with newlines
+                        payload["system"] = "\n\n".join(system_messages)
+
+                    response = client.post(
+                        url=self.base_completion_url,
+                        headers={
+                            "Content-Type": "application/json",
+                            "x-api-key": self.api_key,
+                            "anthropic-version": "2023-06-01",
+                        },
+                        json=payload,
+                    )
+                    response.raise_for_status()
+                    return response.json()
+
+            data = fetch_with_retry(make_request, self.retry_options)
+
+            return LLMResponse(
+                text=data["content"][0]["text"],
+                usage=UsageDict(
+                    prompt_tokens=data["usage"]["input_tokens"],
+                    completion_tokens=data["usage"]["output_tokens"],
+                    total_tokens=data["usage"]["input_tokens"]
+                    + data["usage"]["output_tokens"],
+                ),
+            )
+
+        except httpx.HTTPStatusError as error:
+            error_detail = error.response.text
+            raise Exception(
+                f"Anthropic API error ({error.response.status_code}): {error_detail}"
+            )
+        except Exception as error:
+            raise Exception(f"Anthropic API error: {str(error)}")

trilogy/ai/providers/base.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from trilogy.ai.enums import Provider
+from trilogy.ai.models import LLMMessage, LLMRequestOptions, LLMResponse
+
+
+class LLMProvider(ABC):
+    def __init__(self, name: str, api_key: str, model: str, provider: Provider):
+        self.api_key = api_key
+        self.models: List[str] = []
+        self.name = name
+        self.model = model
+        self.type = provider
+        self.error: Optional[str] = None
+
+    # Abstract method to be implemented by specific providers
+    @abstractmethod
+    def generate_completion(
+        self, options: LLMRequestOptions, history: List[LLMMessage]
+    ) -> LLMResponse:
+        pass

trilogy/ai/providers/google.py

@@ -0,0 +1,142 @@
+from os import environ
+from typing import Any, Dict, List, Optional
+
+from trilogy.ai.enums import Provider
+from trilogy.ai.models import LLMMessage, LLMResponse, UsageDict
+
+from .base import LLMProvider, LLMRequestOptions
+from .utils import RetryOptions, fetch_with_retry
+
+
+class GoogleProvider(LLMProvider):
+    def __init__(
+        self,
+        name: str,
+        model: str,
+        api_key: str | None = None,
+        retry_options: Optional[RetryOptions] = None,
+    ):
+        api_key = api_key or environ.get("GOOGLE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "API key argument or environment variable GOOGLE_API_KEY is required"
+            )
+        super().__init__(name, api_key, model, Provider.GOOGLE)
+        self.base_model_url = "https://generativelanguage.googleapis.com/v1/models"
+        self.base_completion_url = "https://generativelanguage.googleapis.com/v1beta"
+        self.models: List[str] = []
+        self.type = Provider.GOOGLE
+        self.retry_options = retry_options or RetryOptions(
+            max_retries=3,
+            initial_delay_ms=30000,  # 30s default for Google's 429 rate limits
+            retry_status_codes=[429, 500, 502, 503, 504],
+            on_retry=lambda attempt, delay_ms, error: print(
+                f"Google API retry attempt {attempt} after {delay_ms}ms delay due to error: {str(error)}"
+            ),
+        )
+
+    def _convert_to_gemini_history(
+        self, messages: List[LLMMessage]
+    ) -> List[Dict[str, Any]]:
+        """Convert standard message format to Gemini format."""
+        return [
+            {
+                "role": "model" if msg.role == "assistant" else "user",
+                "parts": [{"text": msg.content}],
+            }
+            for msg in messages
+        ]
+
+    def generate_completion(
+        self, options: LLMRequestOptions, history: List[LLMMessage]
+    ) -> LLMResponse:
+        try:
+            import httpx
+        except ImportError:
+            raise ImportError(
+                "Missing httpx. Install pytrilogy[ai] to use GoogleProvider."
+            )
+
+        # Convert messages to Gemini format
+        gemini_history = self._convert_to_gemini_history(history)
+
+        # Separate system message if present
+        system_instruction = None
+        contents = gemini_history
+
+        # Check if first message is a system message
+        if history and history[0].role == "system":
+            system_instruction = {"parts": [{"text": history[0].content}]}
+            contents = gemini_history[1:]  # Remove system message from history
+
+        # Build the request URL
+        url = f"{self.base_completion_url}/models/{self.model}:generateContent"
+
+        # Build request body
+        request_body: Dict[str, Any] = {"contents": contents, "generationConfig": {}}
+
+        # Add system instruction if present
+        if system_instruction:
+            request_body["systemInstruction"] = system_instruction
+
+        # Add generation config options
+        if options.temperature is not None:
+            request_body["generationConfig"]["temperature"] = options.temperature
+
+        if options.max_tokens is not None:
+            request_body["generationConfig"]["maxOutputTokens"] = options.max_tokens
+
+        if options.top_p is not None:
+            request_body["generationConfig"]["topP"] = options.top_p
+
+        try:
+            # Make the API request with retry logic using a lambda
+            response = fetch_with_retry(
+                fetch_fn=lambda: httpx.post(
+                    url,
+                    headers={
+                        "Content-Type": "application/json",
+                        "x-goog-api-key": self.api_key,
+                    },
+                    json=request_body,
+                    timeout=60.0,
+                ),
+                options=self.retry_options,
+            )
+
+            response.raise_for_status()
+            data = response.json()
+
+            # Extract text from response
+            candidates = data.get("candidates", [])
+            if not candidates:
+                raise Exception("No candidates returned from Google API")
+
+            content = candidates[0].get("content", {})
+            parts = content.get("parts", [])
+
+            if not parts:
+                raise Exception("No parts in response content")
+
+            text = parts[0].get("text", "")
+
+            # Extract usage metadata
+            usage_metadata = data.get("usageMetadata", {})
+            prompt_tokens = usage_metadata.get("promptTokenCount", 0)
+            completion_tokens = usage_metadata.get("candidatesTokenCount", 0)
+
+            return LLMResponse(
+                text=text,
+                usage=UsageDict(
+                    prompt_tokens=prompt_tokens,
+                    completion_tokens=completion_tokens,
+                    total_tokens=prompt_tokens + completion_tokens,
+                ),
+            )
+        except httpx.HTTPStatusError as error:
+            error_detail = error.response.text
+            raise Exception(
+                f"Google API error ({error.response.status_code}): {error_detail}"
+            )
+        except Exception as error:
+            raise Exception(f"Google API error: {str(error)}")

trilogy/ai/providers/openai.py

@@ -0,0 +1,88 @@
+from os import environ
+from typing import List, Optional
+
+from trilogy.ai.enums import Provider
+from trilogy.ai.models import LLMMessage, LLMResponse, UsageDict
+
+from .base import LLMProvider, LLMRequestOptions
+from .utils import RetryOptions, fetch_with_retry
+
+
+class OpenAIProvider(LLMProvider):
+    def __init__(
+        self,
+        name: str,
+        model: str,
+        api_key: str | None = None,
+        retry_options: Optional[RetryOptions] = None,
+    ):
+        api_key = api_key or environ.get("OPENAI_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "API key argument or environment variable OPENAI_API_KEY is required"
+            )
+        super().__init__(name, api_key, model, Provider.OPENAI)
+        self.base_completion_url = "https://api.openai.com/v1/chat/completions"
+        self.base_model_url = "https://api.openai.com/v1/models"
+        self.models: List[str] = []
+        self.type = Provider.OPENAI
+
+        self.retry_options = retry_options or RetryOptions(
+            max_retries=3,
+            initial_delay_ms=1000,
+            retry_status_codes=[429, 500, 502, 503, 504],  # Add common API error codes
+            on_retry=lambda attempt, delay_ms, error: print(
+                f"Retry attempt {attempt} after {delay_ms}ms delay due to error: {str(error)}"
+            ),
+        )
+
+    def generate_completion(
+        self, options: LLMRequestOptions, history: List[LLMMessage]
+    ) -> LLMResponse:
+        try:
+            import httpx
+        except ImportError:
+            raise ImportError(
+                "Missing httpx. Install pytrilogy[ai] to use OpenAIProvider."
+            )
+
+        messages: List[dict] = []
+        messages = [{"role": msg.role, "content": msg.content} for msg in history]
+        try:
+
+            def make_request():
+                with httpx.Client(timeout=30) as client:
+                    payload = {
+                        "model": self.model,
+                        "messages": messages,
+                    }
+
+                    response = client.post(
+                        url=self.base_completion_url,
+                        headers={
+                            "Content-Type": "application/json",
+                            "Authorization": f"Bearer {self.api_key}",
+                        },
+                        json=payload,
+                    )
+                    response.raise_for_status()
+                    return response.json()
+
+            data = fetch_with_retry(make_request, self.retry_options)
+            return LLMResponse(
+                text=data["choices"][0]["message"]["content"],
+                usage=UsageDict(
+                    prompt_tokens=data["usage"]["prompt_tokens"],
+                    completion_tokens=data["usage"]["completion_tokens"],
+                    total_tokens=data["usage"]["total_tokens"],
+                ),
+            )
+        except httpx.HTTPStatusError as error:
+            # Capture the response body text
+            error_detail = error.response.text
+            raise Exception(
+                f"OpenAI API error ({error.response.status_code}): {error_detail}"
+            )
+
+        except Exception as error:
+            raise Exception(f"OpenAI API error: {str(error)}")

trilogy/ai/providers/utils.py

@@ -0,0 +1,68 @@
+import time
+from dataclasses import dataclass, field
+from typing import Callable, List, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class RetryOptions:
+    max_retries: int = 3
+    initial_delay_ms: int = 1000
+    retry_status_codes: List[int] = field(
+        default_factory=lambda: [429, 500, 502, 503, 504, 525]
+    )
+    on_retry: Callable[[int, int, Exception], None] | None = None
+
+
+def fetch_with_retry(fetch_fn: Callable[[], T], options: RetryOptions) -> T:
+    from httpx import HTTPError
+
+    """
+    Retry a fetch operation with exponential backoff.
+
+    Args:
+        fetch_fn: Function that performs the fetch operation
+        options: Retry configuration options
+
+    Returns:
+        The result from the successful fetch operation
+
+    Raises:
+        The last exception encountered if all retries fail
+    """
+    from httpx import HTTPStatusError, TimeoutException
+
+    last_error = None
+    delay_ms = options.initial_delay_ms
+
+    for attempt in range(options.max_retries + 1):
+        try:
+            return fetch_fn()
+        except (HTTPError, TimeoutException) as error:
+            last_error = error
+            should_retry = False
+
+            if isinstance(error, HTTPStatusError):
+                if (
+                    options.retry_status_codes
+                    and error.response.status_code in options.retry_status_codes
+                ):
+                    should_retry = True
+            elif isinstance(error, TimeoutException):
+                should_retry = True
+            if not should_retry or attempt >= options.max_retries:
+                raise
+
+            # Call the retry callback if provided
+            if options.on_retry:
+                options.on_retry(attempt + 1, delay_ms, error)
+
+            # Wait before retrying with exponential backoff
+            time.sleep(delay_ms / 1000.0)
+            delay_ms *= 2  # Exponential backoff
+
+    # This should never be reached, but just in case
+    if last_error:
+        raise last_error
+    raise Exception("Retry logic failed unexpectedly")

trilogy/executor.py

@@ -6,7 +6,7 @@ from sqlalchemy import text
 
 from trilogy.constants import MagicConstants, Rendering, logger
 from trilogy.core.enums import FunctionType, Granularity, IOType, ValidationScope
-from trilogy.core.models.author import Concept, Function
+from trilogy.core.models.author import Comment, Concept, Function
 from trilogy.core.models.build import BuildFunction
 from trilogy.core.models.core import ListWrapper, MapWrapper
 from trilogy.core.models.datasource import Datasource
@@ -86,6 +86,10 @@ class Executor(object):
     def execute_query(self, query) -> ResultProtocol | None:
         raise NotImplementedError("Cannot execute type {}".format(type(query)))
 
+    @execute_query.register
+    def _(self, query: Comment) -> ResultProtocol | None:
+        return None
+
     @execute_query.register
     def _(self, query: ConceptDeclarationStatement) -> ResultProtocol | None:
         return handle_concept_declaration(query)
@@ -266,9 +270,22 @@ class Executor(object):
         None,
     ]:
         file = Path(file)
-        with open(file, "r") as f:
-            command = f.read()
-            return self.parse_text_generator(command, persist=persist, root=file)
+        candidates = [file, self.environment.working_path / file]
+        err = None
+        for file in candidates:
+            try:
+                with open(file, "r") as f:
+                    command = f.read()
+                    return self.parse_text_generator(
+                        command, persist=persist, root=file
+                    )
+            except FileNotFoundError as e:
+                if not err:
+                    err = e
+                continue
+        if err:
+            raise err
+        raise FileNotFoundError(f"File {file} not found")
 
     def parse_text(
         self, command: str, persist: bool = False, root: Path | None = None
@@ -440,9 +457,20 @@ class Executor(object):
         self, file: str | Path, non_interactive: bool = False
     ) -> List[ResultProtocol]:
         file = Path(file)
-        with open(file, "r") as f:
-            command = f.read()
-        return self.execute_text(command, non_interactive=non_interactive)
+        candidates = [file, self.environment.working_path / file]
+        err = None
+        for file in candidates:
+            if not file.exists():
+                continue
+            with open(file, "r") as f:
+                command = f.read()
+            if file.suffix == ".sql":
+                return [self.execute_raw_sql(command)]
+            else:
+                return self.execute_text(command, non_interactive=non_interactive)
+        if err:
+            raise err
+        raise FileNotFoundError(f"File {file} not found")
 
     def validate_environment(
         self,