595 lines
16 KiB
Markdown
595 lines
16 KiB
Markdown
# Minimal Pistn API Integration Plan for ServiceBot
|
|
|
|
**Date Created**: 2025-11-06
|
|
**Context**: ServiceBot integration with Pistn after Claude OS knowledge export is complete
|
|
**Category**: Architecture & Integration
|
|
**Status**: Planning - Not Yet Implemented
|
|
|
|
---
|
|
|
|
## Current State (November 2025)
|
|
|
|
### ✅ What's Complete:
|
|
1. **Claude OS Export System**: Generic knowledge export to SQLite (format v1.0)
|
|
2. **ServiceBot Knowledge Integration**: Embedded RAG engine with vector search
|
|
3. **ServiceBot MCP Servers**: 4 servers with 7 tools (currently using stubs)
|
|
4. **JavaScript Widget**: Production-ready chat modal for Pistn frontend
|
|
5. **Vision Documents**: Claude OS Family established
|
|
|
|
### ⚠️ What's Stubbed:
|
|
- `PistnAPIMCPServer.get_dealer_info()` - Returns fake dealer data
|
|
- `ServicesMCPServer.list_services()` - Returns hardcoded services
|
|
- `AppointmentsMCPServer.check_availability()` - Returns fake time slots
|
|
- `AppointmentsMCPServer.create_appointment()` - Doesn't actually create appointments
|
|
|
|
### 🎯 The Problem:
|
|
**Pistn has NO API endpoints.** ServiceBot can't:
|
|
- Get real dealer hours, contact info
|
|
- List actual services with real prices
|
|
- Check real appointment availability (uses Pistn's complex scheduling logic)
|
|
- Create actual appointments (uses Pistn's business rules, validations, callbacks)
|
|
|
|
---
|
|
|
|
## The Solution: Three-Phase Minimal API
|
|
|
|
Build a **minimal, secure API** in Pistn that ServiceBot can call to execute Pistn's business logic.
|
|
|
|
---
|
|
|
|
## Phase 1: Test ServiceBot with Knowledge Only (Do This First!)
|
|
|
|
**Goal**: Validate export + chat widget work before building API
|
|
|
|
**What to Test**:
|
|
1. Export knowledge from Claude OS
|
|
2. Import into ServiceBot
|
|
3. Add JavaScript widget to Pistn
|
|
4. Test knowledge-only conversations
|
|
|
|
**Commands**:
|
|
```bash
|
|
# In Claude OS
|
|
/claude-os-export dealer_123 --output ./exports
|
|
|
|
# Copy to ServiceBot
|
|
cp claude-os/exports/dealer_123_*.db servicebot/data/dealer_123.db
|
|
|
|
# Configure ServiceBot .env
|
|
KNOWLEDGE_DB_PATH=data/dealer_123.db
|
|
ENABLE_KNOWLEDGE_SEARCH=true
|
|
KNOWLEDGE_USE_EMBEDDINGS=true
|
|
OPENAI_API_KEY=your_key
|
|
|
|
# Deploy ServiceBot
|
|
cd servicebot
|
|
docker-compose up -d
|
|
|
|
# Add widget to Pistn layout
|
|
# (see implementation below)
|
|
```
|
|
|
|
**Test Conversations** (knowledge-only):
|
|
- "What are your hours?" ✅ (from knowledge base)
|
|
- "How long does an oil change take?" ✅ (from knowledge base)
|
|
- "What's your cancellation policy?" ✅ (from knowledge base)
|
|
- "I want to book an appointment" ⚠️ (will fail gracefully - no API yet)
|
|
|
|
**Success Criteria**:
|
|
- Widget loads on Pistn
|
|
- Knowledge queries work
|
|
- Responses stream properly
|
|
- Graceful degradation when tools not available
|
|
|
|
**Pistn Changes** (Minimal):
|
|
```ruby
|
|
# app/views/layouts/application.html.erb (or dealer layout)
|
|
<% if ENV['SERVICEBOT_ENABLED'] == 'true' %>
|
|
<script src="<%= ENV['SERVICEBOT_URL'] %>/static/servicebot-widget.js"></script>
|
|
<script>
|
|
ServiceBotWidget.init({
|
|
apiUrl: '<%= ENV['SERVICEBOT_URL'] %>',
|
|
dealerId: '<%= current_account.id if current_account.is_a?(DealerAccount) %>',
|
|
primaryColor: '<%= current_account.primary_bg if current_account.is_a?(DealerAccount) %>',
|
|
greeting: 'Hi! How can we help you today?'
|
|
});
|
|
</script>
|
|
<% end %>
|
|
```
|
|
|
|
**Duration**: 1-2 days (testing and validation)
|
|
|
|
---
|
|
|
|
## Phase 2: Add Minimal Read-Only API (After Phase 1 Works)
|
|
|
|
**Goal**: Replace stubs with real Pistn data (no writes yet)
|
|
|
|
### Implementation
|
|
|
|
#### 2.1: Create API Controller
|
|
|
|
```ruby
|
|
# pistn/app/controllers/api/v1/servicebot_controller.rb
|
|
module Api
|
|
module V1
|
|
class ServicebotController < ApplicationController
|
|
skip_before_action :verify_authenticity_token
|
|
before_action :authenticate_servicebot
|
|
|
|
# GET /api/v1/servicebot/dealers/:id
|
|
def dealer_info
|
|
dealer = DealerAccount.find(params[:id])
|
|
|
|
render json: {
|
|
id: dealer.id,
|
|
name: dealer.name,
|
|
address: dealer.full_address,
|
|
city: dealer.city,
|
|
state: dealer.state,
|
|
zip: dealer.zip,
|
|
phone: dealer.phone,
|
|
email: dealer.email,
|
|
hours: build_hours_hash(dealer)
|
|
}
|
|
rescue ActiveRecord::RecordNotFound
|
|
render json: { error: 'Dealer not found' }, status: 404
|
|
end
|
|
|
|
# GET /api/v1/servicebot/dealers/:dealer_id/services
|
|
def services
|
|
dealer = DealerAccount.find(params[:dealer_id])
|
|
|
|
# Adjust based on Pistn's actual service model
|
|
services = dealer.oil_change_services || []
|
|
|
|
render json: services.map { |service| {
|
|
id: service.id,
|
|
name: service.name,
|
|
description: service.description || '',
|
|
price: service.price,
|
|
duration_minutes: service.duration_minutes || 60
|
|
}}
|
|
end
|
|
|
|
private
|
|
|
|
def authenticate_servicebot
|
|
api_key = request.headers['X-ServiceBot-API-Key']
|
|
|
|
unless api_key.present? && api_key == ENV['SERVICEBOT_API_KEY']
|
|
render json: { error: 'Unauthorized' }, status: 401
|
|
end
|
|
end
|
|
|
|
def build_hours_hash(dealer)
|
|
# Adjust based on how Pistn stores hours
|
|
{
|
|
monday: dealer.monday_hours || 'Closed',
|
|
tuesday: dealer.tuesday_hours || 'Closed',
|
|
wednesday: dealer.wednesday_hours || 'Closed',
|
|
thursday: dealer.thursday_hours || 'Closed',
|
|
friday: dealer.friday_hours || 'Closed',
|
|
saturday: dealer.saturday_hours || 'Closed',
|
|
sunday: dealer.sunday_hours || 'Closed'
|
|
}
|
|
end
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
#### 2.2: Add Routes
|
|
|
|
```ruby
|
|
# pistn/config/routes.rb
|
|
namespace :api do
|
|
namespace :v1 do
|
|
scope :servicebot do
|
|
get 'dealers/:id', to: 'servicebot#dealer_info'
|
|
get 'dealers/:dealer_id/services', to: 'servicebot#services'
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
#### 2.3: Update ServiceBot MCP Servers
|
|
|
|
```python
|
|
# servicebot/app/mcp_servers/pistn_api.py
|
|
class PistnAPIMCPServer:
|
|
def __init__(self):
|
|
self.base_url = settings.PISTN_API_URL # e.g., http://localhost:3000
|
|
self.api_key = settings.PISTN_API_KEY
|
|
self.client = httpx.AsyncClient(
|
|
base_url=self.base_url,
|
|
headers={
|
|
"X-ServiceBot-API-Key": self.api_key,
|
|
"Content-Type": "application/json"
|
|
},
|
|
timeout=10.0
|
|
)
|
|
|
|
async def get_dealer_info(self, dealer_id: str) -> Dict[str, Any]:
|
|
"""Get real dealer data from Pistn API."""
|
|
try:
|
|
response = await self.client.get(f"/api/v1/servicebot/dealers/{dealer_id}")
|
|
response.raise_for_status()
|
|
return response.json()
|
|
except Exception as e:
|
|
logger.error(f"Failed to get dealer info: {e}")
|
|
# Fallback to stub for graceful degradation
|
|
return self._stub_dealer_info(dealer_id)
|
|
|
|
# servicebot/app/mcp_servers/services.py
|
|
class ServicesMCPServer:
|
|
async def list_services(self, dealer_id: str) -> Dict[str, Any]:
|
|
"""Get real services from Pistn API."""
|
|
try:
|
|
response = await self.pistn_client.get(
|
|
f"/api/v1/servicebot/dealers/{dealer_id}/services"
|
|
)
|
|
response.raise_for_status()
|
|
services = response.json()
|
|
|
|
return {
|
|
"success": True,
|
|
"services": services,
|
|
"count": len(services)
|
|
}
|
|
except Exception as e:
|
|
logger.error(f"Failed to get services: {e}")
|
|
return {"success": False, "services": [], "count": 0}
|
|
```
|
|
|
|
#### 2.4: Configuration
|
|
|
|
**Pistn `.env`**:
|
|
```bash
|
|
# ServiceBot Integration
|
|
SERVICEBOT_ENABLED=true
|
|
SERVICEBOT_URL=http://localhost:8000 # or production URL
|
|
SERVICEBOT_API_KEY=your_secure_random_key_here # Generate with: SecureRandom.hex(32)
|
|
```
|
|
|
|
**ServiceBot `.env`**:
|
|
```bash
|
|
# Pistn API Integration
|
|
PISTN_API_URL=http://localhost:3000 # or production Pistn URL
|
|
PISTN_API_KEY=same_key_as_above
|
|
```
|
|
|
|
**Test**:
|
|
```bash
|
|
# Test Pistn API directly
|
|
curl -H "X-ServiceBot-API-Key: your_key" \
|
|
http://localhost:3000/api/v1/servicebot/dealers/123
|
|
|
|
# Test in ServiceBot
|
|
# Should now return real dealer data instead of stubs
|
|
```
|
|
|
|
**Duration**: 2-3 days (implementation + testing)
|
|
|
|
---
|
|
|
|
## Phase 3: Add Appointment Booking (After Phase 2 Works)
|
|
|
|
**Goal**: Enable full appointment booking through ServiceBot
|
|
|
|
### 3.1: Identify Pistn's Appointment Logic
|
|
|
|
**Before implementing**, answer these questions:
|
|
- What model handles appointments? (e.g., `Appointment`, `ServiceAppointment`)
|
|
- What service/class creates appointments? (e.g., `AppointmentCreationService`)
|
|
- What validates availability? (e.g., `AppointmentAvailabilityService`, `BlockScheduler`)
|
|
- What are required fields? (customer info, vehicle, service, time)
|
|
- What validations exist? (blackout dates, capacity, dealer hours)
|
|
- What side effects happen? (emails, SMS, calendar updates)
|
|
|
|
### 3.2: Add Appointment Endpoints
|
|
|
|
```ruby
|
|
# pistn/app/controllers/api/v1/servicebot_controller.rb
|
|
|
|
# POST /api/v1/servicebot/dealers/:dealer_id/appointments/check_availability
|
|
def check_availability
|
|
dealer = DealerAccount.find(params[:dealer_id])
|
|
date = Date.parse(params[:date])
|
|
service_id = params[:service_id]
|
|
|
|
# Use existing Pistn service (adjust to actual service name)
|
|
availability = AppointmentAvailabilityService.new(
|
|
dealer: dealer,
|
|
date: date,
|
|
service_id: service_id
|
|
).call
|
|
|
|
render json: {
|
|
success: true,
|
|
date: date,
|
|
slots: availability.map { |slot| {
|
|
time: slot.time.iso8601,
|
|
available: slot.available,
|
|
capacity: slot.capacity
|
|
}}
|
|
}
|
|
rescue => e
|
|
render json: { success: false, error: e.message }, status: 422
|
|
end
|
|
|
|
# POST /api/v1/servicebot/dealers/:dealer_id/appointments
|
|
def create_appointment
|
|
dealer = DealerAccount.find(params[:dealer_id])
|
|
|
|
# Use existing Pistn service (adjust to actual service name)
|
|
result = AppointmentCreationService.new(
|
|
dealer: dealer,
|
|
customer_name: params[:customer_name],
|
|
customer_email: params[:customer_email],
|
|
customer_phone: params[:customer_phone],
|
|
service_id: params[:service_id],
|
|
appointment_time: Time.parse(params[:appointment_time]),
|
|
vehicle_year: params.dig(:vehicle, :year),
|
|
vehicle_make: params.dig(:vehicle, :make),
|
|
vehicle_model: params.dig(:vehicle, :model),
|
|
notes: params[:notes]
|
|
).call
|
|
|
|
if result.success?
|
|
render json: {
|
|
success: true,
|
|
appointment: {
|
|
id: result.appointment.id,
|
|
confirmation_number: result.appointment.confirmation_number,
|
|
scheduled_time: result.appointment.scheduled_time.iso8601
|
|
}
|
|
}
|
|
else
|
|
render json: {
|
|
success: false,
|
|
errors: result.errors
|
|
}, status: 422
|
|
end
|
|
rescue => e
|
|
render json: { success: false, error: e.message }, status: 500
|
|
end
|
|
```
|
|
|
|
### 3.3: Add Routes
|
|
|
|
```ruby
|
|
# pistn/config/routes.rb
|
|
namespace :api do
|
|
namespace :v1 do
|
|
scope :servicebot do
|
|
# ... existing routes ...
|
|
post 'dealers/:dealer_id/appointments/check_availability',
|
|
to: 'servicebot#check_availability'
|
|
post 'dealers/:dealer_id/appointments',
|
|
to: 'servicebot#create_appointment'
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
### 3.4: Update ServiceBot MCP Server
|
|
|
|
```python
|
|
# servicebot/app/mcp_servers/appointments.py
|
|
class AppointmentsMCPServer:
|
|
async def check_availability(
|
|
self,
|
|
dealer_id: str,
|
|
date: str,
|
|
service_id: Optional[str] = None
|
|
) -> Dict[str, Any]:
|
|
"""Check real appointment availability via Pistn API."""
|
|
try:
|
|
response = await self.pistn_client.post(
|
|
f"/api/v1/servicebot/dealers/{dealer_id}/appointments/check_availability",
|
|
json={"date": date, "service_id": service_id}
|
|
)
|
|
response.raise_for_status()
|
|
return response.json()
|
|
except Exception as e:
|
|
logger.error(f"Availability check failed: {e}")
|
|
return {"success": False, "error": str(e)}
|
|
|
|
async def create_appointment(
|
|
self,
|
|
dealer_id: str,
|
|
customer_name: str,
|
|
customer_email: str,
|
|
customer_phone: str,
|
|
service_id: str,
|
|
appointment_time: str,
|
|
vehicle: Dict[str, str],
|
|
notes: Optional[str] = None
|
|
) -> Dict[str, Any]:
|
|
"""Create real appointment via Pistn API."""
|
|
try:
|
|
response = await self.pistn_client.post(
|
|
f"/api/v1/servicebot/dealers/{dealer_id}/appointments",
|
|
json={
|
|
"customer_name": customer_name,
|
|
"customer_email": customer_email,
|
|
"customer_phone": customer_phone,
|
|
"service_id": service_id,
|
|
"appointment_time": appointment_time,
|
|
"vehicle": vehicle,
|
|
"notes": notes
|
|
}
|
|
)
|
|
response.raise_for_status()
|
|
return response.json()
|
|
except Exception as e:
|
|
logger.error(f"Appointment creation failed: {e}")
|
|
return {"success": False, "error": str(e)}
|
|
```
|
|
|
|
**Duration**: 3-5 days (complex, needs thorough testing)
|
|
|
|
---
|
|
|
|
## Security Considerations
|
|
|
|
### API Key Generation
|
|
```ruby
|
|
# Generate secure API key
|
|
SecureRandom.hex(32)
|
|
# => "a1b2c3d4e5f6..."
|
|
```
|
|
|
|
### Rate Limiting (Optional but Recommended)
|
|
```ruby
|
|
# Gemfile
|
|
gem 'rack-attack'
|
|
|
|
# config/initializers/rack_attack.rb
|
|
Rack::Attack.throttle('servicebot/ip', limit: 100, period: 1.minute) do |req|
|
|
if req.path.start_with?('/api/v1/servicebot')
|
|
req.ip
|
|
end
|
|
end
|
|
```
|
|
|
|
### HTTPS in Production
|
|
- ServiceBot MUST use HTTPS (WebSocket requires it)
|
|
- Pistn API should use HTTPS for security
|
|
- Set `PISTN_API_URL=https://pistn.yourdomain.com` in production
|
|
|
|
---
|
|
|
|
## Testing Strategy
|
|
|
|
### Phase 1 Testing
|
|
- [ ] Export knowledge from Claude OS
|
|
- [ ] Import into ServiceBot successfully
|
|
- [ ] Widget loads on Pistn page
|
|
- [ ] Can ask knowledge questions
|
|
- [ ] Streaming responses work
|
|
- [ ] Conversation persists in localStorage
|
|
|
|
### Phase 2 Testing
|
|
- [ ] API authentication works
|
|
- [ ] Can get real dealer info
|
|
- [ ] Can list real services
|
|
- [ ] Graceful fallback if API fails
|
|
- [ ] Error handling works
|
|
|
|
### Phase 3 Testing
|
|
- [ ] Can check availability for real dates
|
|
- [ ] Can create actual appointments
|
|
- [ ] Appointments appear in Pistn dashboard
|
|
- [ ] Customer receives confirmation
|
|
- [ ] All validations work (capacity, hours, etc.)
|
|
- [ ] Error messages are user-friendly
|
|
|
|
---
|
|
|
|
## Deployment Checklist
|
|
|
|
### ServiceBot Deployment
|
|
- [ ] Docker container running
|
|
- [ ] Knowledge DB imported
|
|
- [ ] HTTPS/SSL configured
|
|
- [ ] CORS configured for Pistn domain
|
|
- [ ] Environment variables set
|
|
- [ ] Widget file served at `/static/servicebot-widget.js`
|
|
|
|
### Pistn Deployment
|
|
- [ ] API controller added
|
|
- [ ] Routes configured
|
|
- [ ] API key set in `.env`
|
|
- [ ] Widget script added to layout
|
|
- [ ] ServiceBot enabled flag set
|
|
- [ ] CORS headers configured (if needed)
|
|
|
|
---
|
|
|
|
## Monitoring & Maintenance
|
|
|
|
### Logs to Watch
|
|
**ServiceBot**:
|
|
- WebSocket connections
|
|
- MCP tool calls
|
|
- API call failures
|
|
- Knowledge query performance
|
|
|
|
**Pistn**:
|
|
- ServiceBot API requests
|
|
- Authentication failures
|
|
- Appointment creation errors
|
|
|
|
### Metrics to Track
|
|
- Conversations started
|
|
- Messages sent
|
|
- Knowledge queries performed
|
|
- Appointments booked via chat
|
|
- API response times
|
|
- Error rates
|
|
|
|
---
|
|
|
|
## Future Enhancements
|
|
|
|
### Post-MVP Features
|
|
- [ ] Customer authentication (lookup by email/phone)
|
|
- [ ] Appointment rescheduling
|
|
- [ ] Appointment cancellation
|
|
- [ ] Service history lookup
|
|
- [ ] Vehicle history integration
|
|
- [ ] Multi-language support
|
|
- [ ] Voice integration
|
|
- [ ] SMS integration
|
|
|
|
### Knowledge Base Updates
|
|
- [ ] Sync `enhanced_documentation_service.rb` knowledge to Claude OS
|
|
- [ ] Regular export/import workflow
|
|
- [ ] Automated knowledge updates
|
|
|
|
---
|
|
|
|
## Rollback Plan
|
|
|
|
If something breaks:
|
|
|
|
1. **Phase 1 Issues**: Disable widget
|
|
```ruby
|
|
# .env
|
|
SERVICEBOT_ENABLED=false
|
|
```
|
|
|
|
2. **Phase 2 Issues**: ServiceBot falls back to stubs automatically
|
|
|
|
3. **Phase 3 Issues**: Disable appointment booking tool
|
|
```python
|
|
# servicebot/app/mcp_servers/appointments.py
|
|
self.enabled = False
|
|
```
|
|
|
|
---
|
|
|
|
## Key Takeaways
|
|
|
|
✅ **Start minimal** - Test knowledge-only first
|
|
✅ **Phased approach** - Build API incrementally
|
|
✅ **Reuse Pistn logic** - Don't duplicate business rules
|
|
✅ **Graceful degradation** - Stubs as fallbacks
|
|
✅ **Security first** - API key authentication
|
|
✅ **Test thoroughly** - Each phase validated before next
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [ServiceBot README](servicebot/README.md)
|
|
- [Pistn Integration Guide](servicebot/integrations/PISTN_INTEGRATION.md)
|
|
- [Knowledge Integration](servicebot/docs/KNOWLEDGE_INTEGRATION.md)
|
|
- [Claude OS Family](claude-os/docs/CLAUDE_OS_FAMILY.md)
|
|
- [Export Format Spec](claude-os/docs/EXPORT_FORMAT_SPEC.md)
|
|
|
|
---
|
|
|
|
**Next Action**: Run Phase 1 to test ServiceBot with knowledge-only conversations!
|