FRONTEND_INTEGRATION.md•7.75 kB
# Frontend Integration Guide: Core Smart Search
## Overview
Your Core Smart Search Answer Method (`services/smart_search.py:42`) is now available via HTTP API at **http://localhost:8002**
## Quick Start
### 1. API Endpoint
```
POST http://localhost:8002/api/smart-search
```
### 2. Request Format
```json
{
"question": "What tables are available in the database?",
"database": "db3", // Optional: db1, db2, db3
"include_sql": true, // Optional: include SQL queries
"include_semantic": true, // Optional: include semantic search
"include_schema": true // Optional: include schema info
}
```
### 3. Response Format
```json
{
"success": true,
"question": "What tables are available in the database?",
"database": "db3",
"answer_markdown": "## Database Structure\n\nDatabase contains 17 tables...",
"strategy": "schema_only",
"sql_queries": [],
"semantic_results": [],
"sources_used": {"sql_queries": 0, "documents": 0, "tables": 0},
"processing_time": 0.21,
"error": null
}
```
## React Integration Examples
### Basic Hook
```jsx
import { useState } from 'react';
function useSmartSearch() {
const [loading, setLoading] = useState(false);
const [result, setResult] = useState(null);
const [error, setError] = useState(null);
const search = async (question, options = {}) => {
setLoading(true);
setError(null);
try {
const response = await fetch('http://localhost:8002/api/smart-search', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
question,
database: options.database || 'db3',
include_sql: options.include_sql ?? true,
include_semantic: options.include_semantic ?? true,
include_schema: options.include_schema ?? true
})
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.detail || 'Search failed');
}
setResult(data);
return data;
} catch (err) {
setError(err.message);
throw err;
} finally {
setLoading(false);
}
};
return { search, loading, result, error };
}
```
### Smart Search Component
```jsx
import React, { useState } from 'react';
import ReactMarkdown from 'react-markdown';
function SmartSearchComponent() {
const { search, loading, result, error } = useSmartSearch();
const [question, setQuestion] = useState('');
const handleSearch = async (e) => {
e.preventDefault();
if (!question.trim()) return;
try {
await search(question);
} catch (err) {
console.error('Search failed:', err);
}
};
return (
<div className="smart-search">
<form onSubmit={handleSearch}>
<input
type="text"
value={question}
onChange={(e) => setQuestion(e.target.value)}
placeholder="Ask about your database..."
disabled={loading}
/>
<button type="submit" disabled={loading || !question.trim()}>
{loading ? 'Searching...' : 'Search'}
</button>
</form>
{error && (
<div className="error">
Error: {error}
</div>
)}
{result && (
<div className="result">
<div className="metadata">
<span>Strategy: {result.strategy}</span>
<span>Time: {result.processing_time.toFixed(2)}s</span>
<span>Database: {result.database}</span>
</div>
<div className="answer">
<ReactMarkdown>{result.answer_markdown}</ReactMarkdown>
</div>
{result.sql_queries.length > 0 && (
<div className="sql-queries">
<h3>SQL Queries Used:</h3>
{result.sql_queries.map((query, i) => (
<pre key={i}><code>{query.sql}</code></pre>
))}
</div>
)}
</div>
)}
</div>
);
}
```
### Advanced Service Class
```javascript
class SmartSearchService {
constructor(baseUrl = 'http://localhost:8002') {
this.baseUrl = baseUrl;
}
async search(question, options = {}) {
const response = await fetch(`${this.baseUrl}/api/smart-search`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
question,
database: options.database || 'db3',
include_sql: options.include_sql ?? true,
include_semantic: options.include_semantic ?? true,
include_schema: options.include_schema ?? true
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || 'Search failed');
}
return await response.json();
}
async getDatabases() {
const response = await fetch(`${this.baseUrl}/api/databases`);
return await response.json();
}
async healthCheck() {
const response = await fetch(`${this.baseUrl}/health`);
return await response.json();
}
}
// Usage
const searchService = new SmartSearchService();
const result = await searchService.search("What tables exist?");
```
## Available Databases
- **db1**: `postgresql://admin:password@192.168.230.101/defaultdb`
- **db2**: `postgresql://admin:password@192.168.230.102/defaultdb`
- **db3**: `postgresql://postgres:postgres@localhost/postgres` (default)
## Additional Endpoints
### API Information
```bash
GET http://localhost:8002/api/info
# Returns API details, endpoints, databases, and features
```
### Available Models
```bash
GET http://localhost:8002/api/models
# Returns available models for compatibility
```
### Health Check
```bash
GET http://localhost:8002/health
# Returns API health status
```
## API Features
### Core Capabilities
✅ **Question Classification**: Automatically determines best search strategy
✅ **Multi-Strategy Search**: SQL, semantic, hybrid, or schema-only approaches
✅ **Markdown Responses**: Rich formatted answers ready for display
✅ **Performance Tracking**: Processing time and source usage metrics
✅ **Error Handling**: Comprehensive error responses with details
### Search Strategies
- **SQL**: Direct database queries for structured data
- **Semantic**: Vector similarity search for contextual results
- **Schema**: Database structure and metadata analysis
- **Hybrid**: Combination of multiple approaches for complex queries
## Production Considerations
### CORS Configuration
Add CORS middleware if frontend is on different domain:
```python
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000"], # Your React app
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
### Error Handling
Always handle network errors and API failures:
```javascript
try {
const result = await searchService.search(question);
} catch (error) {
if (error.message.includes('Failed to fetch')) {
// Network error - API server down
showError('Search service unavailable');
} else {
// API error - show specific message
showError(error.message);
}
}
```
### Performance Optimization
- Cache search results for repeated queries
- Debounce user input to avoid excessive API calls
- Show loading states for better UX
- Consider pagination for large result sets
## Testing the API
### Health Check
```bash
curl http://localhost:8002/health
```
### List Databases
```bash
curl http://localhost:8002/api/databases
```
### Search Example
```bash
curl -X POST http://localhost:8002/api/smart-search \
-H "Content-Type: application/json" \
-d '{"question": "How many records are in each table?"}'
```
Your Core Smart Search is now ready for frontend integration! 🎉