nxtgauge-gitops/docs/AI_PLANS_FINAL_IMPLEMENTATION.md

# Final AI Plans Implementation Plan

## Last Updated
2026-06-15

## Based On
User-provided final AI Plans and Limits specification.

---

## Scope Summary

**Allowed AI features:**
- Ask Ash help assistant
- AI form filling
- Company job tools (JD, skills, candidate matching)
- Job seeker AI auto-apply
- Professional AI auto-request
- Admin helper tools

**Customer role has NO AI features.**

**Models:**
- `askash-fast` → `qwen3:4b`
- `askash-main` → `qwen3:8b`

**Server:**
- `Ramaris` = Ask Ash AI server

---

## Final Feature Codes

| Feature Code | Model | Credits |
|---|---|---:|
| help_answer | askash-fast | 1 |
| platform_guidance | askash-fast | 1 |
| form_fill | askash-fast | 2 |
| form_validate | askash-fast | 1 |
| jd_generate | askash-main | 5 |
| jd_improve | askash-main | 4 |
| skills_extract | askash-fast | 1 |
| candidate_match | askash-fast | 1 |
| candidate_shortlist | askash-fast | 2 |
| job_match | askash-fast | 1 |
| auto_apply_suggest | askash-fast | 2 |
| auto_apply_execute | askash-main if text generation needed | 5 |
| cover_letter_generate | askash-main | 5 |
| requirement_match | askash-fast | 1 |
| auto_request_suggest | askash-fast | 2 |
| auto_request_execute | backend only | 3 |
| admin_support_reply | askash-main | 3 |
| admin_ticket_summary | askash-fast | 1 |
| admin_verification_summary | askash-fast | 1 |
| abuse_check | askash-fast | 1 |

---

## Plan Tiers

| Plan | Monthly Credits | Daily Actions | Models | Best For |
|---|---:|---:|---|---|
| Free | 10 | 3 | askash-fast | Trial users |
| Pro | 100 | 15 | askash-fast + askash-main | Job seekers and professionals |
| Business | 300 | 40 | askash-fast + askash-main | Companies |
| Enterprise | Custom | Custom | askash-fast + askash-main | High-volume users |

---

## Role-Based AI Access

| Role | AI Access |
|---|---|
| Job Seeker | AI auto-apply, job match, cover letter |
| Professional | AI auto-request, requirement match |
| Company | JD generation, JD improvement, skills extraction, candidate matching |
| Customer | No AI features |
| Admin | Support helper, summary, verification helper, abuse check |

---

## Database Schema

### ai_plans
```sql
CREATE TABLE ai_plans (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    code VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL,
    monthly_credits INT NOT NULL,
    daily_action_limit INT NOT NULL,
    allowed_models JSONB NOT NULL,
    allowed_features JSONB NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### user_ai_subscriptions
```sql
CREATE TABLE user_ai_subscriptions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID UNIQUE NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    plan_id UUID NOT NULL REFERENCES ai_plans(id),
    role_code VARCHAR(50),
    monthly_credits_total INT NOT NULL,
    monthly_credits_used INT NOT NULL DEFAULT 0,
    purchased_credits_total INT NOT NULL DEFAULT 0,
    purchased_credits_used INT NOT NULL DEFAULT 0,
    daily_actions_used INT NOT NULL DEFAULT 0,
    current_period_start TIMESTAMP NOT NULL,
    current_period_end TIMESTAMP NOT NULL,
    status VARCHAR(30) NOT NULL DEFAULT 'active',
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_feature_costs
```sql
CREATE TABLE ai_feature_costs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    feature_code VARCHAR(100) UNIQUE NOT NULL,
    display_name VARCHAR(150) NOT NULL,
    default_model VARCHAR(100) NOT NULL,
    credit_cost INT NOT NULL,
    max_input_tokens INT,
    max_output_tokens INT,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_usage_logs
```sql
CREATE TABLE ai_usage_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    role_code VARCHAR(50),
    feature_code VARCHAR(100) NOT NULL,
    model_alias VARCHAR(100) NOT NULL,
    credits_charged INT NOT NULL,
    input_tokens INT,
    output_tokens INT,
    total_tokens INT,
    status VARCHAR(30) NOT NULL,
    request_id VARCHAR(100),
    error_message TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_credit_transactions
```sql
CREATE TABLE ai_credit_transactions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    transaction_type VARCHAR(50) NOT NULL,
    source VARCHAR(50) NOT NULL,
    credits INT NOT NULL,
    balance_after INT NOT NULL,
    reference_id UUID,
    description TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_auto_apply_settings
```sql
CREATE TABLE ai_auto_apply_settings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID UNIQUE NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    is_enabled BOOLEAN NOT NULL DEFAULT FALSE,
    preferred_titles JSONB,
    preferred_locations JSONB,
    preferred_job_types JSONB,
    preferred_work_modes JSONB,
    preferred_skills JSONB,
    min_salary INT,
    max_salary INT,
    max_applications_per_day INT NOT NULL DEFAULT 3,
    require_user_approval BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_auto_apply_logs
```sql
CREATE TABLE ai_auto_apply_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    job_id UUID NOT NULL,
    match_score INT,
    status VARCHAR(50) NOT NULL,
    credits_charged INT NOT NULL DEFAULT 0,
    generated_cover_letter TEXT,
    applied_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_auto_request_settings
```sql
CREATE TABLE ai_auto_request_settings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID UNIQUE NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    professional_role_code VARCHAR(50) NOT NULL,
    is_enabled BOOLEAN NOT NULL DEFAULT FALSE,
    preferred_categories JSONB,
    preferred_locations JSONB,
    preferred_requirement_types JSONB,
    min_budget INT,
    max_budget INT,
    max_requests_per_day INT NOT NULL DEFAULT 3,
    require_user_approval BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

### ai_auto_request_logs
```sql
CREATE TABLE ai_auto_request_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    requirement_id UUID NOT NULL,
    professional_role_code VARCHAR(50) NOT NULL,
    match_score INT,
    status VARCHAR(50) NOT NULL,
    credits_charged INT NOT NULL DEFAULT 0,
    requested_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

---

## Seed Data

### Plans
```sql
INSERT INTO ai_plans (code, name, monthly_credits, daily_action_limit, allowed_models, allowed_features) VALUES
('free', 'Free', 10, 3, '["askash-fast"]', '["help_answer", "platform_guidance", "form_fill", "form_validate", "jd_generate"]'),
('pro', 'Pro', 100, 15, '["askash-fast", "askash-main"]', '["help_answer", "platform_guidance", "form_fill", "form_validate", "job_match", "auto_apply_suggest", "auto_apply_execute", "cover_letter_generate", "requirement_match", "auto_request_suggest", "auto_request_execute"]'),
('business', 'Business', 300, 40, '["askash-fast", "askash-main"]', '["help_answer", "platform_guidance", "form_fill", "form_validate", "jd_generate", "jd_improve", "skills_extract", "candidate_match", "candidate_shortlist"]'),
('enterprise', 'Enterprise', 50000, 999999, '["askash-fast", "askash-main"]', '["help_answer", "platform_guidance", "form_fill", "form_validate", "jd_generate", "jd_improve", "skills_extract", "candidate_match", "candidate_shortlist", "job_match", "auto_apply_suggest", "auto_apply_execute", "cover_letter_generate", "requirement_match", "auto_request_suggest", "auto_request_execute", "admin_support_reply", "admin_ticket_summary", "admin_verification_summary", "abuse_check"]');
```

### Feature Costs
```sql
INSERT INTO ai_feature_costs (feature_code, display_name, default_model, credit_cost) VALUES
('help_answer', 'Help Answer', 'askash-fast', 1),
('platform_guidance', 'Platform Guidance', 'askash-fast', 1),
('form_fill', 'Form Fill', 'askash-fast', 2),
('form_validate', 'Form Validate', 'askash-fast', 1),
('jd_generate', 'Job Description Generate', 'askash-main', 5),
('jd_improve', 'Job Description Improve', 'askash-main', 4),
('skills_extract', 'Skills Extract', 'askash-fast', 1),
('candidate_match', 'Candidate Match', 'askash-fast', 1),
('candidate_shortlist', 'Candidate Shortlist', 'askash-fast', 2),
('job_match', 'Job Match', 'askash-fast', 1),
('auto_apply_suggest', 'Auto Apply Suggest', 'askash-fast', 2),
('auto_apply_execute', 'Auto Apply Execute', 'askash-main', 5),
('cover_letter_generate', 'Cover Letter Generate', 'askash-main', 5),
('requirement_match', 'Requirement Match', 'askash-fast', 1),
('auto_request_suggest', 'Auto Request Suggest', 'askash-fast', 2),
('auto_request_execute', 'Auto Request Execute', 'backend', 3),
('admin_support_reply', 'Admin Support Reply', 'askash-main', 3),
('admin_ticket_summary', 'Admin Ticket Summary', 'askash-fast', 1),
('admin_verification_summary', 'Admin Verification Summary', 'askash-fast', 1),
('abuse_check', 'Abuse Check', 'askash-fast', 1);
```

---

## Backend Services

### Core Services
1. **AiPlanService** - get plan, check allowed models/features
2. **AiFeatureService** - get feature cost and default model
3. **AiCreditService** - check balance, charge credits, add purchased credits
4. **AiUsageService** - log usage, track tokens
5. **AiModelRouter** - route feature to correct model alias
6. **AiAutoApplyService** - job seeker auto-apply logic
7. **AiAutoRequestService** - professional auto-request logic

### Internal Flow
```
Request
  ↓
Check auth
  ↓
Check active role
  ↓
Check AI plan allows this feature
  ↓
Check daily action limit
  ↓
Check credit balance
  ↓
Select model alias via AiModelRouter
  ↓
Call LiteLLM internal service
  ↓
Charge credits
  ↓
Write usage log
  ↓
Return response
```

---

## API Endpoints

### General AI
```
POST /api/ai/help/ask
POST /api/ai/forms/fill
POST /api/ai/forms/validate
```

### Company AI
```
POST /api/ai/company/jobs/generate-description
POST /api/ai/company/jobs/improve-description
POST /api/ai/company/jobs/extract-skills
POST /api/ai/company/candidates/match
POST /api/ai/company/candidates/shortlist
```

### Job Seeker AI Auto-Apply
```
GET  /api/ai/job-seeker/auto-apply/settings
POST /api/ai/job-seeker/auto-apply/settings
POST /api/ai/job-seeker/auto-apply/suggest
POST /api/ai/job-seeker/auto-apply/execute
GET  /api/ai/job-seeker/auto-apply/logs
```

### Professional AI Auto-Request
```
GET  /api/ai/professional/auto-request/settings
POST /api/ai/professional/auto-request/settings
POST /api/ai/professional/auto-request/suggest
POST /api/ai/professional/auto-request/execute
GET  /api/ai/professional/auto-request/logs
```

### Admin AI
```
POST /api/ai/admin/support/reply
POST /api/ai/admin/tickets/summary
POST /api/ai/admin/verification/summary
POST /api/ai/admin/abuse/check
```

### AI Usage
```
GET /api/ai/usage/summary
GET /api/ai/usage/logs
GET /api/ai/credits/balance
GET /api/ai/plans
POST /api/ai/credits/buy
```

---

## Implementation Order

### Phase 1: Database Foundation
- Create all tables
- Seed plans and feature costs
- Add migrations

### Phase 2: Core AI Services
- AiPlanService
- AiFeatureService
- AiCreditService
- AiUsageService
- AiModelRouter

### Phase 3: LiteLLM Integration
- Internal LiteLLM client
- Feature-based model routing

### Phase 4: Core AI Endpoints
- Help assistant
- Form fill/validate
- Company JD tools

### Phase 5: Automation Features
- Job seeker auto-apply
- Professional auto-request

### Phase 6: Admin AI
- Support reply
- Ticket summary
- Verification summary
- Abuse check

### Phase 7: Frontend
- AI credits widget
- Usage history
- Auto-apply settings
- Auto-request settings
- Admin AI management

### Phase 8: Cron Jobs
- Monthly credit reset
- Daily action reset
- Auto-apply suggestion worker
- Auto-request suggestion worker

---

## Files to Create

### Database
- `migrations/001_add_ai_plans_and_limits.sql`

### Models
- `src/models/ai_plan.rs`
- `src/models/ai_feature_cost.rs`
- `src/models/user_ai_subscription.rs`
- `src/models/ai_usage_log.rs`
- `src/models/ai_credit_transaction.rs`
- `src/models/ai_auto_apply_settings.rs`
- `src/models/ai_auto_apply_log.rs`
- `src/models/ai_auto_request_settings.rs`
- `src/models/ai_auto_request_log.rs`

### Services
- `src/services/ai_plan_service.rs`
- `src/services/ai_feature_service.rs`
- `src/services/ai_credit_service.rs`
- `src/services/ai_usage_service.rs`
- `src/services/ai_model_router.rs`
- `src/services/ai_auto_apply_service.rs`
- `src/services/ai_auto_request_service.rs`
- `src/services/litellm_client.rs`

### Controllers
- `src/controllers/ai_controller.rs`
- `src/controllers/ai_auto_apply_controller.rs`
- `src/controllers/ai_auto_request_controller.rs`
- `src/controllers/ai_admin_controller.rs`

### Middleware
- `src/middleware/ai_auth.rs` (role-based AI access)

### Cron Jobs
- `src/cron/ai_credit_reset.rs`
- `src/cron/ai_daily_reset.rs`
- `src/cron/ai_auto_apply_worker.rs`
- `src/cron/ai_auto_request_worker.rs`

---

## Implementation Status

### Completed
- ✅ Phase 1: Database migration (`20260614233620_ai_plans_and_limits`)
- ✅ Phase 2: Core AI services in `apps/users/src/ai/`
  - `plans.rs` — subscription management, plan/feature/model checks, customer role blocking
  - `credits.rs` — credit balance, charging, daily action limits
  - `model_router.rs` — `askash-fast` / `askash-main` resolution
  - `litellm.rs` — internal LiteLLM client
  - `orchestrator.rs` — combined permission check + model call + charge + log
  - `middleware.rs` — AI access middleware (auto-creates Free subscription)
  - `usage.rs` — usage logging helper
- ✅ Phase 3: LiteLLM integration via `LiteLlmClient`
- ✅ Phase 4: Core AI endpoints wired in `handlers/ai.rs`
  - `POST /api/ai/chat/message` (legacy) → feature-aware LiteLLM fallback
  - `POST /api/ai/chat/ask` → `help_answer`
  - `POST /api/ai/generate-job-field` → `jd_generate`
  - `POST /api/ai/generate-cover-letter` → `cover_letter_generate`
  - `POST /api/ai/tailor-resume` → `form_fill`
  - `POST /api/ai/auto-apply` → `auto_apply_execute`
  - `POST /api/ai/auto-respond-to-lead` → `auto_request_execute`
  - `GET /api/ai/usage` → plan-aware credit/status summary
  - `GET /api/ai/usage/v2` → plan-aware usage summary
- ✅ Phase 5: Automation features in `handlers/ai_auto.rs`
  - `GET/POST /api/ai/auto/job-seeker/auto-apply/settings`
  - `POST /api/ai/auto/job-seeker/auto-apply/suggest`
  - `GET /api/ai/auto/job-seeker/auto-apply/logs`
  - `GET/POST /api/ai/auto/professional/auto-request/settings`
  - `POST /api/ai/auto/professional/auto-request/suggest`
  - `GET /api/ai/auto/professional/auto-request/logs`
- ✅ Phase 6: Admin AI endpoints in `handlers/admin_ai.rs`
  - `POST /api/admin/ai/support/reply` → `admin_support_reply`
  - `POST /api/admin/ai/tickets/summary` → `admin_ticket_summary`
  - `POST /api/admin/ai/verification/summary` → `admin_verification_summary`
  - `POST /api/admin/ai/abuse/check` → `abuse_check`
  - `GET /api/admin/ai/plans`
  - `GET /api/admin/ai/features`
  - `POST /api/admin/ai/users/{user_id}/plan`
  - `POST /api/admin/ai/users/{user_id}/credits`
  - `GET /api/admin/ai/users/{user_id}/usage`
  - `GET /api/admin/ai/users/{user_id}/transactions`
- ✅ Phase 8 (partial): Cron reset jobs in `apps/cron/src/tasks/ai.rs`
  - Daily action reset
  - Monthly credit reset + billing period rollover
- ✅ Seed data: plans, feature costs, and AI credit packages populated by migrations
- ✅ Extended repositories: plan/feature updates, credit transactions, usage logs, auto settings upserts, auto-apply/auto-request logs, credit packages

### Not Started
- ⬜ Credit purchase flow real payment gateway integration (currently Beeceptor simulation)
- ⬜ Kubernetes/infra updates for AI_CREDIT_ADMIN_TOKEN secret
- ⬜ Automated integration tests against a real LiteLLM instance

---

## Key Files

| File | Purpose |
|---|---|
| `crates/db/migrations/20260614233620_ai_plans_and_limits.up.sql` | Database schema + seed data |
| `crates/db/migrations/20260615060600_ai_credit_packages.up.sql` | AI credit purchase packages + seed data |
| `crates/db/src/models/ai/models.rs` | Rust structs for AI tables |
| `crates/db/src/models/ai/repository.rs` | SQLx repositories |
| `apps/users/src/ai/plans.rs` | Plan/subscription enforcement |
| `apps/users/src/ai/credits.rs` | Credit charging |
| `apps/users/src/ai/model_router.rs` | Model selection |
| `apps/users/src/ai/litellm.rs` | LiteLLM HTTP client |
| `apps/users/src/ai/orchestrator.rs` | End-to-end AI call helper |
| `apps/users/src/ai/middleware.rs` | AI access middleware |
| `apps/users/src/handlers/ai.rs` | Wired AI endpoints |
| `apps/users/src/main.rs` | AI module registration |

---

## Key Decisions

- LiteLLM is internal gateway only
- Ollama is internal model runtime only
- Ramaris handles AI workloads
- Customer role has NO AI features
- Credits are feature-based, not token-based
- LLM suggests, backend decides and executes
- Automation has 3 phases: suggest → approve → auto-execute
- Free plan is auto-created on first AI access for non-customer users