AgenticAI POC - Intelligent Global Search System

A comprehensive AI-powered application that combines a React frontend with a FastAPI backend and LangChain agentic AI for intelligent data retrieval and natural language interaction with order and project management systems.

🚀 Features

AI Agent Capabilities

Azure OpenAI Integration - Powered by GPT-4 for intelligent query processing
Dual-Mode Architecture - Supports both GraphQL API and local SQLite database
Tool-Based Architecture - Custom tools for orders, projects, and global search
Natural Language Processing - Convert user queries to structured database queries
Full-Text Search - FTS5-powered global search across all data
Rich Text Responses - Markdown-formatted, human-readable outputs
Single Tool Call Optimization - Efficient query execution with recursion management

Frontend (React)

Modern Chat Interface - Clean, responsive design
Rich Text Display - Markdown rendering with syntax highlighting
Real-time Communication - Instant responses from AI agent
Error Handling - Graceful error display and user feedback
Loading States - Visual indicators for better UX

Backend (FastAPI)

RESTful API - Clean endpoints for AI agent interaction
CORS Support - Cross-origin requests enabled
Environment Configuration - Secure credential management
Comprehensive Logging - Detailed request/response tracking
Error Handling - Robust exception management

Data Integration

Dual Data Sources
- GraphQL API - External order/project management system (Port 3000)
- SQLite Database - Local database with FTS5 full-text search
Flexible Query Generation - Dynamic GraphQL and SQL query construction
Full-Text Search - FTS5 indexing for projects and orders
Data Formatting - Convert raw data to user-friendly format
Authentication - Secure API token management

🏗️ Architecture

┌─────────────────┐    HTTP/REST    ┌─────────────────┐    GraphQL    ┌─────────────────┐
│   React Client  │ ───────────────▶│  FastAPI Server │ ─────────────▶│   GraphQL API   │
│   (Port 4000)   │                 │   (Port 8000)   │               │  (Port 3000)    │
│                 │                 │                 │               │                 │
│ • Chat UI       │                 │ • AI Agent      │               │ • Orders Data   │
│ • Markdown      │                 │ • Tool Calling  │               │ • Projects Data │
│ • Rich Text     │                 │ • Azure OpenAI  │               │ • Authentication│
└─────────────────┘                 └─────────────────┘               └─────────────────┘
                                             │                                 
                                             │ SQLite                          
                                             ▼                                 
                                    ┌─────────────────┐                       
                                    │  Local Database │                       
                                    │                 │                       
                                    │ • SQLite + FTS5 │                       
                                    │ • Orders (v1)   │                       
                                    │ • Projects (v1) │                       
                                    │ • Clients       │                       
                                    │ • Global Search │                       
                                    └─────────────────┘

📁 Project Structure

ai-chatbot/
├── 🎨 client/                    # React Frontend Application
│   ├── public/                   # Static assets
│   │   ├── index.html           # HTML entry point
│   │   ├── manifest.json        # PWA manifest
│   │   └── robots.txt           # SEO robots file
│   ├── src/
│   │   ├── App.js               # Main chat interface
│   │   ├── App.css              # Styling with markdown support
│   │   ├── index.js             # React entry point
│   │   ├── index.css            # Global styles
│   │   ├── reportWebVitals.js   # Performance monitoring
│   │   └── setupTests.js        # Test configuration
│   ├── package.json             # Node.js dependencies
│   └── README.md                # Client documentation
│
├── ⚙️ src/                       # Python Backend Application
│   ├── 🤖 ai_agent.py           # Main AI agent with Azure OpenAI
│   ├── 🤖 ai_agent_v1.py        # SQLite-based AI agent (local DB)
│   ├── 🚀 main.py               # FastAPI application entry point
│   ├── 💾 db_setup.py           # SQLite database initialization & FTS5 setup
│   │
│   ├── ⚙️ config/               # Configuration
│   │   └── constants.py         # API tokens and constants
│   │
│   ├── 📋 models/               # Data models
│   │   └── ask_request_state.py # Request/response schemas
│   │
│   ├── 🛣️ routes/               # API endpoints
│   │   └── ask.py               # /ask endpoint for AI queries
│   │
│   ├── 🔧 services/             # Business logic layer
│   │   ├── order_service.py     # Order data (GraphQL-based)
│   │   ├── order_service_v1.py  # Order data (SQLite-based)
│   │   ├── project_service.py   # Project data (GraphQL-based)
│   │   ├── project_service_v1.py # Project data (SQLite-based)
│   │   └── global_search_service.py # FTS5 full-text search
│   │
│   ├── 🛠️ tools/                # AI Agent Tools
│   │   ├── get_orders.py        # GraphQL order retrieval tool
│   │   ├── get_orders_v1.py     # SQLite order retrieval tool
│   │   ├── get_projects.py      # GraphQL project retrieval tool
│   │   ├── get_projects_v1.py   # SQLite project retrieval tool
│   │   ├── global_search_v1.py  # Global search tool (FTS5)
│   │   └── __init__.py          # Tool exports
│   │
│   └── 🔍 utils/                # Utility functions
│       └── logger.py            # Colored logging configuration
│
├── 💾 local_data.db             # SQLite database (auto-generated)
├── 🔐 .env                      # Environment variables (secure)
├── 📝 .env.example              # Environment template
├── 📋 requirements.txt          # Python dependencies
└── 📖 README.md                 # This documentation

🔧 Technology Stack

Backend

Python 3.8+ - Core language
FastAPI - Modern, fast web framework
LangChain - AI agent framework
LangGraph - Agent orchestration with memory
Azure OpenAI - Language model provider (GPT-4)
SQLite - Local database with FTS5 full-text search
Pydantic - Data validation
Uvicorn - ASGI server
Requests - HTTP client for GraphQL API

Frontend

React 19.1.0 - UI framework
ReactMarkdown 10.1.0 - Rich text rendering
Sass 1.89.2 - CSS preprocessing
CSS3 - Modern styling
JavaScript ES6+ - Modern JavaScript
BotUI - Chat interface components

AI & Data

GPT-4 - Language model
GraphQL - API query language
Structured Tools - Custom AI tools
Markdown - Rich text formatting

🚀 Quick Start

Prerequisites

Python 3.8+
Node.js 16+
Yarn or npm
Valid Azure OpenAI API key
GraphQL API access credentials

1. Backend Setup

# Clone and navigate to project
git clone <repo-url>
cd ai-chatbot

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Initialize local database (optional - for v1 tools)
python src/db_setup.py

2. Frontend Setup

# Navigate to client directory
cd client

# Install dependencies
yarn install
# or: npm install

# Start development server
yarn start
# or: npm start

3. Start the Application

Terminal 1 - Backend:

cd ai-chatbot
python -m uvicorn src.main:app --reload --port 8000

Terminal 2 - Frontend:

cd ai-chatbot/client
yarn start

Optional - Local GraphQL Server (for testing):

# If you have a local GraphQL server
cd <graphql-server-directory>
# Start server on port 3000

Access the application:

🔑 Environment Configuration

Create a .env file with the following variables:

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=your_azure_openai_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-01
AZURE_OPENAI_API_DEPLOYMENT_NAME=gpt-4

# Optional: Search capabilities
TAVILY_API_KEY=your_tavily_search_key

# GraphQL API Authentication (optional - for GraphQL tools)
AUTH_TOKEN=your_graphql_api_token

📡 API Endpoints

Method	Endpoint	Description	Request Body
`GET`	`/health`	Health check	None
`POST`	`/ask`	AI agent query	`AskRequestState`

Ask Endpoint Schema:

{
  "model_name": "gpt-4",
  "query": "Find orders with status OPEN",
  "system_prompt": "Act as an AI assistant",
  "allow_search": false,
  "thread_id": null
}

🤖 AI Agent Tools

GraphQL-Based Tools

get_orders Tool

Purpose: Retrieve order information from external GraphQL API
Input: Variables object with search parameters
Output: Formatted order details with status, addresses, dates
Features: Custom queries, minimal field selection, human-readable responses
Endpoint: http://localhost:3000/verse-graphql

get_projects Tool

Purpose: Retrieve project information from external GraphQL API
Input: Variables object with search parameters
Output: Formatted project details with names, clients, status
Features: Custom queries, minimal field selection, human-readable responses
Endpoint: http://localhost:3000/verse-graphql

SQLite-Based Tools (v1)

get_orders_v1 Tool

Purpose: Retrieve order information from local SQLite database
Input: Query filters (status, file number, date range)
Output: Formatted order details from local database
Features: Fast local queries, no external dependencies

get_projects_v1 Tool

Purpose: Retrieve project information from local SQLite database
Input: Query filters (status, group number, client)
Output: Formatted project details from local database
Features: Fast local queries, no external dependencies

global_search_v1 Tool

Purpose: Perform full-text search across all projects and orders
Input: Space-separated search terms
Output: Combined results from both projects and orders
Features: FTS5-powered search, prefix matching, LIKE fallback
Indexed Fields: Project names, group numbers, order file numbers, addresses

💬 Example Queries

Order Queries

✅ "Find 3 latest orders with status OPEN"
✅ "Get the address for order END8726423"
✅ "What's the status of order END6527461?"
✅ "Show me orders from Los Angeles county"
✅ "Find orders closing this month"
✅ "Search for orders in California"

Project Queries

✅ "List all open projects"
✅ "Find projects for Client 5"
✅ "Show me project details for group number P12345678"
✅ "What projects are in cancelled status?"
✅ "Find the newest projects"

Global Search Queries

✅ "Search for Springfield across all data"
✅ "Find anything related to P12345678"
✅ "Search for END7654321 and get all related info"
✅ "Look for Client projects and orders"

🗄️ Local Database Setup

The project includes a SQLite database with FTS5 (Full-Text Search) capabilities for local testing and development.

Database Schema

Tables:

client - Client information (id, name)
projects - Project records (id, name, groupNumber, status, client_id, createdAt, updatedAt)
orders - Order records (id, fileNum, displayStatus, status, address, createdAt, updatedAt)
projects_fts - FTS5 virtual table for project search (name, groupNumber)
orders_fts - FTS5 virtual table for order search (fileNum, address)

Sample Data Generation

The db_setup.py script generates:

20 dummy clients
100 projects with random statuses (open/cancelled)
100 orders with random statuses and addresses
FTS5 indexes for fast full-text search

Initialize Database

python src/db_setup.py

This will create local_data.db in the project root with all tables, indexes, and sample data.

Search Capabilities

The FTS5 implementation supports:

Prefix matching - Find terms starting with specific text
Multi-term search - Search for multiple keywords simultaneously
LIKE fallback - Substring matching when FTS doesn't match
Deduplication - Combined results from both search methods

🎨 Rich Text Features

The application supports markdown formatting for enhanced readability:

📋 Headers - Section organization
🔸 Bold text - Important information highlighting
📝 Lists - Organized data presentation
💻 Code blocks - Technical details
📌 Blockquotes - Important notes
🎯 Structured formatting - Clean, professional appearance

🔍 Development Features

Logging

Colored output - Easy debugging
Request tracking - Full request/response logging
Error details - Comprehensive error information
Tool execution - GraphQL query and response logging

Error Handling

Graceful degradation - Fallback responses
User-friendly messages - Clear error communication
Recursion management - Prevents infinite loops
Network resilience - Handles API failures

Performance

Single tool calls - Optimized query execution
Efficient GraphQL - Minimal field selection
Response caching - Memory-based conversation state
Fast responses - Optimized processing pipeline

🚨 Troubleshooting

Common Issues

Backend not starting:

# Check Python version
python --version

# Verify virtual environment
pip list

# Check environment variables
python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.getenv('AZURE_OPENAI_API_KEY'))"

Frontend not loading:

# Clear cache
yarn cache clean

# Reinstall dependencies
rm -rf node_modules yarn.lock
yarn install

# Check port conflicts
netstat -ano | findstr :4000

AI agent errors:

Verify Azure OpenAI credentials
Check GraphQL API connectivity
Review recursion limit settings
Validate tool schemas

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
client		client
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

AgenticAI POC - Intelligent Global Search System

🚀 Features

AI Agent Capabilities

Frontend (React)

Backend (FastAPI)

Data Integration

🏗️ Architecture

📁 Project Structure

🔧 Technology Stack

Backend

Frontend

AI & Data

🚀 Quick Start

Prerequisites

1. Backend Setup

2. Frontend Setup

3. Start the Application

🔑 Environment Configuration

📡 API Endpoints

Ask Endpoint Schema:

🤖 AI Agent Tools

GraphQL-Based Tools

get_orders Tool

get_projects Tool

SQLite-Based Tools (v1)

get_orders_v1 Tool

get_projects_v1 Tool

global_search_v1 Tool

💬 Example Queries

Order Queries

Project Queries

Global Search Queries

🗄️ Local Database Setup

Database Schema

Sample Data Generation

Initialize Database

Search Capabilities

🎨 Rich Text Features

🔍 Development Features

Logging

Error Handling

Performance

🚨 Troubleshooting

Common Issues

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages