pytrilogy 0.0.3.108__tar.gz → 0.0.3.109__tar.gz

{pytrilogy-0.0.3.108/pytrilogy.egg-info → pytrilogy-0.0.3.109}/PKG-INFO

@@ -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 → pytrilogy-0.0.3.109}/README.md

@@ -74,6 +74,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: 
@@ -225,6 +250,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 → pytrilogy-0.0.3.109/pytrilogy.egg-info}/PKG-INFO

@@ -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 → pytrilogy-0.0.3.109}/pytrilogy.egg-info/SOURCES.txt

@@ -44,6 +44,19 @@ trilogy/parser.py
 trilogy/py.typed
 trilogy/render.py
 trilogy/utility.py
+trilogy/ai/__init__.py
+trilogy/ai/constants.py
+trilogy/ai/conversation.py
+trilogy/ai/enums.py
+trilogy/ai/execute.py
+trilogy/ai/models.py
+trilogy/ai/prompts.py
+trilogy/ai/providers/__init__.py
+trilogy/ai/providers/anthropic.py
+trilogy/ai/providers/base.py
+trilogy/ai/providers/google.py
+trilogy/ai/providers/openai.py
+trilogy/ai/providers/utils.py
 trilogy/authoring/__init__.py
 trilogy/core/__init__.py
 trilogy/core/constants.py

{pytrilogy-0.0.3.108 → pytrilogy-0.0.3.109}/pytrilogy.egg-info/requires.txt

@@ -8,6 +8,9 @@ duckdb<1.4.0
 duckdb-engine
 click
 
+[ai]
+httpx
+
 [bigquery]
 sqlalchemy-bigquery
 

{pytrilogy-0.0.3.108 → pytrilogy-0.0.3.109}/setup.py

@@ -47,6 +47,7 @@ setuptools.setup(
         "postgres": ["psycopg2-binary"],
         "bigquery": ["sqlalchemy-bigquery"],
         "snowflake": ["snowflake-sqlalchemy"],
+        "ai": ["httpx"],
     },
     entry_points={
         "console_scripts": ["trilogy=trilogy.scripts.trilogy:cli"],

{pytrilogy-0.0.3.108 → pytrilogy-0.0.3.109}/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"]

pytrilogy-0.0.3.109/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",
+]

pytrilogy-0.0.3.109/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
+]

pytrilogy-0.0.3.109/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}"
+        )

pytrilogy-0.0.3.109/trilogy/ai/enums.py

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

pytrilogy-0.0.3.109/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

pytrilogy-0.0.3.109/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 = {}

pytrilogy-0.0.3.109/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;"""'''