A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.
feat: add Self-Driving Data Analyst with Liner
Tiioluwani4e5885471f3a
diff --git a/ai_agents/self_driving_data_analyst/.env.example b/ai_agents/self_driving_data_analyst/.env.examplenew file mode 100644index 0000000..8379b35--- /dev/null+++ b/ai_agents/self_driving_data_analyst/.env.example@@ -0,0 +1,2 @@+# Get your API key from https://liner.com/developers+LINER_API_KEY=your_liner_api_key_herediff --git a/ai_agents/self_driving_data_analyst/.gitignore b/ai_agents/self_driving_data_analyst/.gitignorenew file mode 100644index 0000000..4be7df0--- /dev/null+++ b/ai_agents/self_driving_data_analyst/.gitignore@@ -0,0 +1,6 @@+.env+.venv/+__pycache__/+*.pyc+.pytest_cache/+data/ecommerce_demo/*.csv\ No newline at end of filediff --git a/ai_agents/self_driving_data_analyst/README.md b/ai_agents/self_driving_data_analyst/README.mdnew file mode 100644index 0000000..d71553c--- /dev/null+++ b/ai_agents/self_driving_data_analyst/README.md@@ -0,0 +1,156 @@+# Self-Driving Data Analyst with Liner+> An AI agent that investigates a dataset on its own, without requiring the user to guide every step.++## Overview+Give it a dataset and a broad objective, "why did revenue decline?", and it decides what to check, runs the analysis, follows what it finds, and keeps going until it has enough evidence to explain what happened. Built on the Liner Model API (`liner-mark-1.0`), which automatically routes each request to the most cost-efficient underlying model for that request, so a multi-step agent making dozens of calls per investigation isn't paying premium-model prices for the easy steps.++## Demo+++## Features+- Autonomous investigation loop: understand data, choose what to check, run analysis, observe, decide next step, repeat, produce findings+- Hypothesis tracking with status and confidence, updated as evidence comes in+- Parallel tool calls for independent lines of investigation (e.g. checking product, region, and channel at once)+- Error recovery: a failed SQL query becomes an observation the agent reasons over, not a crash+- Loop detection: flags and redirects the agent if it repeats near-identical queries with no new information+- Structured final report (root cause, confidence, key findings, recommended actions) via a dedicated `finish_investigation` tool+- Full usage and cost tracking per investigation, including cached-token savings++## Tech Stack+| Layer | Technology |+|-------|------------|+| LLM | Liner Model API (`liner-mark-1.0`) |+| Agent orchestration | Custom Python investigation loop (`agent/harness.py`) |+| Data processing | Pandas |+| SQL analysis | DuckDB |+| Charts | Plotly |+| UI | Streamlit |+| Structured state | Pydantic |++## Prerequisites+- Python 3.10 or higher+- API keys for:+ - Liner (https://liner.com/developers)++## Installation++### 1. Clone the repository+```bash+git clone https://github.com/Sumanth077/Hands-On-AI-Engineering.git+cd Hands-On-AI-Engineering/ai_agents/self_driving_data_analyst+```++### 2. Create a virtual environment+```bash+python -m venv .venv+```++### 3. Activate the virtual environment++**macOS / Linux**+```bash+source .venv/bin/activate+```++**Windows (PowerShell)**+```powershell+.\.venv\Scripts\Activate.ps1+```++**Windows (Command Prompt)**+```cmd+.venv\Scripts\activate.bat+```++### 4. Install dependencies+```bash+pip install -r requirements.txt+```++### 5. Configure environment variables+```bash+cp .env.example .env+```+Open `.env` and add your Liner API key.++## Environment Variables+| Variable | Description | Where to Get It |+|----------|-------------|------------------|+| LINER_API_KEY | Authenticates requests to the Liner Model API | Liner Developer Dashboard (liner.com/developers) |++## Usage++### Run the app+```bash+python scripts/generate_sample_data.py # generates the demo dataset, first time only+streamlit run app.py+```++### Example objectives+| Objective | What it does |+|-----------|---------------|+| "Why did revenue decline?" | Investigates a specific question end to end |+| "Find the most important patterns in this data" | Autopilot mode, open-ended exploration |+| "Why do returns spike in certain months?" | Works against uploaded real-world datasets too, not just the demo one |++### What the agent returns+A structured report: root cause with a confidence score, key findings with supporting evidence, hypotheses it tested along the way, relevant charts, recommended next steps, and a full usage breakdown (model calls, tool calls, tokens, estimated cost).++## Project Structure++```+self_driving_data_analyst/+├── app.py # Streamlit UI+├── agent/+│ ├── client.py # Liner Model API wrapper+│ ├── harness.py # the investigation loop+│ ├── state.py # Pydantic investigation state+│ ├── prompts.py # system prompt+│ ├── tool_schemas.py # function-calling schemas+│ └── loop_detector.py+├── tools/+│ ├── dataset.py sql.py python_tool.py charts.py findings.py+├── scripts/+│ └── generate_sample_data.py # builds the demo dataset+├── data/ecommerce_demo/ # generated CSVs (git-ignored, regenerate locally)+└── tests/ # runs without a live API key (mocked client)+```+++## How It Works++### The investigation loop++Understand the data -> Choose what to investigate -> Run an analysis ->+Observe the result -> Decide what to investigate next -> Repeat ->+Produce final findings++The result of each step determines the next one. There's no fixed pipeline telling it to check revenue, then orders, then AOV in that order, it decides that itself based on what it finds.++### The tools+| Tool | What it does |+|---|---|+| `inspect_dataset()` | Schema, column types, row counts, sample rows |+| `run_sql(query)` | Runs a DuckDB SQL query, returns rows or an error |+| `run_python(code)` | Runs Python for stats SQL isn't suited for |+| `create_chart(...)` | Renders a Plotly chart locally |+| `save_finding(...)` | Writes a discovery into persistent state |+| `update_hypothesis(...)` | Records a theory and its status (untested/supported/rejected) as evidence comes in |+| `finish_investigation(...)` | Concludes the investigation with a structured root cause, confidence, findings, and recommended actions |++There's no `find_root_cause()` tool, on purpose. That decision has to stay with the model, or the harness is doing the interesting part instead of it.++### State, not just chat history+Raw conversation history isn't enough to reason about a multi-step investigation. `agent/state.py` keeps an explicit `InvestigationState`: findings, hypotheses, tool-call history, and usage. Its `summary_for_prompt()` is what gets re-sent to the model each turn, a compact snapshot, not the full raw history, since older raw tool-call turns get pruned from what's sent while the structured summary carries that context forward instead.++### Failure recovery and loop detection+If a SQL query fails, the error is returned as data, not raised, and the system prompt tells the model to read the error and try again rather than giving up. Separately, if the agent runs near-identical queries repeatedly with no new information, the harness injects a message telling it to reassess.++### Stopping+The model concludes by calling `finish_investigation(...)` with its structured findings. As a fallback, if it ever responds with no further tool calls, that's also treated as a conclusion. Either way, `max_steps` and `max_tool_calls` (both configurable in the sidebar) put a hard ceiling on the loop so it can't run indefinitely.++### Cost visibility+Every response's usage, including cached tokens, is tracked across the whole investigation and shown at the end: steps, model calls, tokens, and an estimated cost using Liner's published `liner-mark-1.0` pricing, what you're actually billed regardless of which underlying model the orchestrator routed any given request to.++### A note on run_python+`run_python` executes model-generated code with a restricted builtins list and no filesystem/network access, a reasonable floor for a local demo but not a real security sandbox. For anything beyond your own machine or a trusted demo, run this tool inside a real sandbox (for example, E2B) instead of in-process.diff --git a/ai_agents/self_driving_data_analyst/agent/__init__.py b/ai_agents/self_driving_data_analyst/agent/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/ai_agents/self_driving_data_analyst/agent/client.py b/ai_agents/self_driving_data_analyst/agent/client.pynew file mode 100644index 0000000..f379c56--- /dev/null+++ b/ai_agents/self_driving_data_analyst/agent/client.py@@ -0,0 +1,107 @@+"""+Minimal client for the Liner Model API.++Liner's Model API is OpenAI Chat Completions-compatible: same request/response+shape, same tool-calling flow. This wrapper only implements the pieces this+project actually uses (chat completions, function calling, reasoning_effort,+usage tracking) rather than pulling in the full OpenAI SDK for one endpoint.+"""++from __future__ import annotations++import json+import os+from dataclasses import dataclass+from typing import Any, Optional++import requests++LINER_BASE_URL = "https://platform.liner.com/api/v1"+LINER_MODEL = "liner-mark-1.0"+++class LinerAPIError(RuntimeError):+ pass+++@dataclass+class LinerResponse:+ raw: dict[str, Any]++ @property+ def message(self) -> dict[str, Any]:+ return self.raw["choices"][0]["message"]++ @property+ def content(self) -> Optional[str]:+ return self.message.get("content")++ @property+ def tool_calls(self) -> list[dict[str, Any]]:+ return self.message.get("tool_calls") or []++ @property+ def usage(self) -> dict[str, Any]:+ return self.raw.get("usage", {})++ @property+ def prompt_tokens(self) -> int:+ return self.usage.get("prompt_tokens", 0)++ @property+ def completion_tokens(self) -> int:+ return self.usage.get("completion_tokens", 0)++ @property+ def cached_tokens(self) -> int:+ details = self.usage.get("prompt_tokens_details") or {}+ return details.get("cached_tokens", 0)+++class LinerClient:+ def __init__(self, api_key: Optional[str] = None, timeout: int = 120):+ self.api_key = api_key or os.environ.get("LINER_API_KEY")+ if not self.api_key:+ raise LinerAPIError(+ "LINER_API_KEY is not set. Add it to your .env file or pass it explicitly."+ )+ self.timeout = timeout++ def chat(+ self,+ messages: list[dict[str, Any]],+ tools: Optional[list[dict[str, Any]]] = None,+ tool_choice: str = "auto",+ reasoning_effort: str = "medium",+ response_format: Optional[dict[str, Any]] = None,+ parallel_tool_calls: bool = True,+ ) -> LinerResponse:+ payload: dict[str, Any] = {+ "model": LINER_MODEL,+ "messages": messages,+ "reasoning_effort": reasoning_effort,+ }+ if tools:+ payload["tools"] = tools+ payload["tool_choice"] = tool_choice+ payload["parallel_tool_calls"] = parallel_tool_calls+ if response_format:+ payload["response_format"] = response_format++ try:+ resp = requests.post(+ f"{LINER_BASE_URL}/chat/completions",+ headers={+ "Authorization": f"Bearer {self.api_key}",+ "Content-Type": "application/json",+ },+ data=json.dumps(payload),+ timeout=self.timeout,+ )+ except requests.RequestException as exc:+ raise LinerAPIError(f"Request to Liner Model API failed: {exc}") from exc++ if resp.status_code >= 400:+ raise LinerAPIError(f"Liner Model API returned {resp.status_code}: {resp.text}")++ return LinerResponse(raw=resp.json())diff --git a/ai_agents/self_driving_data_analyst/agent/harness.py b/ai_agents/self_driving_data_analyst/agent/harness.pynew file mode 100644index 0000000..4c7d82e--- /dev/null+++ b/ai_agents/self_driving_data_analyst/agent/harness.py@@ -0,0 +1,204 @@+"""+The investigation loop itself, this is the actual project.++Understand -> choose what to investigate -> run an analysis -> observe ->+decide what's next -> repeat -> produce final findings. The result of each+tool call determines the next one; nothing here is a fixed pipeline.+"""++from __future__ import annotations++import json+from dataclasses import dataclass, field+from typing import Any, Callable, Iterator++import duckdb+import pandas as pd++from agent.client import LinerClient+from agent.loop_detector import is_looping+from agent.prompts import LOOP_WARNING, SYSTEM_PROMPT+from agent.state import InvestigationState+from agent.tool_schemas import TOOLS+from tools.charts import create_chart+from tools.dataset import inspect_dataset+from tools.findings import save_finding+from tools.python_tool import run_python+from tools.sql import run_sql++DEPTH_TO_REASONING_EFFORT = {+ "Quick": "low",+ "Standard": "medium",+ "Deep": "high",+}+++@dataclass+class InvestigationEvent:+ type: str # "tool_call" | "loop_warning" | "finished" | "budget_exhausted"+ payload: dict[str, Any] = field(default_factory=dict)+++def _prune_messages(messages: list[dict[str, Any]], context_window_turns: int) -> list[dict[str, Any]]:+ """Keeps messages[0] (system) and messages[1] (the original objective)+ always, plus only the most recent `context_window_turns` assistant/tool+ exchanges. Only cuts at assistant-message boundaries so a tool_call_id+ pairing between an assistant's tool_calls and the following tool results+ never gets split."""+ if len(messages) <= 2:+ return messages++ head, tail = messages[:2], messages[2:]+ turn_starts = [i for i, m in enumerate(tail) if m.get("role") == "assistant"]++ if len(turn_starts) <= context_window_turns:+ return messages++ cutoff = turn_starts[-context_window_turns]+ return head + tail[cutoff:]+++class InvestigationHarness:+ def __init__(+ self,+ client: LinerClient,+ con: duckdb.DuckDBPyConnection,+ dataframes: dict[str, pd.DataFrame],+ max_steps: int = 25,+ max_tool_calls: int = 40,+ context_window_turns: int = 6,+ ):+ self.client = client+ self.con = con+ self.dataframes = dataframes+ self.max_steps = max_steps+ self.max_tool_calls = max_tool_calls+ self.context_window_turns = context_window_turns+ self.charts: list[Any] = [] # Plotly figures, kept out of the Pydantic state on purpose++ def _dispatch_tool(self, name: str, arguments: dict, state: InvestigationState) -> dict:+ if name == "inspect_dataset":+ return inspect_dataset(self.con)+ if name == "run_sql":+ return run_sql(self.con, arguments.get("query", ""))+ if name == "run_python":+ return run_python(arguments.get("code", ""), self.dataframes)+ if name == "create_chart":+ result = create_chart(+ rows=arguments.get("rows", []),+ chart_type=arguments.get("chart_type", "bar"),+ x=arguments.get("x"),+ y=arguments.get("y"),+ color=arguments.get("color"),+ title=arguments.get("title"),+ )+ if result.get("success") and "figure" in result:+ self.charts.append(result.pop("figure"))+ result["chart_index"] = len(self.charts) - 1+ return result+ if name == "save_finding":+ return save_finding(+ state,+ finding=arguments.get("finding", ""),+ importance=arguments.get("importance", "medium"),+ evidence=arguments.get("evidence"),+ )+ if name == "update_hypothesis":+ state.upsert_hypothesis(+ hypothesis=arguments.get("hypothesis", ""),+ status=arguments.get("status", "untested"),+ confidence=arguments.get("confidence"),+ evidence=arguments.get("evidence"),+ )+ return {"success": True}+ if name == "finish_investigation":+ state.root_cause = arguments.get("root_cause")+ state.confidence = arguments.get("confidence")+ state.recommended_actions = arguments.get("recommended_actions") or []+ state.final_report = arguments.get("summary_markdown", "")+ return {"success": True}+ return {"success": False, "error": f"Unknown tool '{name}'"}++ def investigate(self, objective: str, depth: str = "Standard") -> Iterator[InvestigationEvent]:+ reasoning_effort = DEPTH_TO_REASONING_EFFORT.get(depth, "medium")+ state = InvestigationState(objective=objective, reasoning_effort=reasoning_effort)++ messages: list[dict[str, Any]] = [+ {"role": "system", "content": SYSTEM_PROMPT.format(state_summary=state.summary_for_prompt())},+ {"role": "user", "content": objective},+ ]++ while True:+ if state.step_count >= self.max_steps or len(state.tool_calls) >= self.max_tool_calls:+ state.is_finished = True+ state.stop_reason = "budget_exhausted"+ state.final_report = (+ "Investigation stopped after reaching the step/tool-call budget "+ "before the agent concluded on its own. Findings and hypotheses "+ "gathered so far are included below."+ )+ yield InvestigationEvent("budget_exhausted", {"state": state})+ return++ # Keep the system message's state summary current every turn.+ messages[0]["content"] = SYSTEM_PROMPT.format(state_summary=state.summary_for_prompt())+ messages = _prune_messages(messages, self.context_window_turns)++ response = self.client.chat(+ messages=messages,+ tools=TOOLS,+ reasoning_effort=reasoning_effort,+ )++ state.step_count += 1+ state.usage.model_calls += 1+ state.usage.prompt_tokens += response.prompt_tokens+ state.usage.completion_tokens += response.completion_tokens+ state.usage.cached_tokens += response.cached_tokens++ if not response.tool_calls:+ state.is_finished = True+ state.stop_reason = "concluded"+ state.final_report = response.content or "(no content returned)"+ yield InvestigationEvent("finished", {"state": state})+ return++ messages.append(response.message)++ for tool_call in response.tool_calls:+ fn_name = tool_call["function"]["name"]+ try:+ fn_args = json.loads(tool_call["function"]["arguments"] or "{}")+ except json.JSONDecodeError:+ fn_args = {}++ result = self._dispatch_tool(fn_name, fn_args, state)+ is_error = isinstance(result, dict) and result.get("success") is False++ record = state.add_tool_call(+ tool_name=fn_name,+ arguments=fn_args,+ result_summary=json.dumps(result, default=str),+ model_call_index=state.step_count,+ is_error=is_error,+ )++ messages.append(+ {+ "role": "tool",+ "tool_call_id": tool_call["id"],+ "content": json.dumps(result, default=str),+ }+ )++ yield InvestigationEvent("tool_call", {"record": record, "state": state})++ if fn_name == "finish_investigation":+ state.is_finished = True+ state.stop_reason = "concluded"+ yield InvestigationEvent("finished", {"state": state})+ return++ if is_looping(state):+ messages.append({"role": "user", "content": LOOP_WARNING})+ yield InvestigationEvent("loop_warning", {"state": state})diff --git a/ai_agents/self_driving_data_analyst/agent/loop_detector.py b/ai_agents/self_driving_data_analyst/agent/loop_detector.pynew file mode 100644index 0000000..612fdd4--- /dev/null+++ b/ai_agents/self_driving_data_analyst/agent/loop_detector.py@@ -0,0 +1,25 @@+"""+Flags when the agent looks stuck: repeating near-identical SQL queries+without making progress. This does not stop the investigation, it injects+a message telling the model to reassess, and lets the model decide what to+do next.+"""++from __future__ import annotations++import re++from agent.state import InvestigationState+++def _normalize(query: str) -> str:+ return re.sub(r"\s+", " ", query.strip().lower())+++def is_looping(state: InvestigationState, window: int = 4, min_repeats: int = 3) -> bool:+ recent = state.recent_sql_queries(n=window)+ if len(recent) < min_repeats:+ return False+ normalized = [_normalize(q) for q in recent]+ most_common = max(set(normalized), key=normalized.count)+ return normalized.count(most_common) >= min_repeatsdiff --git a/ai_agents/self_driving_data_analyst/agent/prompts.py b/ai_agents/self_driving_data_analyst/agent/prompts.pynew file mode 100644index 0000000..51966ee--- /dev/null+++ b/ai_agents/self_driving_data_analyst/agent/prompts.py@@ -0,0 +1,29 @@+SYSTEM_PROMPT = """You are an autonomous data investigator. You have been given a dataset and \+an objective. Your job is to figure out, on your own, what to check, in what \+order, based on what you find along the way. Nobody will tell you which \+table to look at or which column to check next.++How to work:+1. Start by calling inspect_dataset() if you haven't already, so you know what tables and columns actually exist.+2. Pick a reasonable starting point based on the objective, and run a real query or calculation to check it.+3. Look at what came back. Let the result decide your next step: if something looks off or interesting, drill into it; if a lane looks normal, rule it out and move on.+4. Use save_finding() whenever you've confirmed something worth including in the final report, not just for your own scratch reasoning.+5. Call update_hypothesis() as you form, test, and resolve hypotheses about what's actually causing the pattern in the objective: record a new hypothesis as soon as you have one worth naming, and call it again on that same hypothesis to update its status (supported/rejected) and confidence as evidence comes in. Don't just keep it in mind.+6. When run_sql or run_python returns an error, do not give up or restart from scratch. Read the error, call inspect_dataset() again if needed, and correct your approach.+7. Stop investigating and give your final answer once you genuinely have enough evidence to explain what's going on, tracing the specific path that led there. Don't pad the investigation with redundant checks once you have a real answer.++When you're ready to finish, call finish_investigation() to conclude, \+providing the root cause, your confidence in it, the full narrative report, \+key findings, and recommended actions, tracing the specific path that led \+there.++Investigation state so far:+{state_summary}+"""+++LOOP_WARNING = (+ "Potential analysis loop detected: your last few actions produced little "+ "new information. Reassess your current hypothesis and consider a "+ "different analytical direction instead of repeating the same check."+)diff --git a/ai_agents/self_driving_data_analyst/agent/state.py b/ai_agents/self_driving_data_analyst/agent/state.pynew file mode 100644index 0000000..39399b4--- /dev/null+++ b/ai_agents/self_driving_data_analyst/agent/state.py@@ -0,0 +1,155 @@+"""+Persistent investigation state for the Self-Driving Data Analyst.++Raw chat history alone isn't enough for a long-running investigation: the+agent needs an explicit, structured record of what it has found, what it+still suspects, and what it has already tried, so it can reason about the+investigation as a whole rather than just the last message.+"""++from __future__ import annotations++import time+from typing import Literal, Optional++from pydantic import BaseModel, Field+++class Hypothesis(BaseModel):+ hypothesis: str+ status: Literal["untested", "supported", "rejected"] = "untested"+ confidence: Optional[float] = None+ evidence: list[str] = Field(default_factory=list)+++class Finding(BaseModel):+ finding: str+ importance: Literal["low", "medium", "high"] = "medium"+ evidence: list[str] = Field(default_factory=list)+++class ToolCallRecord(BaseModel):+ call_index: int+ model_call_index: int+ tool_name: str+ arguments: dict+ result_summary: str+ is_error: bool = False+ timestamp: float = Field(default_factory=time.time)+++class UsageRecord(BaseModel):+ model_calls: int = 0+ prompt_tokens: int = 0+ completion_tokens: int = 0+ cached_tokens: int = 0++ @property+ def total_tokens(self) -> int:+ return self.prompt_tokens + self.completion_tokens++ def estimated_cost_usd(self) -> float:+ # Liner Model API list pricing for liner-mark-1.0, regardless of which+ # underlying model the orchestrator actually routed the request to.+ uncached_input = max(self.prompt_tokens - self.cached_tokens, 0)+ cost = (+ uncached_input * (1.0 / 1_000_000)+ + self.cached_tokens * (0.10 / 1_000_000)+ + self.completion_tokens * (6.0 / 1_000_000)+ )+ return round(cost, 4)+++class InvestigationState(BaseModel):+ objective: str+ reasoning_effort: str = "medium"++ findings: list[Finding] = Field(default_factory=list)+ hypotheses: list[Hypothesis] = Field(default_factory=list)+ open_questions: list[str] = Field(default_factory=list)+ tool_calls: list[ToolCallRecord] = Field(default_factory=list)++ step_count: int = 0+ is_finished: bool = False+ stop_reason: Optional[str] = None+ final_report: Optional[str] = None+ root_cause: Optional[str] = None+ confidence: Optional[float] = None+ recommended_actions: list[str] = Field(default_factory=list)++ usage: UsageRecord = Field(default_factory=UsageRecord)+ started_at: float = Field(default_factory=time.time)++ # ---- helpers used by the harness ----++ def recent_tool_calls(self, n: int = 6) -> list[ToolCallRecord]:+ return self.tool_calls[-n:]++ def add_tool_call(+ self,+ tool_name: str,+ arguments: dict,+ result_summary: str,+ model_call_index: int = 0,+ is_error: bool = False,+ ) -> ToolCallRecord:+ record = ToolCallRecord(+ call_index=len(self.tool_calls),+ model_call_index=model_call_index,+ tool_name=tool_name,+ arguments=arguments,+ result_summary=result_summary[:800],+ is_error=is_error,+ )+ self.tool_calls.append(record)+ return record++ def add_finding(self, finding: str, importance: str = "medium", evidence: Optional[list[str]] = None) -> None:+ self.findings.append(Finding(finding=finding, importance=importance, evidence=evidence or []))++ def upsert_hypothesis(self, hypothesis: str, status: str = "untested", confidence: Optional[float] = None, evidence: Optional[list[str]] = None) -> None:+ for h in self.hypotheses:+ if h.hypothesis.strip().lower() == hypothesis.strip().lower():+ h.status = status+ h.confidence = confidence+ if evidence:+ h.evidence.extend(evidence)+ return+ self.hypotheses.append(+ Hypothesis(hypothesis=hypothesis, status=status, confidence=confidence, evidence=evidence or [])+ )++ def recent_sql_queries(self, n: int = 4) -> list[str]:+ queries = [+ tc.arguments.get("query", "")+ for tc in self.tool_calls+ if tc.tool_name == "run_sql" and not tc.is_error+ ]+ return queries[-n:]++ def elapsed_seconds(self) -> float:+ return round(time.time() - self.started_at, 1)++ def summary_for_prompt(self) -> str:+ """A compact, human-readable snapshot of the investigation so far,+ used to keep the model grounded without re-sending the full raw+ tool-call history on every turn."""+ lines = [f"Objective: {self.objective}", f"Step: {self.step_count}"]++ if self.findings:+ lines.append("Findings so far:")+ for f in self.findings:+ lines.append(f" - [{f.importance}] {f.finding}")++ if self.hypotheses:+ lines.append("Hypotheses:")+ for h in self.hypotheses:+ conf = f" (confidence {h.confidence})" if h.confidence is not None else ""+ lines.append(f" - [{h.status}]{conf} {h.hypothesis}")++ if self.open_questions:+ lines.append("Open questions:")+ for q in self.open_questions:+ lines.append(f" - {q}")++ return "\n".join(lines)diff --git a/ai_agents/self_driving_data_analyst/agent/tool_schemas.py b/ai_agents/self_driving_data_analyst/agent/tool_schemas.pynew file mode 100644index 0000000..bbb9cc2--- /dev/null+++ b/ai_agents/self_driving_data_analyst/agent/tool_schemas.py@@ -0,0 +1,170 @@+"""+Function-calling schemas for the tools, in the OpenAI/Liner Chat+Completions `tools` format.++Kept deliberately primitive, on purpose: there is no `find_root_cause()` or+similar shortcut. The model decides what to investigate; these tools only+execute one small, well-defined operation each.+"""++TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "inspect_dataset",+ "description": (+ "Returns schema, column types, row counts, and a few sample rows "+ "for every table currently loaded. Call this first, and again "+ "any time you're unsure what columns or tables exist."+ ),+ "parameters": {"type": "object", "properties": {}, "required": []},+ },+ },+ {+ "type": "function",+ "function": {+ "name": "run_sql",+ "description": (+ "Runs a SQL query (DuckDB syntax) against the loaded tables and "+ "returns the result rows. Use this for aggregations, filtering, "+ "grouping, and joins."+ ),+ "parameters": {+ "type": "object",+ "properties": {+ "query": {"type": "string", "description": "A DuckDB SQL query."},+ },+ "required": ["query"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "run_python",+ "description": (+ "Runs Python code for statistics or calculations SQL isn't suited "+ "for. Loaded tables are available as pandas DataFrames by table "+ "name. pandas is available as pd, numpy as np. Set a variable "+ "named `result` to whatever you want returned."+ ),+ "parameters": {+ "type": "object",+ "properties": {+ "code": {"type": "string", "description": "Python code to execute."},+ },+ "required": ["code"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "create_chart",+ "description": "Renders a chart from a list of rows (e.g. from a prior run_sql result).",+ "parameters": {+ "type": "object",+ "properties": {+ "rows": {+ "type": "array",+ "items": {"type": "object"},+ "description": "Row objects to plot, e.g. the 'rows' field from a run_sql result.",+ },+ "chart_type": {"type": "string", "enum": ["bar", "line", "scatter", "pie", "histogram"]},+ "x": {"type": "string", "description": "Column name for the x-axis."},+ "y": {"type": "string", "description": "Column name for the y-axis, if applicable."},+ "color": {"type": "string", "description": "Optional column name to color/group by."},+ "title": {"type": "string", "description": "Chart title."},+ },+ "required": ["rows", "chart_type", "x"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "save_finding",+ "description": (+ "Records a discovery into the investigation's persistent findings "+ "list, so it survives into the final report. Use this whenever "+ "you confirm something worth including in the final answer, not "+ "just for your own intermediate reasoning."+ ),+ "parameters": {+ "type": "object",+ "properties": {+ "finding": {"type": "string"},+ "importance": {"type": "string", "enum": ["low", "medium", "high"]},+ "evidence": {+ "type": "array",+ "items": {"type": "string"},+ "description": "Short evidence notes supporting this finding.",+ },+ },+ "required": ["finding"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "update_hypothesis",+ "description": (+ "Records or updates a hypothesis about what's actually causing the "+ "pattern in the objective. Call this as you form, test, and resolve "+ "hypotheses during the investigation, not just for your own "+ "intermediate reasoning. Calling it again with the same hypothesis "+ "text updates its status/confidence/evidence in place."+ ),+ "parameters": {+ "type": "object",+ "properties": {+ "hypothesis": {"type": "string"},+ "status": {"type": "string", "enum": ["untested", "supported", "rejected"]},+ "confidence": {"type": "number", "description": "Confidence from 0 to 1, if known."},+ "evidence": {+ "type": "array",+ "items": {"type": "string"},+ "description": "Short evidence notes supporting or refuting this hypothesis.",+ },+ },+ "required": ["hypothesis"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "finish_investigation",+ "description": (+ "Concludes the investigation and produces the final report. Call "+ "this once you genuinely have enough evidence to explain what's "+ "going on, instead of just replying with no more tool calls."+ ),+ "parameters": {+ "type": "object",+ "properties": {+ "root_cause": {"type": "string", "description": "The single, specific root cause identified."},+ "confidence": {"type": "number", "description": "Confidence in the root cause, from 0 to 1."},+ "summary_markdown": {+ "type": "string",+ "description": "The full narrative report, in markdown, including findings, evidence, and conclusion.",+ },+ "key_findings": {+ "type": "array",+ "items": {"type": "string"},+ "description": "The key findings that led to the conclusion.",+ },+ "recommended_actions": {+ "type": "array",+ "items": {"type": "string"},+ "description": "Concrete next steps or actions recommended based on the root cause.",+ },+ },+ "required": ["root_cause", "confidence", "summary_markdown"],+ },+ },+ },+]++TOOL_NAMES = [t["function"]["name"] for t in TOOLS]diff --git a/ai_agents/self_driving_data_analyst/app.py b/ai_agents/self_driving_data_analyst/app.pynew file mode 100644index 0000000..87c25f9--- /dev/null+++ b/ai_agents/self_driving_data_analyst/app.py@@ -0,0 +1,238 @@+from __future__ import annotations++import os++import duckdb+import pandas as pd+import streamlit as st+from dotenv import load_dotenv++from agent.client import LinerAPIError, LinerClient+from agent.harness import InvestigationHarness++load_dotenv()++st.set_page_config(page_title="Self-Driving Data Analyst", layout="wide")++DEMO_DATA_DIR = os.path.join(os.path.dirname(__file__), "data", "ecommerce_demo")++# ---------- session state ----------++if "con" not in st.session_state:+ st.session_state.con = duckdb.connect(database=":memory:")+if "dataframes" not in st.session_state:+ st.session_state.dataframes = {}+if "loaded_tables" not in st.session_state:+ st.session_state.loaded_tables = []+if "log" not in st.session_state:+ st.session_state.log = []+if "final_state" not in st.session_state:+ st.session_state.final_state = None+if "charts" not in st.session_state:+ st.session_state.charts = []+if "running" not in st.session_state:+ st.session_state.running = False+++def read_csv_robust(file_or_path) -> pd.DataFrame:+ try:+ return pd.read_csv(file_or_path)+ except UnicodeDecodeError:+ if hasattr(file_or_path, "seek"):+ file_or_path.seek(0)+ try:+ return pd.read_csv(file_or_path, encoding="cp1252")+ except UnicodeDecodeError as exc:+ name = getattr(file_or_path, "name", file_or_path)+ raise ValueError(+ f"Could not read '{name}' as UTF-8 or Windows-1252 (cp1252) CSV. "+ "Please check the file's encoding."+ ) from exc+++def escape_markdown_dollars(text: str) -> str:+ """Streamlit's st.markdown/st.write treat single $...$ as inline LaTeX+ math, which corrupts model-generated numbers like "$131,364.30". This+ app has no legitimate use for LaTeX math, so escape literal dollar+ signs in any model-generated text before displaying it."""+ if not text:+ return text+ return text.replace("$", "\\$")+++def load_dataframe(name: str, df: pd.DataFrame) -> None:+ st.session_state.con.register(name, df)+ st.session_state.dataframes[name] = df+ if name not in st.session_state.loaded_tables:+ st.session_state.loaded_tables.append(name)+++def load_demo_dataset() -> None:+ if not os.path.isdir(DEMO_DATA_DIR):+ st.error(+ f"Demo dataset not found at {DEMO_DATA_DIR}. Run "+ "`python scripts/generate_sample_data.py` first."+ )+ return+ for fname in os.listdir(DEMO_DATA_DIR):+ if fname.endswith(".csv"):+ table_name = fname.removesuffix(".csv")+ df = read_csv_robust(os.path.join(DEMO_DATA_DIR, fname))+ load_dataframe(table_name, df)+++# ---------- sidebar ----------++with st.sidebar:+ st.header("Dataset")++ uploaded_files = st.file_uploader("Upload CSV file(s)", type="csv", accept_multiple_files=True)+ if uploaded_files:+ for f in uploaded_files:+ table_name = f.name.removesuffix(".csv")+ df = read_csv_robust(f)+ load_dataframe(table_name, df)++ if st.button("Load demo dataset (e-commerce)"):+ load_demo_dataset()++ if st.session_state.loaded_tables:+ st.success(f"Loaded: {', '.join(st.session_state.loaded_tables)}")+ else:+ st.info("No dataset loaded yet.")++ st.divider()+ st.header("Investigation")++ objective_mode = st.radio("Mode", ["Specific objective", "Autopilot: find what matters"])+ if objective_mode == "Specific objective":+ objective = st.text_area(+ "What do you want investigated?",+ placeholder="Why have sales been declining over the last three months?",+ )+ else:+ objective = "Explore this dataset broadly and find the most important patterns, changes, or anomalies happening in the business."++ depth = st.select_slider("Analysis depth", options=["Quick", "Standard", "Deep"], value="Standard")++ max_steps = st.number_input("Max steps", min_value=5, max_value=60, value=25)+ max_tool_calls = st.number_input("Max tool calls", min_value=5, max_value=100, value=40)++ start_disabled = not st.session_state.loaded_tables or st.session_state.running+ start = st.button("Start Investigation", type="primary", disabled=start_disabled)++# ---------- main area ----------++st.title("Self-Driving Data Analyst")+st.caption("Give it a dataset and an objective. It decides how to investigate it.")++if start and not objective:+ st.warning("Please enter an objective before starting.")+elif start:+ st.session_state.log = []+ st.session_state.final_state = None+ st.session_state.charts = []+ st.session_state.running = True++ try:+ client = LinerClient()+ except LinerAPIError as exc:+ st.error(str(exc))+ st.session_state.running = False+ st.stop()++ harness = InvestigationHarness(+ client=client,+ con=st.session_state.con,+ dataframes=st.session_state.dataframes,+ max_steps=int(max_steps),+ max_tool_calls=int(max_tool_calls),+ )++ progress_box = st.status("Investigating...", expanded=True)+ log_lines: list[str] = []+ last_round: int | None = None++ try:+ for event in harness.investigate(objective=objective, depth=depth):+ if event.type == "tool_call":+ record = event.payload["record"]+ if record.model_call_index != last_round:+ separator = f"-- round {record.model_call_index} --"+ log_lines.append(separator)+ progress_box.write(separator)+ last_round = record.model_call_index+ icon = "x" if record.is_error else "-"+ line = f"[{record.call_index}] {icon} {record.tool_name}({record.arguments})"+ log_lines.append(line)+ progress_box.write(line)+ elif event.type == "loop_warning":+ log_lines.append("!! Loop detected, prompting the agent to reassess.")+ progress_box.write("Loop detected, prompting the agent to reassess...")+ elif event.type in ("finished", "budget_exhausted"):+ st.session_state.final_state = event.payload["state"]++ st.session_state.charts = harness.charts+ st.session_state.log = log_lines+ progress_box.update(label="Investigation complete", state="complete", expanded=False)+ except LinerAPIError as exc:+ st.error(f"Liner Model API error: {exc}")+ finally:+ st.session_state.running = False++# ---------- results ----------++if st.session_state.final_state:+ state = st.session_state.final_state++ st.subheader("Final Report")+ if state.stop_reason == "budget_exhausted":+ st.warning(escape_markdown_dollars(state.final_report))+ if state.root_cause:+ conf = f" ({state.confidence:.0%} confidence)" if state.confidence is not None else ""+ st.markdown(f"**Root cause:** {escape_markdown_dollars(state.root_cause)}{conf}")+ st.write(escape_markdown_dollars(state.final_report))++ col1, col2 = st.columns(2)++ with col1:+ st.subheader("Findings")+ if state.findings:+ for f in sorted(state.findings, key=lambda x: {"high": 0, "medium": 1, "low": 2}[x.importance]):+ st.markdown(f"**[{f.importance.upper()}]** {escape_markdown_dollars(f.finding)}")+ for e in f.evidence:+ st.caption(f"- {escape_markdown_dollars(e)}")+ else:+ st.caption("No findings were explicitly saved during this run.")++ with col2:+ st.subheader("Hypotheses Explored")+ if state.hypotheses:+ for h in state.hypotheses:+ st.markdown(f"**[{h.status}]** {escape_markdown_dollars(h.hypothesis)}")+ else:+ st.caption("No hypotheses were explicitly tracked during this run.")++ if st.session_state.charts:+ st.subheader("Charts")+ for i, fig in enumerate(st.session_state.charts):+ st.plotly_chart(fig, use_container_width=True, key=f"chart_{i}")++ st.subheader("Investigation Log")+ with st.expander(f"{state.step_count} model calls · {len(state.tool_calls)} tool calls", expanded=False):+ for line in st.session_state.log:+ st.text(line)++ st.subheader("Usage")+ u = state.usage+ m1, m2, m3, m4 = st.columns(4)+ m1.metric("Agent steps", state.step_count)+ m2.metric("Model calls", u.model_calls)+ m3.metric("Tokens used", u.total_tokens)+ m4.metric("Estimated cost", f"${u.estimated_cost_usd():.4f}")+ st.caption(+ "Cost estimate uses Liner Model API's published liner-mark-1.0 pricing "+ "($1 / $6 / $0.10 per 1M input / output / cached tokens), which is what "+ "you're billed regardless of which underlying model the orchestrator "+ "routed any given request to."+ )diff --git a/ai_agents/self_driving_data_analyst/assets/demo.gif b/ai_agents/self_driving_data_analyst/assets/demo.gifnew file mode 100644index 0000000..4c6f3a6Binary files /dev/null and b/ai_agents/self_driving_data_analyst/assets/demo.gif differdiff --git a/ai_agents/self_driving_data_analyst/requirements.txt b/ai_agents/self_driving_data_analyst/requirements.txtnew file mode 100644index 0000000..1833a7c--- /dev/null+++ b/ai_agents/self_driving_data_analyst/requirements.txt@@ -0,0 +1,8 @@+streamlit>=1.38+pandas>=2.2+numpy>=1.26+duckdb>=1.0+plotly>=5.22+pydantic>=2.7+requests>=2.32+python-dotenv>=1.0diff --git a/ai_agents/self_driving_data_analyst/scripts/generate_sample_data.py b/ai_agents/self_driving_data_analyst/scripts/generate_sample_data.pynew file mode 100644index 0000000..c317dbf--- /dev/null+++ b/ai_agents/self_driving_data_analyst/scripts/generate_sample_data.py@@ -0,0 +1,120 @@+"""+Generates data/ecommerce_demo/{orders,customers,products}.csv.++The data has a specific, known pattern baked in, matching the walkthrough+in the project brief: overall order volume and customer counts stay+roughly flat across all six months, but in the final month a promotion on+the Fashion category raises discounts sharply, which drags down Fashion's+average selling price, which drags down overall average order value, which+shows up as an overall revenue decline. Nothing else in the data changes.++This makes it possible to check whether the agent actually finds the real+cause instead of a plausible-sounding wrong one.+"""++from __future__ import annotations++import os++import numpy as np+import pandas as pd++RNG = np.random.default_rng(seed=7)++OUT_DIR = os.path.join(os.path.dirname(__file__), "..", "data", "ecommerce_demo")++CATEGORIES = ["Electronics", "Beauty", "Home", "Fashion"]+BASE_PRICE = {"Electronics": 220.0, "Beauty": 35.0, "Home": 90.0, "Fashion": 60.0}+REGIONS = ["North", "South", "East", "West"]++N_CUSTOMERS = 800+N_PRODUCTS_PER_CATEGORY = 15+MONTHS = pd.date_range("2025-01-01", periods=6, freq="MS") # Jan .. Jun 2025+DECLINE_MONTH = MONTHS[-1] # June: the promotion month+ORDERS_PER_MONTH = 1400+++def build_customers() -> pd.DataFrame:+ return pd.DataFrame(+ {+ "customer_id": [f"C{i:04d}" for i in range(N_CUSTOMERS)],+ "region": RNG.choice(REGIONS, size=N_CUSTOMERS),+ "signup_date": pd.to_datetime("2023-01-01") + pd.to_timedelta(+ RNG.integers(0, 700, size=N_CUSTOMERS), unit="D"+ ),+ }+ )+++def build_products() -> pd.DataFrame:+ rows = []+ pid = 0+ for category in CATEGORIES:+ for _ in range(N_PRODUCTS_PER_CATEGORY):+ base = BASE_PRICE[category] * RNG.uniform(0.8, 1.3)+ rows.append({"product_id": f"P{pid:04d}", "category": category, "base_price": round(base, 2)})+ pid += 1+ return pd.DataFrame(rows)+++def build_orders(customers: pd.DataFrame, products: pd.DataFrame) -> pd.DataFrame:+ rows = []+ order_id = 0++ for month_start in MONTHS:+ is_decline_month = month_start == DECLINE_MONTH+ days_in_month = pd.Period(month_start, freq="M").days_in_month++ for _ in range(ORDERS_PER_MONTH):+ customer = customers.iloc[RNG.integers(0, len(customers))]+ product = products.iloc[RNG.integers(0, len(products))]+ category = product["category"]++ order_day = RNG.integers(0, days_in_month)+ order_date = month_start + pd.Timedelta(days=int(order_day))++ quantity = int(RNG.integers(1, 4))++ # Baseline discount behavior: small, roughly constant noise.+ discount_pct = float(np.clip(RNG.normal(0.05, 0.02), 0.0, 0.15))++ # The one deliberate change in the whole dataset: a Fashion+ # promotion in the final month raises discounts sharply, and+ # nothing else about that category or month changes.+ if is_decline_month and category == "Fashion":+ discount_pct = float(np.clip(RNG.normal(0.35, 0.05), 0.20, 0.50))++ unit_price = round(product["base_price"] * (1 - discount_pct), 2)++ rows.append(+ {+ "order_id": f"O{order_id:06d}",+ "customer_id": customer["customer_id"],+ "product_id": product["product_id"],+ "order_date": order_date.date().isoformat(),+ "quantity": quantity,+ "unit_price": unit_price,+ "discount_pct": round(discount_pct, 4),+ }+ )+ order_id += 1++ return pd.DataFrame(rows)+++def main() -> None:+ os.makedirs(OUT_DIR, exist_ok=True)++ customers = build_customers()+ products = build_products()+ orders = build_orders(customers, products)++ customers.to_csv(os.path.join(OUT_DIR, "customers.csv"), index=False)+ products.to_csv(os.path.join(OUT_DIR, "products.csv"), index=False)+ orders.to_csv(os.path.join(OUT_DIR, "orders.csv"), index=False)++ print(f"Wrote {len(customers)} customers, {len(products)} products, {len(orders)} orders to {OUT_DIR}")+++if __name__ == "__main__":+ main()diff --git a/ai_agents/self_driving_data_analyst/tests/__init__.py b/ai_agents/self_driving_data_analyst/tests/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/ai_agents/self_driving_data_analyst/tests/test_harness.py b/ai_agents/self_driving_data_analyst/tests/test_harness.pynew file mode 100644index 0000000..1d5fa39--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tests/test_harness.py@@ -0,0 +1,136 @@+import json+from unittest.mock import MagicMock++import duckdb+import pandas as pd++from agent.client import LinerResponse+from agent.harness import InvestigationHarness+++def _fake_response(content=None, tool_calls=None, prompt_tokens=100, completion_tokens=50):+ message = {"role": "assistant", "content": content}+ if tool_calls:+ message["tool_calls"] = tool_calls+ return LinerResponse(+ raw={+ "choices": [{"message": message}],+ "usage": {+ "prompt_tokens": prompt_tokens,+ "completion_tokens": completion_tokens,+ "prompt_tokens_details": {"cached_tokens": 0},+ },+ }+ )+++def _tool_call(call_id, name, arguments):+ return {"id": call_id, "type": "function", "function": {"name": name, "arguments": json.dumps(arguments)}}+++def test_harness_runs_tool_then_concludes():+ con = duckdb.connect(database=":memory:")+ df = pd.DataFrame({"category": ["Fashion", "Electronics"], "revenue": [100, 500]})+ con.register("orders", df)++ client = MagicMock()+ client.chat.side_effect = [+ _fake_response(+ tool_calls=[_tool_call("call_1", "inspect_dataset", {})],+ ),+ _fake_response(content="Fashion revenue is much lower than Electronics. Investigation complete."),+ ]++ harness = InvestigationHarness(client=client, con=con, dataframes={"orders": df}, max_steps=10, max_tool_calls=10)++ events = list(harness.investigate(objective="Why is revenue low?", depth="Standard"))++ event_types = [e.type for e in events]+ assert event_types == ["tool_call", "finished"]++ final_state = events[-1].payload["state"]+ assert final_state.is_finished is True+ assert final_state.stop_reason == "concluded"+ assert "Investigation complete" in final_state.final_report+ assert final_state.usage.model_calls == 2+ assert final_state.usage.total_tokens == 300 # two calls x (100 + 50)+++def test_harness_stops_at_step_budget():+ con = duckdb.connect(database=":memory:")+ df = pd.DataFrame({"x": [1, 2, 3]})+ con.register("t", df)++ client = MagicMock()+ # Always returns another tool call, never concludes on its own.+ client.chat.return_value = _fake_response(+ tool_calls=[_tool_call("call_x", "inspect_dataset", {})]+ )++ harness = InvestigationHarness(client=client, con=con, dataframes={"t": df}, max_steps=3, max_tool_calls=100)++ events = list(harness.investigate(objective="loop forever", depth="Quick"))++ assert events[-1].type == "budget_exhausted"+ final_state = events[-1].payload["state"]+ assert final_state.stop_reason == "budget_exhausted"+ assert final_state.step_count == 3+++def test_tool_calls_share_model_call_index_within_a_round():+ con = duckdb.connect(database=":memory:")+ df = pd.DataFrame({"x": [1, 2, 3]})+ con.register("t", df)++ client = MagicMock()+ client.chat.side_effect = [+ # Round 1: two parallel tool calls in a single model response.+ _fake_response(+ tool_calls=[+ _tool_call("call_1", "inspect_dataset", {}),+ _tool_call("call_2", "inspect_dataset", {}),+ ]+ ),+ # Round 2: a separate while-loop iteration, one more tool call.+ _fake_response(tool_calls=[_tool_call("call_3", "inspect_dataset", {})]),+ _fake_response(content="Done."),+ ]++ harness = InvestigationHarness(client=client, con=con, dataframes={"t": df}, max_steps=10, max_tool_calls=10)+ events = list(harness.investigate(objective="test", depth="Standard"))++ final_state = events[-1].payload["state"]+ tool_calls = final_state.tool_calls+ assert len(tool_calls) == 3++ # Calls dispatched from the same parallel batch share a model_call_index.+ assert tool_calls[0].model_call_index == tool_calls[1].model_call_index+ # A call from a later while-loop iteration gets a different one.+ assert tool_calls[2].model_call_index != tool_calls[0].model_call_index+++def test_harness_save_finding_persists():+ con = duckdb.connect(database=":memory:")+ df = pd.DataFrame({"x": [1]})+ con.register("t", df)++ client = MagicMock()+ client.chat.side_effect = [+ _fake_response(+ tool_calls=[+ _tool_call(+ "call_1",+ "save_finding",+ {"finding": "Revenue dropped due to Fashion discounts", "importance": "high"},+ )+ ]+ ),+ _fake_response(content="Done."),+ ]++ harness = InvestigationHarness(client=client, con=con, dataframes={"t": df}, max_steps=10, max_tool_calls=10)+ events = list(harness.investigate(objective="test", depth="Standard"))++ final_state = events[-1].payload["state"]+ assert len(final_state.findings) == 1+ assert final_state.findings[0].importance == "high"diff --git a/ai_agents/self_driving_data_analyst/tests/test_tools.py b/ai_agents/self_driving_data_analyst/tests/test_tools.pynew file mode 100644index 0000000..03c8ed6--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tests/test_tools.py@@ -0,0 +1,92 @@+import duckdb+import pandas as pd+import pytest++from agent.loop_detector import is_looping+from agent.state import InvestigationState+from tools.charts import create_chart+from tools.dataset import inspect_dataset+from tools.findings import save_finding+from tools.python_tool import run_python+from tools.sql import run_sql+++def con():+ connection = duckdb.connect(database=":memory:")+ df = pd.DataFrame({"category": ["A", "B", "A"], "revenue": [100, 200, 150]})+ connection.register("orders", df)+ return connection+++def test_inspect_dataset(con):+ result = inspect_dataset(con)+ assert "orders" in result["tables"]+ assert result["tables"]["orders"]["row_count"] == 3+ assert {"name": "category", "type": "VARCHAR"} in [+ {"name": c["name"], "type": c["type"]} for c in result["tables"]["orders"]["columns"]+ ]+++def test_run_sql_success(con):+ result = run_sql(con, "SELECT category, SUM(revenue) AS total FROM orders GROUP BY category")+ assert result["success"] is True+ assert result["row_count"] == 2+++def test_run_sql_error_is_returned_not_raised(con):+ result = run_sql(con, "SELECT nonexistent_column FROM orders")+ assert result["success"] is False+ assert "error" in result+++def test_run_python_sets_result():+ dfs = {"orders": pd.DataFrame({"revenue": [100, 200, 300]})}+ result = run_python("result = orders['revenue'].mean()", dfs)+ assert result["success"] is True+ assert result["result"] == 200.0+++def test_run_python_blocks_dangerous_builtins():+ result = run_python("open('/etc/passwd')", {})+ assert result["success"] is False+++def test_create_chart_success():+ rows = [{"category": "A", "revenue": 100}, {"category": "B", "revenue": 200}]+ result = create_chart(rows, chart_type="bar", x="category", y="revenue")+ assert result["success"] is True+ assert "figure" in result+++def test_create_chart_bad_column():+ rows = [{"category": "A"}]+ result = create_chart(rows, chart_type="bar", x="does_not_exist")+ assert result["success"] is False+++def test_save_finding_persists_to_state():+ state = InvestigationState(objective="test")+ save_finding(state, "Revenue dropped 18%", importance="high")+ assert len(state.findings) == 1+ assert state.findings[0].importance == "high"+++def test_loop_detector_flags_repeated_queries():+ state = InvestigationState(objective="test")+ for _ in range(4):+ state.add_tool_call("run_sql", {"query": "SELECT * FROM orders"}, "some result")+ assert is_looping(state) is True+++def test_loop_detector_ignores_varied_queries():+ state = InvestigationState(objective="test")+ queries = [+ "SELECT * FROM orders",+ "SELECT category, SUM(revenue) FROM orders GROUP BY category",+ "SELECT * FROM customers",+ "SELECT AVG(revenue) FROM orders WHERE category = 'Fashion'",+ ]+ for q in queries:+ state.add_tool_call("run_sql", {"query": q}, "some result")+ assert is_looping(state) is Falsediff --git a/ai_agents/self_driving_data_analyst/tools/__init__.py b/ai_agents/self_driving_data_analyst/tools/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/ai_agents/self_driving_data_analyst/tools/charts.py b/ai_agents/self_driving_data_analyst/tools/charts.pynew file mode 100644index 0000000..c01c34e--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tools/charts.py@@ -0,0 +1,53 @@+"""+create_chart(...) - renders a chart locally with Plotly.++Deliberately local. This project's scope is the Liner Model API only; it+does not call Liner's separate Visualization API. If you ever extend this+tool, keep it that way, wiring this up to the real Visualization API would+pull in a different product than the one this project is about.+"""++from __future__ import annotations++from typing import Any, Optional++import pandas as pd+import plotly.express as px++_CHART_BUILDERS = {+ "bar": px.bar,+ "line": px.line,+ "scatter": px.scatter,+ "pie": px.pie,+ "histogram": px.histogram,+}+++def create_chart(+ rows: list[dict[str, Any]],+ chart_type: str,+ x: str,+ y: Optional[str] = None,+ color: Optional[str] = None,+ title: Optional[str] = None,+):+ if chart_type not in _CHART_BUILDERS:+ return {"success": False, "error": f"Unsupported chart_type '{chart_type}'. Use one of {list(_CHART_BUILDERS)}."}++ df = pd.DataFrame(rows)+ if x not in df.columns:+ return {"success": False, "error": f"Column '{x}' not found in the provided rows."}++ kwargs: dict[str, Any] = {"x": x, "title": title}+ if y:+ kwargs["y"] = y+ if color:+ kwargs["color"] = color++ builder = _CHART_BUILDERS[chart_type]+ try:+ fig = builder(df, **kwargs)+ except Exception as exc: # noqa: BLE001 - becomes model-facing data+ return {"success": False, "error": str(exc)}++ return {"success": True, "figure": fig}diff --git a/ai_agents/self_driving_data_analyst/tools/dataset.py b/ai_agents/self_driving_data_analyst/tools/dataset.pynew file mode 100644index 0000000..85a175d--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tools/dataset.py@@ -0,0 +1,34 @@+"""+inspect_dataset() - the agent's first move in almost every investigation.++Deliberately kept primitive: it returns schema, types, row counts, and a+few sample rows, and nothing more. It does not summarize, does not guess+at what's interesting, and does not suggest what to check next. That+judgment is the model's job, not the tool's.+"""++from __future__ import annotations++import duckdb+++def inspect_dataset(con: duckdb.DuckDBPyConnection) -> dict:+ tables = [row[0] for row in con.execute("SHOW TABLES").fetchall()]++ schema_info: dict[str, dict] = {}+ for table_name in tables:+ columns_df = con.execute(f"DESCRIBE {table_name}").fetchdf()+ row_count = con.execute(f"SELECT COUNT(*) FROM {table_name}").fetchone()[0]+ sample_rows = (+ con.execute(f"SELECT * FROM {table_name} LIMIT 3").fetchdf().to_dict(orient="records")+ )+ schema_info[table_name] = {+ "columns": [+ {"name": r["column_name"], "type": r["column_type"]}+ for r in columns_df.to_dict(orient="records")+ ],+ "row_count": row_count,+ "sample_rows": sample_rows,+ }++ return {"tables": schema_info}diff --git a/ai_agents/self_driving_data_analyst/tools/findings.py b/ai_agents/self_driving_data_analyst/tools/findings.pynew file mode 100644index 0000000..44dc489--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tools/findings.py@@ -0,0 +1,18 @@+"""+save_finding(...) - the agent's way of writing something down for good.++Kept separate from the model's free-text output on purpose: findings saved+this way persist in structured state and survive into the final report,+observations mentioned only in passing in the model's reasoning do not.+"""++from __future__ import annotations++from agent.state import InvestigationState+++def save_finding(state: InvestigationState, finding: str, importance: str = "medium", evidence: list[str] | None = None) -> dict:+ if importance not in ("low", "medium", "high"):+ importance = "medium"+ state.add_finding(finding=finding, importance=importance, evidence=evidence or [])+ return {"success": True, "saved": finding}diff --git a/ai_agents/self_driving_data_analyst/tools/python_tool.py b/ai_agents/self_driving_data_analyst/tools/python_tool.pynew file mode 100644index 0000000..0530cf1--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tools/python_tool.py@@ -0,0 +1,72 @@+"""+run_python(code) - for statistics and calculations SQL isn't suited for.++SECURITY NOTE, read before using this outside a local/trusted demo:+This executes model-generated code with a restricted builtins list and no+filesystem/network access, which is a reasonable floor for a local demo but+is NOT a real security sandbox. A determined or simply buggy generation+could still find ways to consume excessive memory/CPU or exploit a gap in+the restricted namespace. For anything beyond your own machine or a trusted+demo, run this tool inside a real sandbox (e.g. E2B) instead of in-process.+"""++from __future__ import annotations++import contextlib+import io+import math+from typing import Any++import numpy as np+import pandas as pd++_SAFE_BUILTINS = {+ "abs": abs,+ "round": round,+ "min": min,+ "max": max,+ "sum": sum,+ "len": len,+ "sorted": sorted,+ "range": range,+ "enumerate": enumerate,+ "zip": zip,+ "list": list,+ "dict": dict,+ "set": set,+ "tuple": tuple,+ "float": float,+ "int": int,+ "str": str,+ "bool": bool,+ "print": print,+}+++def run_python(code: str, dataframes: dict[str, pd.DataFrame]) -> dict:+ """Executes `code` with the loaded tables available as pandas DataFrames+ (by table name) plus pd/np/math, and returns whatever was printed plus+ the value of a `result` variable if the code set one."""++ local_vars: dict[str, Any] = {**dataframes}+ global_vars = {+ "__builtins__": _SAFE_BUILTINS,+ "pd": pd,+ "np": np,+ "math": math,+ }++ stdout = io.StringIO()+ try:+ with contextlib.redirect_stdout(stdout):+ exec(code, global_vars, local_vars) # noqa: S102 - restricted globals above+ except Exception as exc: # noqa: BLE001 - becomes model-facing data, not a crash+ return {"success": False, "error": f"{type(exc).__name__}: {exc}", "stdout": stdout.getvalue()}++ result = local_vars.get("result")+ if isinstance(result, pd.DataFrame):+ result = result.head(50).to_dict(orient="records")+ elif isinstance(result, (pd.Series, np.ndarray)):+ result = list(result)[:50]++ return {"success": True, "stdout": stdout.getvalue(), "result": result}diff --git a/ai_agents/self_driving_data_analyst/tools/sql.py b/ai_agents/self_driving_data_analyst/tools/sql.pynew file mode 100644index 0000000..638bfc9--- /dev/null+++ b/ai_agents/self_driving_data_analyst/tools/sql.py@@ -0,0 +1,29 @@+"""+run_sql(query) - lets the agent query the loaded datasets directly.++Errors are returned as data, not raised, so the harness can hand them back+to the model as an observation ("this column doesn't exist") instead of+crashing the investigation. See agent/harness.py for how a failed query+becomes the trigger for a follow-up inspect_dataset() call.+"""++from __future__ import annotations++import duckdb++MAX_ROWS_RETURNED = 50+++def run_sql(con: duckdb.DuckDBPyConnection, query: str) -> dict:+ try:+ df = con.execute(query).fetchdf()+ except Exception as exc: # noqa: BLE001 - deliberately broad, this becomes model-facing data+ return {"success": False, "error": str(exc)}++ return {+ "success": True,+ "columns": list(df.columns),+ "row_count": len(df),+ "rows": df.head(MAX_ROWS_RETURNED).to_dict(orient="records"),+ "truncated": len(df) > MAX_ROWS_RETURNED,+ }