ESF Nursery Assistant v2.0

AI-powered management system for El Sobrante Family Nursery with enhanced features including RAG-based knowledge search, natural language CRM queries, meeting action extraction, daily AI briefings, and cost tracking.

Features

1. Knowledge Base RAG (Retrieval-Augmented Generation)

• Semantic SOP Search: Uses Google Gemini embeddings for intelligent document search
• Chunked Documents: SOPs split into 800-char chunks with 200-char overlap
• Context-Aware Answers: AI responses cite specific SOP sections
• Auto-Ingestion: SOPs auto-ingested on startup from ESF_SOP_Framework_Sample.md

2. Natural Language CRM Access

• Plain English Queries: Staff can ask questions like "Find Jane Smith's emergency contacts"
• Supported Queries:
  • "Show children with peanut allergies"
  • "List employees with CPR expiring next month"
  • "Count enrolled children in preschool"
  • "Who hasn't submitted portfolio this month?"
  • "Show all illness exclusions ending this week"
• Read-Only Safety: All queries are read-only by default
• AI-Powered SQL Generation: Falls back to AI when pattern matching fails

3. Meeting Action Item Extractor

• Transcript Analysis: Paste meeting transcripts to extract action items
• AI Extraction: Identifies tasks, assignees, due dates, and priority
• Employee Matching: Auto-matches assignees to employee database
• Approval Workflow: Director reviews and approves before task creation
• Telegram Notifications: Auto-notifies assignees when tasks created

4. Daily Nursery Briefing

• Automated Summary: Generated daily at 8 AM with AI insights
• Multi-Persona Review: Simulated perspectives from Compliance Officer, Operations Manager, and Teacher
• Health Score: 0-100 nursery health rating with prioritized recommendations
• Data Signals:
  • Enrollment pipeline status
  • Compliance alerts
  • Portfolio deadlines
  • ASQ tracking
  • Illness exclusions
  • Parent message volume
• Multi-Channel Delivery: Telegram message + email backup

5. Cost Tracking

• API Usage Logging: Tracks every OpenRouter API call
• Pricing Table: Supports free and paid models with accurate cost calculation
• Reporting Endpoints:
  • /api/costs/summary - Total costs by period
  • /api/costs/by-model - Usage per model
  • /api/costs/by-task - Costs per task type
  • /api/costs/trend - Daily spending chart
• Dashboard Widget: Real-time cost tracking with optimization suggestions

New Database Tables

sop_chunks

Stores RAG chunks with embeddings for semantic search

- id, content, source_title, source_section
- chunk_index, embedding (JSON), created_at

tasks

Action items extracted from meetings

- id, title, description, priority, status
- assignee_id, created_by, meeting_date
- due_date, notification_sent, created_at

api_usage

Cost tracking logs for every API call

- id, timestamp, model, task_type
- input_tokens, output_tokens, cost_estimate
- query_preview, response_status, user_id

briefing_history

Daily briefing records with AI analysis

- id, briefing_date, health_score, signals (JSON)
- recommendations (JSON), full_text
- telegram_sent, email_sent

illness_exclusions

Track illness exclusions with return dates

- id, child_id, symptom_onset_date, symptoms
- earliest_return_date, is_active, doctor_note_required

API Endpoints

RAG (Semantic Search)

• POST /rag/ingest - Ingest SOP document into chunks
• POST /rag/search - Perform semantic search

AI Chatbot

• POST /ai/ask - Legacy keyword-based search
• POST /ai/ask-rag - RAG-powered semantic search with citations

Natural Language Queries

• POST /nl-query - Execute natural language query
• POST /nl-query/execute - Execute with confirmation for updates

Meeting Extractor

• POST /meeting/extract - Extract action items from transcript
• POST /meeting/create-tasks - Create approved tasks

Tasks

• GET /tasks - List tasks with filtering
• GET /tasks/{id} - Get specific task
• PUT /tasks/{id} - Update task status
• GET /employees/{id}/tasks - Get employee's tasks

Daily Briefing

• POST /briefing/generate - Generate briefing preview
• POST /briefing/send - Generate and save briefing
• GET /briefing/today - Get today's briefing
• GET /briefing/history - Get briefing history

Cost Tracking

• GET /costs/summary?period=month - Cost summary
• GET /costs/by-model - Breakdown by model
• GET /costs/by-task - Breakdown by task
• GET /costs/trend - Daily trend chart
• GET /costs/current-month - Current month summary

Enhanced Employee Endpoints

• GET /employees/search/{name} - Search by name
• GET /employees/{id}/tasks - Get employee tasks

Enhanced Child Endpoints

• GET /children/search/{name} - Search by name
• GET /children/with-allergies - Get children with allergies
• GET /children/{id}/emergency-contacts - Get emergency contacts

Portfolio

• GET /portfolios/stats/{month_year} - Get completion statistics

Enrollment

• GET /enrollment/pipeline - Get pipeline statistics

Illness Exclusions

• POST /illness-exclusions - Create exclusion record
• GET /illness-exclusions/active - Get active exclusions
• GET /illness-exclusions/ending-this-week - Get returning children

Environment Variables

# Required
OPENROUTER_API_KEY=your_openrouter_key

# Optional
GEMINI_API_KEY=your_gemini_key_for_embeddings  # Falls back to mock embeddings if not set
DATABASE_URL=sqlite:///./esf_nursery.db  # Default SQLite
UPLOAD_DIR=./uploads  # File upload directory

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Set environment variables:

export OPENROUTER_API_KEY="your_key"
export GEMINI_API_KEY="your_key"  # Optional, for embeddings

3. Start the backend:

cd /tmp/esf-python-assistant
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

4. Start the frontend:

cd /tmp/esf-python-assistant/frontend
streamlit run app.py

Usage

Using RAG Search

1. Navigate to "🤖 SOP Chatbot"
2. Ask questions naturally
3. View cited sources in the response

Natural Language Queries

1. Navigate to "💬 Natural Language Query"
2. Type questions in plain English
3. Click example queries for quick access
4. View results formatted as tables

Meeting Extractor

1. Navigate to "📝 Meeting Extractor"
2. Paste meeting transcript
3. Review AI-extracted action items
4. Approve items and create tasks
5. Staff receive Telegram notifications

Daily Briefing

1. Navigate to "⚙️ Admin Dashboard" → "📋 Daily Briefing"
2. Click "Generate Preview" to see AI analysis
3. Review health score and recommendations
4. Click "Generate & Save" to send via Telegram/email

Cost Tracking

1. Navigate to "⚙️ Admin Dashboard" → "💰 Cost Tracking"
2. View current month costs and trends
3. Check optimization suggestions
4. Monitor usage by model and task type

Frontend Pages

• app.py - Main entry with portal selection
• pages/admin_dashboard.py - Admin with cost tracking & briefing
• pages/employee_portal.py - Employee onboarding & training
• pages/parent_portal.py - Parent enrollment & messaging
• pages/chatbot.py - RAG-enhanced SOP chatbot
• pages/natural_language.py - Natural language CRM queries NEW
• pages/meeting_extractor.py - Meeting action extraction NEW

Services

• services/rag_service.py - Semantic search with embeddings
• services/ai_service.py - AI chat with RAG integration
• services/nl_query_service.py - Natural language to SQL
• services/meeting_extractor.py - Transcript analysis
• services/daily_briefing.py - AI-powered daily summaries
• services/cost_tracker.py - API usage and cost tracking
• services/compliance.py - Compliance alerts and checks

Security Considerations

• All NL queries are read-only by default
• SQL injection protection via parameterized queries
• Confirmation required for any update operations
• API keys stored in environment variables
• File uploads limited to specific directories

Model Pricing Reference

Model	Input (per 1M)	Output (per 1M)
meta-llama/llama-3.3-70b-instruct:free	$0.00	$0.00
openai/gpt-3.5-turbo	$0.50	$1.50
openai/gpt-4o-mini	$0.15	$0.60
anthropic/claude-3-haiku	$0.25	$1.25
google/gemini-flash-1.5	$0.075	$0.30

Changelog

v2.0.0

• Added RAG (Retrieval-Augmented Generation) for semantic SOP search
• Added Natural Language CRM Access with AI-powered SQL generation
• Added Meeting Action Item Extractor
• Added Daily Nursery Briefing with AI analysis
• Added Cost Tracking for OpenRouter API usage
• Added new database tables: sop_chunks, tasks, api_usage, briefing_history, illness_exclusions
• Enhanced admin dashboard with cost tracking and briefing widgets
• New frontend pages: Natural Language Query, Meeting Extractor

License

Proprietary - El Sobrante Family Nursery