Daita Logo

Focus

The Focus DSL pre-filters tool results before they reach the LLM, reducing token consumption without changing agent behaviour. SQL database plugins push focus clauses directly into the query so the database does the filtering.

#Overview

Every token a tool result sends to the LLM costs money and consumes context window. Wide database tables, verbose API responses, and large JSON payloads force the LLM to process far more data than it actually needs to answer the question.

Focus lets you describe which rows and columns matter. The framework filters the data before the LLM ever sees it.

python
from daita import Agent
from daita.plugins import postgresql
 
db = postgresql(host="localhost", database="analytics", username="user", password="pw")
 
agent = Agent(
    name="Analyst",
    tools=[db],
    focus="status == 'completed' | SELECT order_id, product, amount | LIMIT 100"
)
 
# The LLM receives only completed orders, only 3 columns, capped at 100 rows.
# For SQL plugins, this filter runs inside the database — no full table scan.
await agent.run("What was total revenue from completed orders this month?")

#DSL Syntax

Focus expressions are pipe-delimited strings. All clauses are optional and can appear in any order.

python
[filter] | [SELECT ...] | [ORDER BY ...] | [LIMIT n] | [GROUP BY ...]

#Filter

A Python boolean expression evaluated against each row.

python
"status == 'active'"
"amount > 100 and region == 'EU'"
"level == 'ERROR' or level == 'WARN'"
"refunded == False"
"status in ['pending', 'processing']"
"notes == None"      # translates to IS NULL in SQL

Supported operators: ==, !=, <, <=, >, >=, in, not in, and, or, not.

#SELECT

Project to a subset of columns.

python
"SELECT id, name, amount"
"SELECT order_id, status, region"

#ORDER BY

python
"ORDER BY amount DESC"
"ORDER BY created_at"           # ASC is the default

#LIMIT

python
"LIMIT 50"

#GROUP BY and Aggregates

python
"GROUP BY region | SELECT region, SUM(revenue) AS total"
"GROUP BY status | SELECT status, COUNT(*) AS cnt | ORDER BY cnt DESC"

Supported aggregate functions: SUM, COUNT, AVG, MIN, MAX.

#Combined example

python
focus = "status == 'completed' | SELECT order_id, product, amount | ORDER BY amount DESC | LIMIT 100"

#Applying Focus

#Agent-wide — all tools

python
agent = Agent(
    name="Analyst",
    tools=[db],
    focus="SELECT id, name, status | LIMIT 200",
)

#Per-tool — by tool name

python
agent = Agent(
    name="Analyst",
    tools=[db, slack_plugin],
    focus={
        "postgres_query": "status == 'active' | SELECT id, amount | LIMIT 100",
        "slack_post":     "SELECT channel, text",
    },
)

#On the tool definition

python
from daita import tool
 
@tool(focus="level == 'ERROR' | SELECT timestamp, service, message | LIMIT 50")
def get_logs() -> list:
    ...

#Precedence

When multiple focus sources apply to the same tool:

python
Agent dict focus  >  Agent string focus  >  @tool default  >  no focus

#Applying manually

python
from daita import apply_focus
 
rows = await db.query("SELECT * FROM orders")
focused = apply_focus(rows, "status == 'completed' | SELECT id, amount | LIMIT 100")

#SQL Pushdown

For SQL database plugins (PostgreSQL, MySQL, Snowflake), focus clauses are compiled into the SQL query before it executes. The database filters the data — nothing unnecessary is transferred over the wire.

python
# Without focus — fetches every row, every column
rows = await db.query("SELECT * FROM orders")
 
# With focus — database executes the narrowed query
rows = await db.query(
    "SELECT * FROM orders",
    focus="status == 'completed' | SELECT id, product, amount | LIMIT 100"
)
# Runs: SELECT "id", "product", "amount"
#       FROM (SELECT * FROM orders) _focus_q
#       WHERE "status" = 'completed'
#       LIMIT 100

#Using focus through an agent

Pass a focus string in Agent(focus=...) and the framework injects it automatically:

python
agent = Agent(
    name="Analyst",
    tools=[postgresql(...)],
    focus={"postgres_query": "status == 'completed' | SELECT id, product, amount | LIMIT 100"},
)

Or instruct the LLM to pass it explicitly as a tool argument — the postgres_query, mysql_query, and snowflake_query tools all expose a focus parameter in their schemas.

#What gets pushed down

ClausePushed to SQLNotes
Filter (==, !=, <, >, and, or, not)Yes
Filter with == NoneYesEmits IS NULL
Filter with dot notation (order.status)NoFalls back to Python
SELECTYesColumn names must be simple identifiers
ORDER BYYes
LIMITYes
GROUP BY + aggregatesYesStandard SUM/COUNT/AVG/MIN/MAX

Anything that cannot be expressed in SQL is silently handled by the Python evaluator after the query returns.

#Token reduction

Integration tests on typical wide tables show ~90% reduction in tokens sent to the LLM when focus pushdown is active.

ScenarioWithout focusWith focusReduction
Orders table (15 columns)~572 tokens~49 tokens−91%
Sales table (10 columns)~413 tokens~39 tokens−91%

#Supported Backends

Data typeBackendHow focus is applied
list[dict] / dictPython evaluatorAST-walk filter, Python projection/sort/limit
pandas.DataFramePandas nativedf.query(), column selection, sort_values, head
PostgreSQL / MySQL / SnowflakeSQL compilerFocus compiled into subquery SQL before execution

The correct backend is selected automatically based on the data type.

#Error Handling

Malformed DSL raises FocusDSLError at parse time:

python
from daita import apply_focus
from daita.core.exceptions import FocusDSLError
 
try:
    apply_focus(data, "price >>>")
except FocusDSLError as e:
    print(e)  # Invalid filter expression 'price >>>': invalid syntax

Focus failures on a live tool call log a warning and return the unfiltered result rather than failing the agent run.

#Next Steps