🛡️ Agentic-Data-Intelligence

AI-Powered Business Intelligence Engine with LangGraph Agentic Workflows & AST-Secured Query Execution

Live Demo • Architecture • Workflow • Security • Installation

---

📌 Why This Project?

Traditional natural language analytics tools rely on generating raw SQL queries or dynamic exec() code strings. This introduces critical security vulnerabilities like SQL injection and remote code execution (RCE), while limiting execution to rigid database schemas.

Agentic-Data-Intelligence solves this by enforcing a zero-SQL, type-safe execution model. Built on a stateful LangGraph agent architecture, natural language prompts are translated into structured expressions validated through a Custom Abstract Syntax Tree (AST) Parser. This guarantees that only whitelisted vector operations run on data, delivering safe, low-latency conversational BI for enterprise datasets.

---

✨ Features at a Glance

• Conversational BI: Query complex business line and regional sales data using everyday English.
• LangGraph Agent Workflow: Cyclic graph-based agent execution (agent_graph.py) orchestrating intent parsing, data routing, and insight generation.
• AST Security Engine: Validates every generated filter/expression prior to execution, completely eliminating dynamic code injection risks.
• Sub-Second Groq LPU Acceleration: Powered by llama-3.3-70b-versatile on Groq hardware for fast query translation.
• Automated Plotly Visualizations: Automatically selects and renders interactive charts tailored to the data schema.
• Modular Database Adapter: In-memory vectorized processing with built-in database adapters (database_engine.py).

---

📸 Application Preview

+-----------------------------------------------------------------------------------+
| 🛡️ Secure Text-to-Viz Analytics Engine                                            |
| [Llama-3.3-70b (Groq)]  [AST Secure Filter]  [Plotly Express]                     |
| Zero-SQL, Type-Safe AST Engine Translating Natural Language to Visualizations.     |
+-----------------------------------------------------------------------------------+
| 💡 Quick Query Suggestions:                                                       |
|  [ 📊 Revenue by Business Line (2024) ]   [ 📈 Trajectory Across 2023-2025 ]      |
+-----------------------------------------------------------------------------------+
| e.g., Show me the trajectory of business lines where the year is equal to 2024    |
+-----------------------------------------------------------------------------------+

🛠️ Technology Stack

Layer	Technology	File / Component	Role
Frontend UI	Streamlit	app.py	Dashboard interface, prompt handling, and chart rendering
Agent Framework	LangGraph	agent_graph.py	Graph orchestration, state management, and tool routing
LLM Inference	Groq LPU (llama-3.3-70b)	API Integration	Low-latency natural language understanding and intent parsing
Data Engine	Pandas / SQLAlchemy	database_engine.py	AST execution, vectorized filtering, and database queries
Data Synthesizer	Python Script	generate_data.py	Mock dataset generator for industrial enterprise schemas
Visualization	Plotly Express	app.py	Interactive chart generation (Bar, Line, Scatter, Heatmap)
Deployment	Streamlit Cloud	Cloud Hosting	Live production environment synced via GitHub

---

🏗️ System Architecture

flowchart LR
    subgraph UI ["Presentation Layer"]
        User(["User Prompt"]) --> StreamlitUI["Streamlit UI (app.py)"]
    end

    subgraph Agents ["LangGraph Agent System (agent_graph.py)"]
        StreamlitUI --> GraphSupervisor["Agent Graph Supervisor"]
        GraphSupervisor --> IntentAgent["Intent Classifier"]
        GraphSupervisor --> SecurityAgent["Query Builder"]
        GraphSupervisor --> InsightAgent["Executive Insight Writer"]
    end

    subgraph LLM ["Inference"]
        Agents <--> Groq["Groq LPU Engine"]
    end

    subgraph Security ["Security & Execution (database_engine.py)"]
        SecurityAgent --> AST["AST Parser & Node Inspector"]
        AST -- "Valid Tree" --> Engine["Pandas / SQLAlchemy Engine"]
        AST -- "Invalid Node" --> Blocked["Execution Aborted"]
    end

    subgraph Data ["Data Source"]
        Engine <--> ExcelData[("abb_sales_data.xlsx")]
    end

    subgraph Output ["Visualization"]
        Engine --> Plotly["Plotly Charts"]
        Plotly --> StreamlitUI
        InsightAgent --> StreamlitUI
    end

Loading

System Architecture Breakdown

The architecture follows a decoupled, multi-tier design separating user interaction, orchestration, inference, and execution:

• Presentation Layer (app.py): Built with Streamlit, providing a clean chat interface that captures user queries, maintains chat history, and dynamically renders Plotly visualizations alongside executive summaries.
• LangGraph Agent System (agent_graph.py): Acts as the central brain. Instead of a single static prompt, stateful graph nodes divide processing into sub-tasks (Intent Classification, Query Construction, and Insight Generation).
• Groq LPU Inference Engine: Connects to llama-3.3-70b-versatile over ultra-low latency LPU infrastructure for near-instant expression generation and summary synthesis.
• Security & Execution Engine (database_engine.py): Intercepts generated query payloads before database contact. The custom AST parser inspects syntax nodes to prevent arbitrary code execution, then safely executes validated expressions via vectorized Pandas / SQLAlchemy pipelines.
• Data Layer (abb_sales_data.xlsx): Provides structured industrial enterprise analytics data, fully isolated from direct raw user queries.

---

🔄 End-to-End Workflow

sequenceDiagram
    autonumber
    actor User
    participant UI as "Streamlit UI (app.py)"
    participant Graph as "Agent Graph (agent_graph.py)"
    participant Groq as "Groq LPU"
    participant AST as "AST Inspector (database_engine.py)"
    participant Data as "Data Engine"

    User->>UI: Input natural language query
    UI->>Graph: Send query & schema context
    Graph->>Groq: Request intent classification & expression structure
    Groq-->>Graph: Return structured AST expression
    Graph->>AST: Validate node syntax against whitelist
    
    alt Injection / Unauthorized call detected
        AST-->>UI: Raise Security Exception & Abort
    else AST Expression Validated
        AST->>Data: Execute safe operation on abb_sales_data.xlsx
        Data-->>UI: Return filtered metrics & Dataframe
        Graph->>Groq: Generate executive summary
        Groq-->>UI: Render interactive Plotly charts & insights
    end

Loading

Step-by-Step Execution Sequence

1. Query Submission: The user submits an everyday query (e.g., "Show me revenue by business line for 2024").
2. Context Enrichment: app.py passes the query along with minimal table schema metadata to agent_graph.py.
3. LLM Translation: The Agent Supervisor prompts Groq LPU to return a strictly typed JSON/AST expression tree rather than a raw SQL string.
4. AST Whitelist Inspection: database_engine.py parses the expression tree. It checks every node against allowed arithmetic and filter operators (Compare, Attribute, Num, Str, BinOp).
5. Branching & Safety Verification:

• If malicious or unapproved code is detected: Execution halts immediately, and a security exception is safely raised to the UI without touching the database.
• If AST is fully validated: The filter is applied safely to the dataset using vectorized Pandas operations.

6. Insight & Chart Generation: The filtered dataset is mapped to appropriate Plotly chart types while the LLM generates a bulleted executive summary.
7. UI Presentation: The final response renders seamlessly in Streamlit with interactive charts, summary metrics, and inspectable data tables.

---

🤖 Multi-Agent Graph Communication

flowchart TD
    UserQuery(["User Input"]) --> StartNode["State Graph Start"]
    
    StartNode --> IntentNode["1. Intent Node"]
    IntentNode -- "Extracts target metrics & filters" --> RoutingNode{"Route Task"}
    
    RoutingNode -- "Query Request" --> QueryNode["2. Query Security Node"]
    QueryNode --> ASTCheck{"AST Whitelist Validation"}
    
    ASTCheck -- "PASSED" --> ExecutionNode["3. Database Engine Node"]
    ASTCheck -- "FAILED" --> SecurityError["Security Exception"]
    
    ExecutionNode -- "Process data" --> SummaryNode["4. Insight Synthesis Node"]
    SummaryNode --> EndNode(["Render Result to UI"])

Loading

Agent Roles & State Graph Responsibility

The system utilizes LangGraph to build a cyclic, state-driven workflow where each node specializes in a single task:

• Node 1: Intent Node: Parses incoming prompts to identify key business parameters—target dimensions (e.g., Business Line), numerical metrics (e.g., Revenue), date ranges (e.g., Year == 2024), and desired chart types.
• Node 2: Query Security Node: Translates extracted parameters into an AST-compatible logical condition structure. It acts as an isolation barrier between LLM text generation and system execution.
• Node 3: Database Engine Node: Accepts only verified AST expressions. Executes in-memory vectorized transformations on the dataset to produce aggregate figures and filtered dataframes.
• Node 4: Insight Synthesis Node: Consumes raw calculated outputs from Node 3 and crafts concise business executive summaries highlighting trends, outliers, and key metrics.

---

🔒 Why AST Security Over Raw SQL?

flowchart TD
    subgraph Traditional ["Traditional Text-to-SQL (Vulnerable)"]
        A1["User Prompt"] --> A2["LLM"]
        A2 --> A3["Raw SQL Query"]
        A3 --> A4["Database"]
        A4 --> A5["🚨 Risk: SQL Injection / Table Corruption"]
    end

    subgraph ASTSystem ["AST-Engine (Safe)"]
        B1["User Prompt"] --> B2["LLM"]
        B2 --> B3["AST Node Expression"]
        B3 --> B4{"AST Whitelist Inspector"}
        B4 -- "Safe Expression" --> B5["Pandas / SQLAlchemy Execution"]
        B4 -- "Unsafe Call" --> B6["❌ Execution Rejection"]
    end

Loading

Security Comparison Analysis

Risk / Feature	Traditional Text-to-SQL / Dynamic exec()	AST-Secured Execution Model (Our Approach)
SQL Injection	High Risk: Malicious prompts can inject DROP TABLE, UNION SELECT, or stacked queries.	Zero Risk: No raw SQL strings are generated or sent directly to the database.
Remote Code Execution (RCE)	High Risk: Dynamic code evaluate engines like exec() or eval() can run host commands.	Zero Risk: AST inspector rejects module imports, function calls, and unauthorized tokens.
Data Corruption	Possible: Unchecked write/alter queries can mutate persistent storage.	Impossible: Read-only vectorized execution sandbox over structured data instances.
Determinism & Parsing	Low: LLM text generation can omit quotes, misspell SQL syntax, or generate invalid dialects.	High: Evaluates strictly against standard Abstract Syntax Tree structures with clear node types.

How the AST Whitelist Works

When an expression is parsed into Python's ast.NodeVisitor, every single syntax node is validated:

• Allowed Nodes: ast.Expression, ast.Compare, ast.Name, ast.Load, ast.Constant, ast.Eq, ast.Gt, ast.Lt, ast.And, ast.Or.
• Disallowed Nodes: ast.Call (prevents function invocation), ast.Import (prevents loading system modules), ast.Attribute access to private methods (__subclasses__, __globals__).

---

💡 Example Queries

Try running these natural language prompts against the platform:

• 📊 Business Line Performance: "Show me revenue by business line for 2024"
• 📈 Multi-Year Trajectory: "What is the sales trajectory across 2023, 2024, and 2025?"
• 🌍 Regional Breakdown: "Display regional units sold categorized by client industry"
• 🔍 Targeted Filter: "Find all discrete automation orders in South India where units sold exceed 400"
• 📉 Comparative Analysis: "Compare average order value between Electrification and Motion divisions"

---

⚡ Performance Profile

Metric	Target	Realized
Groq LPU Inference	< 1.5s	~0.4s - 0.8s
AST Parse & Inspection	< 10ms	< 2ms
Data Transformation	< 100ms	In-memory vectorized evaluation
Chart Rendering	< 200ms	Real-time Plotly Express
Execution Security	Read-Only	Safe AST-isolated sandbox

---

📂 Project Directory Structure

agentic-data-intelligence/
├── .env                  # Local environment variables (API keys)
├── .env.example          # Environment variable template
├── .gitignore            # Git exclusion settings
├── abb_sales_data.xlsx   # Industrial sample dataset
├── agent_graph.py        # LangGraph agent graph definition & node routing
├── app.py                # Main Streamlit web application dashboard
├── database_engine.py    # AST security parser & database execution engine
├── generate_data.py      # Synthetic enterprise dataset generation script
├── README.md             # Project documentation
└── requirements.txt      # Python dependencies

---

🚀 Getting Started

Prerequisites

• Python: 3.10 or higher
• Groq API Key: Obtain a free key at console.groq.com
• Setup Time: ≈ 2 minutes

Installation

1. Clone the repository:

git clone [https://github.com/KesavaAI/agentic-data-intelligence.git](https://github.com/KesavaAI/agentic-data-intelligence.git)
cd agentic-data-intelligence

2. Create and activate virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure Environment Variables: Copy .env.example to .env and fill in your API key:

cp .env.example .env

Add your key inside .env:

GROQ_API_KEY=gsk_your_groq_api_key_here

5. (Optional) Regenerate Sample Dataset:

python generate_data.py

6. Launch the Application:

streamlit run app.py

---

🔑 Environment Variables Reference

Variable	Required	Description
GROQ_API_KEY	Yes	Key for Groq low-latency inference (llama-3.3-70b-versatile)
OPENAI_API_KEY	Optional	Fallback LLM provider key if configured
GEMINI_API_KEY	Optional	Fallback LLM provider key if configured

---

🔮 Roadmap

• SQLAlchemy Enterprise Bridge: Expand AST expressions directly to external database instances (PostgreSQL, Snowflake, BigQuery).
• Time-Series Forecasting: Integrate automated Prophet/ARIMA predictive models into agent graph nodes.
• RAG Integration: Combine unstructured text logs with tabular analytics.
• Voice Analytics: Add speech-to-text querying directly on the Streamlit dashboard.

---

🤝 Contributing

1. Fork the Repository
2. Create a Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for details.

---

📬 Contact & Support

• Live Demo: 🛡️ Agentic-Data-Intelligence
• GitHub: KesavaAI
• Linkedin: Linkedin
• Credly: Credly
• Portfolio: kesava-reddy.netlify.app
• Mail: kesavac913@gmail.com