feat: add warehouse_explore tool for structured data exploration

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kulvirgit

packages/altimate-engine/src/altimate_engine/models.py

@@ -987,6 +987,27 @@ class AltimateCoreIsSafeParams(BaseModel):
     sql: str
 
 
+# --- Warehouse Explore ---
+
+
+class WarehouseExploreParams(BaseModel):
+    warehouse: str | None = None
+
+
+class WarehouseExploreTableInfo(BaseModel):
+    schema_name: str = Field(alias="schema")
+    name: str
+    columns: list[str]
+
+    model_config = {"populate_by_name": True}
+
+
+class WarehouseExploreResult(BaseModel):
+    tables: list[WarehouseExploreTableInfo]
+    table_count: int
+
+
+
 # --- JSON-RPC ---
 
 

packages/altimate-engine/src/altimate_engine/server.py

@@ -65,6 +65,9 @@
     SqlRewriteRule,
     SqlTranslateParams,
     SqlTranslateResult,
+    WarehouseExploreParams,
+    WarehouseExploreTableInfo,
+    WarehouseExploreResult,
     WarehouseInfo,
     WarehouseListResult,
     WarehouseTestParams,
@@ -212,6 +215,37 @@
 INTERNAL_ERROR = -32603
 
 
+# --- Warehouse helpers ---
+
+
+def _resolve_warehouse(warehouse_name: str | None):
+    """Resolve warehouse: explicit name > registered connections > dbt profiles."""
+    if warehouse_name:
+        return ConnectionRegistry.get(warehouse_name)
+    # Try first registered connection
+    connections = ConnectionRegistry.list()
+    if connections:
+        return ConnectionRegistry.get(connections[0]["name"])
+    # Try dbt profiles
+    dbt_conns = discover_dbt_connections()
+    if dbt_conns:
+        first_name = next(iter(dbt_conns))
+        # Register it so ConnectionRegistry.get() works
+        ConnectionRegistry.add(first_name, dbt_conns[first_name])
+        return ConnectionRegistry.get(first_name)
+    raise ValueError(
+        "No warehouse connection found. Configure one or pass warehouse name."
+    )
+
+
+def _parse_table_ref(table_name: str) -> tuple[str | None, str]:
+    """Parse 'schema.table' into (schema, table) or (None, table)."""
+    parts = table_name.split(".", 1)
+    if len(parts) == 2:
+        return parts[0], parts[1]
+    return None, parts[0]
+
+
 # Lazily-initialized singletons
 def _schema_context_to_dict(
     schema_context: dict[str, list] | None,
@@ -453,6 +487,28 @@ def dispatch(request: JsonRpcRequest) -> JsonRpcResponse:
             result = parse_manifest(DbtManifestParams(**params))
         elif method == "dbt.lineage":
             result = dbt_lineage(DbtLineageParams(**params))
+        elif method == "warehouse.explore":
+            p = WarehouseExploreParams(**params)
+            connector = _resolve_warehouse(p.warehouse)
+            connector.connect()
+            try:
+                tables_info = []
+                for schema in connector.list_schemas():
+                    for tbl in connector.list_tables(schema):
+                        cols = connector.describe_table(schema, tbl["name"])
+                        col_names = [c["name"] for c in cols]
+                        tables_info.append(
+                            WarehouseExploreTableInfo(
+                                schema=schema,
+                                name=tbl["name"],
+                                columns=col_names,
+                            )
+                        )
+                result = WarehouseExploreResult(
+                    tables=tables_info, table_count=len(tables_info)
+                )
+            finally:
+                connector.close()
         elif method == "warehouse.list":
             warehouses = [WarehouseInfo(**w) for w in ConnectionRegistry.list()]
             result = WarehouseListResult(warehouses=warehouses)

packages/opencode/src/altimate/bridge/protocol.ts

@@ -951,6 +951,24 @@ export interface LocalTestResult {
   error?: string
 }
 
+// --- Warehouse Explore ---
+
+export interface WarehouseExploreParams {
+  warehouse?: string
+}
+
+export interface WarehouseExploreTableInfo {
+  schema: string
+  name: string
+  columns: string[]
+}
+
+export interface WarehouseExploreResult {
+  tables: WarehouseExploreTableInfo[]
+  table_count: number
+}
+
+
 // --- Method registry ---
 
 export const BridgeMethods = {
@@ -975,6 +993,7 @@ export const BridgeMethods = {
   "warehouse.add": {} as { params: WarehouseAddParams; result: WarehouseAddResult },
   "warehouse.remove": {} as { params: WarehouseRemoveParams; result: WarehouseRemoveResult },
   "warehouse.discover": {} as { params: Record<string, never>; result: WarehouseDiscoverResult },
+  "warehouse.explore": {} as { params: WarehouseExploreParams; result: WarehouseExploreResult },
   "finops.query_history": {} as { params: QueryHistoryParams; result: QueryHistoryResult },
   "finops.analyze_credits": {} as { params: CreditAnalysisParams; result: CreditAnalysisResult },
   "finops.expensive_queries": {} as { params: ExpensiveQueriesParams; result: ExpensiveQueriesResult },

packages/opencode/src/altimate/prompts/builder.txt

@@ -5,6 +5,7 @@ You have full read/write access to the project. You can:
 - Execute SQL against connected warehouses via `sql_execute`
 - Validate SQL with AltimateCore via `sql_validate` (syntax, safety, lint, PII)
 - Analyze SQL for anti-patterns and performance issues via `sql_analyze`
+- Explore warehouse schemas and tables via `warehouse_explore` (use FIRST)
 - Inspect database schemas via `schema_inspect`
 - Check column-level lineage via `lineage_check`
 - List and test warehouse connections via `warehouse_list` and `warehouse_test`

packages/opencode/src/altimate/tools/warehouse-explore.ts

@@ -0,0 +1,58 @@
+import z from "zod"
+import { Tool } from "../../tool/tool"
+import { Bridge } from "../bridge/client"
+import type { WarehouseExploreResult } from "../bridge/protocol"
+
+export const WarehouseExploreTool = Tool.define("warehouse_explore", {
+  description:
+    "List all schemas and table names in the connected warehouse. " +
+    "Use this FIRST to see what tables exist. Then use schema_inspect " +
+    "on specific tables to see their column types and details.",
+  parameters: z.object({
+    warehouse: z.string().optional().describe("Warehouse connection name (auto-detected if omitted)"),
+  }),
+  async execute(args, ctx) {
+    try {
+      const result = await Bridge.call("warehouse.explore", {
+        warehouse: args.warehouse,
+      })
+
+      return {
+        title: `Warehouse: ${result.table_count} tables`,
+        metadata: { tableCount: result.table_count },
+        output: formatExploreResult(result),
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      return {
+        title: "Warehouse: ERROR",
+        metadata: { tableCount: 0 },
+        output: `Failed to explore warehouse: ${msg}\n\nEnsure the Python bridge is running and a warehouse connection is configured.`,
+      }
+    }
+  },
+})
+
+function formatExploreResult(result: WarehouseExploreResult): string {
+  if (result.table_count === 0) return "(no tables found)"
+
+  const lines: string[] = [`${result.table_count} tables found:`, ""]
+
+  // Group by schema
+  const bySchema = new Map<string, typeof result.tables>()
+  for (const table of result.tables) {
+    const list = bySchema.get(table.schema) || []
+    list.push(table)
+    bySchema.set(table.schema, list)
+  }
+
+  for (const [schema, tables] of bySchema) {
+    lines.push(`### ${schema}`)
+    for (const t of tables) {
+      lines.push(`- ${t.name} (${t.columns.join(", ")})`)
+    }
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}

packages/opencode/src/tool/registry.ts

@@ -44,6 +44,7 @@ import { WarehouseTestTool } from "../altimate/tools/warehouse-test"
 import { WarehouseAddTool } from "../altimate/tools/warehouse-add"
 import { WarehouseRemoveTool } from "../altimate/tools/warehouse-remove"
 import { WarehouseDiscoverTool } from "../altimate/tools/warehouse-discover"
+import { WarehouseExploreTool } from "../altimate/tools/warehouse-explore"
 import { DbtRunTool } from "../altimate/tools/dbt-run"
 import { DbtManifestTool } from "../altimate/tools/dbt-manifest"
 import { DbtProfilesTool } from "../altimate/tools/dbt-profiles"
@@ -218,6 +219,7 @@ export namespace ToolRegistry {
       WarehouseAddTool,
       WarehouseRemoveTool,
       WarehouseDiscoverTool,
+      WarehouseExploreTool,
       DbtRunTool,
       DbtManifestTool,
       DbtProfilesTool,