controls-web/ai_agents/db_agent/prompting/README.md

Prompt Assembly

Utilities for packaging database context into a single LLM prompt.

Files

• prompt_builder.py: Loads schema/glossary/value hints/example artifacts and produces a structured prompt for SQL generation.
• __init__.py: Exposes load_context and build_prompt helpers.

Quick Start

1. Ensure context artifacts exist under db_agent/context/ (run the extractor, curate glossary/value hints/examples).
2. In Python, build the prompt:

   from db_agent.prompting import load_context, build_prompt
   
   ctx = load_context()
   prompt = build_prompt(
       question="Which vehicles hauled more than 30 tons last week?",
       context=ctx,
       table_hints=["dbo.SugarLoadData", "dbo.SugarVehicles"],
   )
   print(prompt)
   

3. Send the prompt to your LLM provider (OpenAI, Azure OpenAI, Anthropic, etc.) and parse the JSON response with the sql and summary fields.

Configuration

• Customize file paths by instantiating PromptConfig with alternate filenames or directories.
• Use table_hints to restrict the schema section to relevant tables (helps stay within context limits).
• Adjust max_columns to control how many column definitions are emitted per table.

Next Steps

• Integrate the prompt builder into a service layer that calls the LLM and executes the generated SQL with validation.
• Add retrieval heuristics to automatically pick tables based on keyword matching instead of manually passing table_hints.
• Extend the format to include recent query logs or execution feedback for reinforcement.