Dynamic Report Agent — Data skill for Claude Code

Dynamic Report Generation Agent

This project is a lightweight AI agent that turns a natural-language business question into SQL, asks follow-up questions when the request is ambiguous, and generates a readable report from the result.

For the current learning/demo version, the SQL is executed against an embedded SQLite fixture dataset so the behavior is easy to test. In a real production deployment, the generated SQL would connect to your actual database system and execute against live data instead of the mock dataset.

It is built as a learning project for:

• LLM tool calling
• multi-turn agent loops
• SQL guardrails
• schema-aware prompting
• report generation from query results

What this solution does

When you run the app:

1. It loads the schema from data/schema.py.
2. It sends the user's query to the Claude model with the schema in context.
3. If the query is ambiguous, the agent may call the ask_clarification tool.
4. Once the intent is clear, the agent calls generate_sql_query to return the SQL query and explanation.
5. The generated SQL is executed against the embedded SQLite fixture dataset.
6. A Markdown and HTML report is created in the reports/ folder.

Features

• Natural-language to SQL generation
• Clarifying questions for missing details
• Schema-aware prompting using the database schema
• Multi-turn conversational flow in the agent loop
• SQL safety validation to block dangerous operations
• Auto-generated Markdown and HTML reports

Project structure

dynamic-report-agent/
├── src/
│   ├── agent/
│   │   ├── client.py            # Anthropic client creation and env loading
│   │   ├── loop.py              # Main agent loop and tool-calling flow
│   │   ├── query_builder.py     # SQLite query execution and safety checks
│   │   └── report_generator.py  # Markdown/HTML report generation
│   ├── main.py                  # Entry point for running sample queries
│   └── __init__.py
├── config/
│   └── env.py                   # En