Ashwin Kumar Sivakumar 7902b265a9 feat(ai): add AI plans docs, LiteLLM manifests, and infrastructure updates

- Add comprehensive AI plans implementation documentation
- Add LiteLLM gateway Kubernetes manifests
- Update PostgreSQL and Forgejo deployment configs
- Add build-from-binaries script

2026-06-15 06:15:41 +05:30

17 KiB

Raw Blame History

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

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

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

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

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

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

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

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

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

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

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

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

AiPlanService - get plan, check allowed models/features
AiFeatureService - get feature cost and default model
AiCreditService - check balance, charge credits, add purchased credits
AiUsageService - log usage, track tokens
AiModelRouter - route feature to correct model alias
AiAutoApplyService - job seeker auto-apply logic
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

17 KiB Raw Blame History

Final AI Plans Implementation Plan

Last Updated

Based On

Scope Summary

Final Feature Codes

Plan Tiers

Role-Based AI Access

Database Schema

ai_plans

user_ai_subscriptions

ai_feature_costs

ai_usage_logs

ai_credit_transactions

ai_auto_apply_settings

ai_auto_apply_logs

ai_auto_request_settings

ai_auto_request_logs

Seed Data

Plans

Feature Costs

Backend Services

Core Services

Internal Flow

API Endpoints

General AI

Company AI

Job Seeker AI Auto-Apply

Professional AI Auto-Request

Admin AI

AI Usage

Implementation Order

Phase 1: Database Foundation

Phase 2: Core AI Services

Phase 3: LiteLLM Integration

Phase 4: Core AI Endpoints

Phase 5: Automation Features

Phase 6: Admin AI

Phase 7: Frontend

Phase 8: Cron Jobs

Files to Create

Database

Models

Services

Controllers

Middleware

Cron Jobs

Implementation Status

Completed

Not Started

Key Files

Key Decisions

17 KiB

Raw Blame History