AI_ML integration

The AI/ML integration for the TalentSync-Normies platform.

The AI/ML capabilities are primarily implemented in the backend Python service, with complementary frontend components for configuration and testing. The backend organizes AI/ML logic into:

• Core LLM configuration and provider switching
• Document processing and NLP preprocessing
• LangChain prompt engineering and chains
• Resume analysis services and routes
• ATS evaluation and interview assistance
• Experiment notebooks for ML model training

graph TB
subgraph "Frontend"
UI[User Interface]
Config[LLM Config Panel]
Test[Test Endpoint]
end
subgraph "Backend"
API[FastAPI Routes]
Core[Core Services]
NLP[NLP Processing]
LLM[LLM Provider Layer]
Prompts[Prompt Templates]
Models[ML Models]
Experiments[Training Notebook]
end
UI --> API
Config --> API
Test --> API
API --> Core
Core --> NLP
Core --> LLM
Core --> Prompts
Core --> Models
Models --> Experiments

• LLM Provider Configuration and Dynamic Switching: Centralized provider selection and instantiation supporting multiple vendors with unified API.
• NLP Pipeline: Document ingestion, text extraction, cleaning, and preprocessing using spaCy and NLTK.
• LangChain Prompt Engineering: Structured prompts for detailed resume analysis, ATS scoring, interview question generation, and cold email editing.
• ML Models: Scikit-learn-based resume classification trained on a synthetic dataset; persisted models and vectorizers for inference.
• Service Orchestration: FastAPI routes delegating to specialized services for resume analysis, ATS evaluation, and interview assistance.

The AI/ML microservice architecture integrates document processing, LLM orchestration, and ML inference. The system supports dynamic LLM provider switching and includes clear error handling and fallback mechanisms.

sequenceDiagram
participant Client as "Client App"
participant API as "FastAPI Routes"
participant Deps as "Dependencies"
participant Proc as "Document Processor"
participant LLM as "LLM Provider"
participant Prompt as "LangChain Prompt"
participant ML as "ML Models"
Client->>API : Upload Resume
API->>Deps : get_request_llm()
Deps-->>API : BaseChatModel
API->>Proc : process_document()
Proc-->>API : Cleaned Text
API->>Prompt : Build Chain
Prompt->>LLM : Invoke
LLM-->>Prompt : Structured JSON
Prompt-->>API : Parsed Data
API->>ML : TF-IDF + Classification (optional)
ML-->>API : Category Prediction
API-->>Client : Analysis Results

The system supports multiple LLM providers (Google, OpenAI, Anthropic, Ollama, OpenRouter, DeepSeek) with a unified factory that selects the appropriate client based on configuration. It includes:

• Environment-based settings for provider, model, API key, and base URL
• Singleton instances for default and faster models
• Runtime provider override via request headers
• Connection testing endpoint for validating credentials

classDiagram
class Settings {
+string LLM_PROVIDER
+string LLM_MODEL
+string LLM_API_KEY
+string LLM_API_BASE
+string GOOGLE_API_KEY
+string MODEL_NAME
+string FASTER_MODEL_NAME
+float MODEL_TEMPERATURE
}
class LLMFactory {
+create_llm(provider, model, api_key, api_base, kwargs) BaseChatModel
+get_llm() BaseChatModel
+get_faster_llm() BaseChatModel
}
class RequestLLM {
+get_request_llm() BaseChatModel
}
Settings --> LLMFactory : "provides config"
RequestLLM --> LLMFactory : "creates per-request"

The pipeline extracts and cleans text from documents, applies preprocessing, and prepares data for LLM analysis and ML classification:

• Document ingestion: Supports TXT, MD, PDF, DOC/DOCX with fallback to multimodal conversion when needed.
• Text extraction: Uses PyMuPDF for Markdown rendering.
• Cleaning and preprocessing: Removes URLs, mentions, punctuation, lemmatization, and stopword filtering.
• spaCy integration: Tokenization and lemmatization for structured NLP tasks.
• ML preprocessing: TF-IDF vectorization for classification.

flowchart TD
Start([Upload File]) --> Detect["Detect File Type"]
Detect --> |TXT/MD| ReadText["Read Text Bytes"]
Detect --> |PDF/DOC/DOCX| Convert["Convert to Markdown"]
Convert --> EmptyCheck{"Empty?"}
EmptyCheck --> |Yes| Fallback["Multimodal Fallback (Google)"]
EmptyCheck --> |No| Clean["Clean Text<br/>Remove URLs/mentions/punctuation"]
Fallback --> Clean
Clean --> Lemmatize["Lemmatize + Stopwords"]
Lemmatize --> TFIDF["TF-IDF Vectorization"]
TFIDF --> Ready([Ready for LLM/ML])

Structured prompts guide the LLM to produce standardized JSON outputs for downstream processing:

• Detailed Analysis: Extracts skills, experience, projects, education, and predicted field.
• ATS Analysis: Scores resumes against job descriptions and provides keyword coverage and recommendations.
• Interview Question Generation: Produces role-specific, difficulty-tuned questions with evaluation criteria.
• Cold Mail Editing: Personalizes and refines cold outreach emails with context and edits.

classDiagram
class ComprehensiveAnalysisPrompt {
+template : string
+build_chain(llm) Runnable
}
class ATSAnalysisPrompt {
+template : string
+build_chain(llm) Runnable
}
class InterviewQuestionPrompt {
+template : ChatPromptTemplate
+get_question_generation_prompt() ChatPromptTemplate
}
class ColdMailEditorPrompt {
+template : string
+build_chain(llm) Runnable
}
ComprehensiveAnalysisPrompt --> LLM : "invokes"
ATSAnalysisPrompt --> LLM : "invokes"
InterviewQuestionPrompt --> LLM : "invokes"
ColdMailEditorPrompt --> LLM : "invokes"

The backend exposes endpoints for resume analysis, formatting, and detailed analysis. Services integrate LLM chains and validation schemas:

• File-based analysis: Processes uploaded files and returns structured data.
• Text-based analysis: Accepts formatted text and returns detailed analysis.
• Validation and cleanup: Ensures data conforms to Pydantic models and filters invalid entries.

sequenceDiagram
participant Client as "Client"
participant Route as "Resume Analysis Routes"
participant Service as "Resume Analysis Service"
participant Processor as "Data Processor"
participant LLM as "LLM Chain"
Client->>Route : POST /resume/analysis
Route->>Service : analyze_resume_service(file, llm)
Service->>Processor : format_resume_text_with_llm()
Processor->>LLM : Invoke formatter
LLM-->>Processor : Formatted text
Processor-->>Service : Cleaned text
Service->>Processor : format_resume_json_with_llm()
Processor->>LLM : Invoke JSON formatter
LLM-->>Processor : Structured JSON
Processor-->>Service : Parsed data
Service-->>Client : ResumeUploadResponse

A scikit-learn pipeline classifies resumes into predefined categories:

• Training Data: Synthetic dataset with resume texts and categories.
• Preprocessing: NLTK-based cleaning and TF-IDF vectorization.
• Models: Grid-searched ensemble models (Random Forest, AdaBoost, Gradient Boosting, SVM, KNN, MultinomialNB, Logistic Regression).
• Persistence: Saved model and vectorizer artifacts for inference.

flowchart TD
Data["Resume Texts + Categories"] --> Clean["NLTK Cleaning"]
Clean --> TFIDF["TF-IDF Vectorization"]
TFIDF --> Split["Train/Test Split"]
Split --> Models["Grid-Search Models"]
Models --> Evaluate["Validation Metrics"]
Evaluate --> Save["Persist Model + Vectorizer"]
Save --> Inference["Inference Pipeline"]

• ATS Evaluation: LangChain graph orchestrates keyword matching, scoring, and recommendations against job descriptions.
• Interview Assistance: Templates and question generation with difficulty and topic alignment; streaming code execution for technical interviews.

sequenceDiagram
participant Client as "Client"
participant ATS as "ATS Evaluator Graph"
participant LLM as "LLM Chain"
Client->>ATS : evaluate_ats(resume_text, jd_text)
ATS->>LLM : Build prompt + invoke
LLM-->>ATS : JSON + Narrative
ATS-->>Client : Structured Evaluation

• Cold Email Editing: Personalized email generation and iterative editing guided by candidate data and company insights.
• Tailored Resume Generation: Uses ATS evaluation summaries and company website content to refine and align resumes.

AI pieces stay in their own modules:

• Core LLM layer depends on environment settings and provider libraries.
• Services depend on LangChain prompts and LLM instances.
• NLP preprocessing depends on spaCy and NLTK resources.
• ML models depend on persisted artifacts and vectorizers.

graph TB
Settings["Settings"] --> LLMFactory["LLM Factory"]
LLMFactory --> Routes["Routes"]
Routes --> Services["Services"]
Services --> NLP["NLP Processor"]
Services --> Prompts["LangChain Prompts"]
Services --> ML["ML Models"]
NLP --> ML

• LLM Provider Selection: Choose models aligned with latency and cost targets; use faster models for preliminary formatting and heavier models for complex reasoning.
• Cost Optimization:
• Use provider-specific pricing calculators and monitor token usage.
• Prefer smaller, cheaper models for formatting and fallbacks.
• Batch requests where feasible and avoid unnecessary retries.
• Caching and Persistence:
• Persist TF-IDF vectorizer and ML models to avoid retraining.
• Cache LLM responses for identical inputs where appropriate.
• Resource Management:
• Monitor memory usage during PDF processing and vectorization.
• Limit concurrent LLM invocations to prevent rate-limit errors.

Common issues:

• Authentication Failures: Verify API keys and provider configuration; use the LLM test endpoint to validate connectivity.
• Rate Limits: Implement retry with exponential backoff and switch to lighter models temporarily.
• Empty or Malformed JSON: Ensure prompts return JSON blocks; use fallback parsing logic to extract JSON substrings.
• Provider Switching Errors: Confirm environment variables and model availability; fallback to default provider if unknown.

Model training data and validation metrics#

• Dataset: Synthetic resume corpus with labeled categories.
• Preprocessing: NLTK cleaning and TF-IDF vectorization.
• Models Tested: Random Forest, AdaBoost, Gradient Boosting, SVM, KNN, MultinomialNB, Logistic Regression.
• Validation: Cross-validation grid search with hyperparameter tuning; best scores recorded.

Testing strategies and model versioning#

• Unit-level tests: Validate prompt parsing, JSON extraction, and service error handling.
• Integration tests: full resume analysis and ATS evaluation flows.
• Model versioning: Persist model and vectorizer artifacts; maintain backward-compatible schemas.

Deployment considerations#

• Containerization: Package backend with required LLM provider libraries and environment variables.
• Secrets Management: Store API keys securely; use encrypted configuration for user-defined providers.
• Monitoring: Track LLM latency, error rates, and token usage; alert on sustained failures.