## 1. Overview

Auto-Train là hệ thống tự động cập nhật prompt rules từ user feedback. Đây là pipeline end-to-end:

Feedback → AI Analysis → Rule Suggestion → Admin Review → Deploy → Production

## 2. Architecture Flow

Diagram not found. Please regenerate with generate_autotrain_diagram.py'">

## 3. Database Schema

### feedbacks table

Column | Type | Description
--- | --- | ---
`id` | INT PK | Auto-increment primary key
`feedback_id` | TEXT UNIQUE | External ID (FB-XXXX)
`user_id` | TEXT | User identifier
`query` | TEXT | Original user query
`ai_response` | TEXT | AI's response that received feedback
`feedback_text` | TEXT | User's feedback content
`feedback_type` | TEXT | bug|suggestion|praise
`status` | TEXT | pending|processing|processed|rejected

### generated_rules table

Column | Type | Description
--- | --- | ---
`rule_id` | TEXT UNIQUE | Rule identifier (RUL-XXXX)
`feedback_id` | TEXT FK | Source feedback reference
`module_name` | TEXT | Target file (fashion_rules.json)
`rule_type` | TEXT | prompt_update|system_message
`old_rule` | TEXT | Rule being replaced (if any)
`new_rule` | TEXT | Proposed new rule
`reasoning` | TEXT | Why AI suggested this rule
`confidence` | REAL | 0.0 - 1.0
`status` | TEXT | pending|approved|rejected|deployed

### deployments table

Column | Type | Description
--- | --- | ---
`rule_id` | TEXT FK | Reference to deployed rule
`deployed_by` | TEXT | Admin user ID
`deployed_at` | TIMESTAMP | Deployment timestamp
`version_before` | TEXT | Previous rule version (preview)
`version_after` | TEXT | New rule version (preview)
`rollback_of` | INT NULL | If rollback, reference previous deployment

## 4. API Endpoints

Method | Endpoint | Purpose
--- | --- | ---
POST | `/autotrain/feedback` | Submit feedback
GET | `/autotrain/feedback` | List feedbacks
POST | `/autotrain/generate/{feedback_id}` | Generate rule from feedback
GET | `/autotrain/rules` | List rules
POST | `/autotrain/rules/{rule_id}/approve` | Approve rule
POST | `/autotrain/rules/{rule_id}/deploy` | Deploy rule
GET | `/autotrain/status` | System status
POST | `/autotrain/run-all` | Process all pending

## 5. Mock AI Rule Generation

Current implementation uses pattern matching on feedback text:

### Python Implementation

    def _ai_generate_rule(feedback: Dict[str, Any]) -> Dict[str, Any]:
        fb_text = feedback['feedback_text'].lower()
        query = feedback['query'].lower()

        # Pattern: Weather mismatch
        if "nóng" in fb_text and "áo khoác" in query:
            return {
                "old_rule": "- Luôn ưu tiên áo khoác/dày",
                "new_rule": "- Khi trời nóng (>30°): KHÔNG gợi ý áo khoác dày",
                "reasoning": "Weather mismatch correction",
                "confidence": 0.85
            }

        # Pattern: Size/fit issues
        if any(word in fb_text for word in ["dáng lùn", "thấp"]):
            return {
                "old_rule": "- Gợi ý đầm maxi cho mọi khách",
                "new_rule": "- Dưới 1m55: gợi ý đầm ngắn (midi, knee-length)",
                "reasoning": "Proportion-appropriate recommendations",
                "confidence": 0.9
            }

        return {
            "new_rule": f"- Adjust based on: {feedback['feedback_text'][:50]}...",
            "reasoning": "Generic adjustment",
            "confidence": 0.5
        }

⚠️ Production: Replace with LLM call to Claude/OpenAI for smarter rule generation.

## 6. Deployment Flow (Production)

Currently `deploy_rule()` only logs to DB. Production implementation would:

1. Fetch the approved rule from DB
2. Load target file (`fashion_rules.json` or `prompt_v2.txt`)
3. Apply the rule update (append or replace)
4. Write back with backup
5. Reload chatbot configuration (hot-reload if supported)
6. Log deployment in `deployments` table

### Production Deploy Code Template

    async def deploy_rule(rule_id: str):
        rule = await get_rule(rule_id)
        target_path = CONFIG_DIR / rule['module_name']

        # Load existing rules
        content = json.load(open(target_path))

        # Apply update
        content['rules'].append({
            "rule": rule['new_rule'],
            "added_from": rule['feedback_id'],
            "confidence": rule['confidence'],
            "deployed_at": datetime.now().isoformat()
        })

        # Backup and write
        backup(target_path)
        json.dump(content, open(target_path, 'w'), indent=2)

        # Hot-reload chatbot config
        await chatbot_reload()

        await log_deployment(rule_id)
        return {"status": "deployed"}

## 7. Testing Checklist

- Submit feedback → DB stores correctly
- Generate rule → Mock AI produces relevant rule
- Approve rule → Status changes to 'approved'
- Deploy → Status changes to 'deployed', log created
- `run-all` → Processes all pending feedbacks
- Concurrent deploy → No race conditions
- Invalid rule_id → 404 error response

## 8. Extending the System

### Add new AI pattern

    # In _ai_generate_rule():
    if "pattern_keyword" in fb_text:
        return {
            "rule_type": "prompt_update",
            "new_rule": "- Your rule here",
            "reasoning": "Your reasoning",
            "confidence": 0.85
        }

### Add new module type

    ALLOWED_MODULES = [
        "fashion_rules.json",
        "prompt_v2.txt",
        "stylist_guidelines.md"
    ]

### Hook to real LLM

    async def _ai_generate_rule(feedback):
        prompt = f"""Given user feedback:
        Query: {feedback['query']}
        AI Response: {feedback['ai_response']}
        Feedback: {feedback['feedback_text']}

        Suggest a prompt rule to prevent this issue:"""

        resp = await anthropic_client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=1000,
            messages=[{"role": "user", "content": prompt}]
        )
        return parse_llm_response(resp.content[0].text)

## 9. Monitoring & Alerting

Metric | Threshold | Alert
--- | --- | ---
Pending feedbacks | > 100 | Warning (Slack)
Rule generation error rate | > 5% | Critical (PagerDuty)
Deployed rules per day | > 50 | Info
Avg approval time | > 24h | Warning (Email)

## 10. Security Considerations

- Authentication: Add JWT auth to all endpoints (currently open)
- Authorization: Only admin can approve/deploy
- Input validation: Pydantic validates; add profanity filter for `feedback_text`
- Rate limiting: Limit to 10 feedbacks per user/hour
- Audit log: Track who deployed what (already in `deployments` table)

## 11. Future Enhancements

- A/B Testing: Deploy rules to 10% of users first
- Rollback: One-click revert to previous rule version
- Auto-approve: Confidence threshold > 0.9 auto-approves
- Feedback Clustering: Group similar feedback before generation
- Webhook Notifications: Notify admin on new rule suggestion
- Version Control: Store rule history in Git

## 12. Quick Start

### Start server

uvicorn api.main:app --reload

### Submit feedback

curl -X POST http://localhost:8000/autotrain/feedback \ -H "Content-Type: application/json" \ -d '{"query":"tìm áo khoác cho trời 35 độ","ai_response":"Mình gợi ý áo khoác nỉ này...","feedback_text":"Trời nóng quá, AI còn tư vấn áo khoác","feedback_type":"bug"}'

### Generate rule

curl -X POST http://localhost:8000/autotrain/generate/FB-1001

### Approve rule

curl -X POST http://localhost:8000/autotrain/rules/RUL-1001/approve

### Deploy rule

curl -X POST http://localhost:8000/autotrain/rules/RUL-1001/deploy

### Check status

curl http://localhost:8000/autotrain/status
💡 Tip: Use the `/autotrain/run-all` endpoint to process all pending feedbacks in batch.