From 8a025524f3040406b0642c8e3c1870a97d00e3fe Mon Sep 17 00:00:00 2001 From: Sachin Jaiswal Date: Fri, 12 Sep 2025 21:36:05 +0530 Subject: [PATCH 1/2] Add comprehensive Report/Analytics API documentation - Created detailed API documentation for Report/Analytics endpoints - Documented all endpoints: GET/POST /report/, /extract/, /run/, /insight/ - Included comprehensive examples, request/response formats, and error handling - Added usage examples, integration notes, and performance considerations - Updated README.md to include link to new documentation - Addresses issue #14 --- README.md | 1 + docs/api/API_REPORT_ANALYTICS.md | 578 +++++++++++++++++++++++++++++++ 2 files changed, 579 insertions(+) create mode 100644 docs/api/API_REPORT_ANALYTICS.md diff --git a/README.md b/README.md index 056c623..b2dcff5 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,7 @@ Select applications → Choose analysis scope → **Generate Report** → Review --- ## API Docs - Application Management: [link](docs/api/API_APPLICATION.md) +- Report/Analytics: [link](docs/api/API_REPORT_ANALYTICS.md) --- ## 🤝 Contributing diff --git a/docs/api/API_REPORT_ANALYTICS.md b/docs/api/API_REPORT_ANALYTICS.md new file mode 100644 index 0000000..77901d3 --- /dev/null +++ b/docs/api/API_REPORT_ANALYTICS.md @@ -0,0 +1,578 @@ +# Report/Analytics API Documentation + +This document describes the Report/Analytics APIs that enable data analysis, insight generation, and pipeline processing for job application data. + +## Base URL +``` +http://localhost:8000/report/ +``` + +## Authentication +The API currently uses Django REST Framework's standard authentication. + +--- + +## Overview + +The Report/Analytics APIs provide powerful data analysis capabilities for job application data. These APIs enable: + +- **Report Generation**: Create analytical reports from job description data +- **Data Extraction**: Process and extract insights from job descriptions +- **Pipeline Processing**: Run complete analysis pipelines combining extraction and insights +- **AI-Powered Insights**: Generate personalized summaries and recommendations + +--- + +## API Endpoints + +### 1. Report Management + +Base Path: `/report/` + +#### 1.1 Get All Reports +```http +GET /report/ +``` + +**Description**: Retrieve all analysis reports with their results and latest summaries. + +**Response Example:** +```json +{ + "count": 5, + "results": [ + { + "id": 1, + "created_at": "2024-01-15T10:30:00Z", + "results": [ + { + "id": 1, + "name": "skill_analysis", + "result": { + "must_have_skills": ["Python", "Django", "REST API"], + "nice_to_have_skills": ["Docker", "AWS", "React"], + "skill_frequency": { + "Python": 45, + "Django": 32, + "JavaScript": 28 + } + } + } + ], + "latest_summary": { + "id": 1, + "created_at": "2024-01-15T10:35:00Z", + "content": "Based on analysis of 50 job descriptions, Python and Django are the most demanded skills..." + } + } + ] +} +``` + +#### 1.2 Get Single Report +```http +GET /report/{id}/ +``` + +**Path Parameters:** +- `id` (integer, required): The report ID + +**Response**: Single report object with detailed results and summaries + +#### 1.3 Create Analysis Report +```http +POST /report/ +``` + +**Description**: Generate a new analysis report based on job description data. + +**Request Body Options:** + +**Option 1 - Filter by Job IDs:** +```json +{ + "job_ids": [1, 2, 3, 5, 8] +} +``` + +**Option 2 - Filter by Date Range:** +```json +{ + "start_at": "2024-01-01T00:00:00Z", + "end_at": "2024-01-31T23:59:59Z" +} +``` + +**Option 3 - Analyze All Data:** +```json +{} +``` + +**Response Example:** +```json +{ + "id": 2, + "created_at": "2024-01-16T14:20:00Z", + "results": [ + { + "id": 5, + "name": "skill_analysis", + "result": { + "total_jobs_analyzed": 25, + "must_have_skills": ["Python", "SQL", "Git"], + "emerging_skills": ["Kubernetes", "GraphQL"], + "skill_categories": { + "programming_languages": ["Python", "JavaScript", "Java"], + "frameworks": ["Django", "React", "Spring"], + "tools": ["Docker", "Jenkins", "Git"] + }, + "experience_levels": { + "junior": 5, + "mid": 12, + "senior": 8 + } + } + }, + { + "id": 6, + "name": "salary_analysis", + "result": { + "average_salary_eur": 75000, + "salary_range": { + "min": 45000, + "max": 120000 + }, + "by_experience": { + "junior": 52000, + "mid": 75000, + "senior": 95000 + } + } + } + ], + "latest_summary": null +} +``` + +#### 1.4 Update Report +```http +PUT /report/{id}/ +PATCH /report/{id}/ +``` + +**Description**: Update report metadata (results are typically read-only) + +#### 1.5 Delete Report +```http +DELETE /report/{id}/ +``` + +**Response**: 204 No Content + +--- + +### 2. Data Extraction Pipeline + +#### 2.1 Process Data Extraction +```http +POST /report/extract/ +``` + +**Description**: Extract and process job description data using AI services. + +**Request Body Options:** + +**Option 1 - Extract Specific Jobs:** +```json +{ + "job_ids": [1, 2, 3, 4, 5] +} +``` + +**Option 2 - Extract by Date Range:** +```json +{ + "start": "2024-01-01", + "end": "2024-01-31" +} +``` + +**Option 3 - Extract All:** +```json +{} +``` + +**Response:** +```json +{ + "message": "Extraction completed", + "processed_jobs": 15, + "extraction_time": "2024-01-16T14:25:00Z" +} +``` + +**What This Endpoint Does:** +- Processes raw job description text using AI/NLP +- Extracts structured data (skills, requirements, salary info) +- Enriches job descriptions with categorized information +- Prepares data for analysis and reporting + +--- + +### 3. Complete Analysis Pipeline + +#### 3.1 Run Full Pipeline +```http +POST /report/run/ +``` + +**Description**: Execute the complete analysis pipeline combining data extraction, report generation, and AI-powered insights. + +**Request Body:** +```json +{ + "job_ids": [1, 2, 3, 4, 5], + "resume_id": 2, + "languages": ["en", "zh"] +} +``` + +**Parameters:** +- `job_ids` (array, optional): Specific job IDs to analyze (if not provided, analyzes all) +- `resume_id` (integer, optional): Resume ID for personalized analysis +- `languages` (array, optional): Languages for summary generation (default: ["en"]) + +**Response:** +```json +{ + "report": { + "id": 3, + "created_at": "2024-01-16T15:00:00Z", + "results": [ + { + "id": 7, + "name": "market_analysis", + "result": { + "top_skills": ["Python", "JavaScript", "SQL"], + "trending_technologies": ["AI/ML", "Cloud Computing", "DevOps"], + "location_insights": { + "remote_friendly": 65, + "hybrid": 25, + "onsite": 10 + } + } + } + ], + "latest_summary": { + "id": 3, + "created_at": "2024-01-16T15:05:00Z", + "content": "Market analysis reveals strong demand for full-stack developers..." + } + }, + "summary": { + "personalized_insights": "Based on your resume, you match 85% of the market requirements...", + "skill_gaps": ["Docker", "Kubernetes", "AWS"], + "recommended_actions": [ + "Consider learning containerization technologies", + "Gain cloud platform experience", + "Strengthen DevOps skills" + ], + "career_progression": { + "current_level": "Mid-level Developer", + "next_steps": ["Senior Developer", "Tech Lead"], + "timeline": "12-18 months with focused learning" + } + } +} +``` + +**Pipeline Process:** +1. **Data Extraction**: Processes job descriptions using AI/NLP +2. **Analysis Generation**: Creates comprehensive market analysis +3. **Insight Generation**: Generates personalized insights based on resume +4. **Summary Creation**: Produces actionable recommendations + +--- + +### 4. AI-Powered Insights + +#### 4.1 Generate Report Summary +```http +POST /report/{report_id}/insight/ +``` + +**Description**: Generate AI-powered insights and summary for an existing report. + +**Path Parameters:** +- `report_id` (integer, required): The ID of the report to analyze + +**Request Body:** +```json +{ + "resume_id": 2 +} +``` + +**Response:** +```json +{ + "summary": { + "personalized_analysis": "Your profile shows strong alignment with 78% of analyzed positions...", + "strengths": [ + "Excellent Python and Django experience", + "Strong problem-solving skills", + "Good understanding of web technologies" + ], + "areas_for_improvement": [ + "Cloud platforms (AWS/Azure)", + "Containerization (Docker/Kubernetes)", + "Advanced database optimization" + ], + "market_insights": { + "average_requirements_match": "78%", + "top_missing_skills": ["Docker", "AWS", "React"], + "salary_potential": { + "current_estimate": "€65,000 - €75,000", + "with_improvements": "€80,000 - €95,000" + } + }, + "action_plan": [ + { + "priority": "High", + "skill": "Docker", + "learning_path": "Complete Docker fundamentals course", + "estimated_time": "2-3 weeks" + }, + { + "priority": "High", + "skill": "AWS", + "learning_path": "AWS Cloud Practitioner certification", + "estimated_time": "4-6 weeks" + } + ] + } +} +``` + +--- + +## Data Models + +### AnalysisReport +```json +{ + "id": 1, + "created_at": "2024-01-15T10:30:00Z", + "results": [AnalysisResult], + "latest_summary": Summary +} +``` + +### AnalysisResult +```json +{ + "id": 1, + "name": "skill_analysis", + "result": { + // JSON object containing analysis results + // Structure varies based on analysis type + } +} +``` + +### Summary +```json +{ + "id": 1, + "created_at": "2024-01-15T10:35:00Z", + "content": "AI-generated summary and insights text" +} +``` + +--- + +## Analysis Types + +The system generates several types of analysis results: + +### 1. Skill Analysis +- **Must-have skills**: Core requirements across jobs +- **Nice-to-have skills**: Desirable but not required +- **Skill frequency**: How often each skill appears +- **Skill categories**: Grouped by type (languages, frameworks, tools) + +### 2. Market Analysis +- **Trending technologies**: Emerging skills in demand +- **Experience levels**: Distribution of seniority requirements +- **Location insights**: Remote/hybrid/onsite preferences +- **Industry trends**: Sector-specific patterns + +### 3. Salary Analysis +- **Average compensation**: Market rates by experience +- **Salary ranges**: Min/max compensation bands +- **Geographic variations**: Location-based differences +- **Benefit patterns**: Common perks and benefits + +### 4. Personalized Insights +- **Profile matching**: How well resume fits market demands +- **Skill gaps**: Missing skills for target roles +- **Career progression**: Recommended next steps +- **Learning roadmap**: Prioritized skill development plan + +--- + +## Error Responses + +### 400 Bad Request +```json +{ + "error": "Invalid date format. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)" +} +``` + +### 404 Not Found +```json +{ + "detail": "Report not found." +} +``` + +### 422 Validation Error +```json +{ + "job_ids": ["This field cannot be empty when provided."], + "resume_id": ["Invalid resume ID."] +} +``` + +### 500 Internal Server Error +```json +{ + "error": "AI service temporarily unavailable. Please try again later." +} +``` + +--- + +## Usage Examples + +### Complete Analysis Workflow + +1. **Extract Job Data:** +```bash +curl -X POST http://localhost:8000/report/extract/ \ + -H "Content-Type: application/json" \ + -d '{"start": "2024-01-01", "end": "2024-01-31"}' +``` + +2. **Generate Analysis Report:** +```bash +curl -X POST http://localhost:8000/report/ \ + -H "Content-Type: application/json" \ + -d '{"start_at": "2024-01-01T00:00:00Z", "end_at": "2024-01-31T23:59:59Z"}' +``` + +3. **Get Personalized Insights:** +```bash +curl -X POST http://localhost:8000/report/3/insight/ \ + -H "Content-Type: application/json" \ + -d '{"resume_id": 2}' +``` + +### Full Pipeline Execution + +```bash +curl -X POST http://localhost:8000/report/run/ \ + -H "Content-Type: application/json" \ + -d '{ + "job_ids": [1, 2, 3, 4, 5], + "resume_id": 2, + "languages": ["en"] + }' +``` + +### Retrieve All Reports + +```bash +curl http://localhost:8000/report/ +``` + +### Get Specific Report + +```bash +curl http://localhost:8000/report/1/ +``` + +--- + +## Integration Notes + +### Frontend Integration + +The frontend service layer (`src/service/report.js`) provides ready-to-use functions: + +```javascript +import { + fetchReports, + getReport, + createReport, + processExtract, + generatePipeline, + createSummary +} from '../service/report'; + +// Get all reports +const reports = await fetchReports(); + +// Generate new analysis +const analysisData = await generatePipeline({ + job_ids: [1, 2, 3], + resume_id: 2, + languages: ['en'] +}); + +// Create personalized summary +const summary = await createSummary(reportId, resumeId); +``` + +### API Configuration + +Base URL is configurable via environment variables: +```javascript +VITE_REPORT_API=http://localhost:8000/report/ +``` + +### Data Flow + +1. **Raw Data**: Job descriptions and resumes +2. **Extraction**: AI-powered data processing (`/extract/`) +3. **Analysis**: Statistical analysis and reporting (`POST /`) +4. **Insights**: Personalized recommendations (`/insight/`) +5. **Pipeline**: Complete end-to-end processing (`/run/`) + +--- + +## Performance Considerations + +- **Large Datasets**: Analysis of 100+ jobs may take 30-60 seconds +- **AI Processing**: Insight generation requires external API calls +- **Caching**: Reports are cached; re-analysis creates new reports +- **Rate Limits**: Respect AI provider rate limits for insight generation + +--- + +## Version Information + +- **API Version**: v1 +- **Django Version**: 5.2 +- **Django REST Framework**: Latest +- **AI Integration**: LangChain with multiple providers (OpenAI, Anthropic, Google) +- **Database**: SQLite (development), PostgreSQL (production recommended) + +--- + +## Related Documentation + +- [Application Management API](API_APPLICATION.md) +- [Deployment Guide](../DEPLOYMENT.md) +- [Project README](../../README.md) \ No newline at end of file From 3ab93561c62cd5eb20542c834ebd3aa210fb8f1e Mon Sep 17 00:00:00 2001 From: Sachin Jaiswal Date: Sat, 13 Sep 2025 10:46:46 +0530 Subject: [PATCH 2/2] Fix API documentation to reflect actual implementation - Update GET /report/ response to show skill frequency statistics as returned by API - Correct POST /report/ response to reflect raw data structure from Analyst class - Fix summary responses to show plain markdown text instead of structured JSON - Simplify extract endpoint response to match actual implementation Addresses maintainer feedback on PR #35 --- docs/api/API_REPORT_ANALYTICS.md | 150 ++++++++++++------------------- 1 file changed, 59 insertions(+), 91 deletions(-) diff --git a/docs/api/API_REPORT_ANALYTICS.md b/docs/api/API_REPORT_ANALYTICS.md index 77901d3..f5825cc 100644 --- a/docs/api/API_REPORT_ANALYTICS.md +++ b/docs/api/API_REPORT_ANALYTICS.md @@ -49,12 +49,20 @@ GET /report/ "id": 1, "name": "skill_analysis", "result": { - "must_have_skills": ["Python", "Django", "REST API"], - "nice_to_have_skills": ["Docker", "AWS", "React"], - "skill_frequency": { - "Python": 45, - "Django": 32, - "JavaScript": 28 + "programming_languages": { + "python": 15, + "javascript": 12, + "java": 8 + }, + "frameworks_tools": { + "django": 10, + "react": 8, + "spring": 5 + }, + "databases": { + "postgresql": 7, + "mysql": 5, + "mongodb": 4 } } } @@ -118,34 +126,28 @@ POST /report/ "id": 5, "name": "skill_analysis", "result": { - "total_jobs_analyzed": 25, - "must_have_skills": ["Python", "SQL", "Git"], - "emerging_skills": ["Kubernetes", "GraphQL"], - "skill_categories": { - "programming_languages": ["Python", "JavaScript", "Java"], - "frameworks": ["Django", "React", "Spring"], - "tools": ["Docker", "Jenkins", "Git"] + "programming_languages": { + "python": 23, + "javascript": 18, + "java": 12, + "typescript": 9 }, - "experience_levels": { - "junior": 5, - "mid": 12, - "senior": 8 - } - } - }, - { - "id": 6, - "name": "salary_analysis", - "result": { - "average_salary_eur": 75000, - "salary_range": { - "min": 45000, - "max": 120000 + "frameworks_tools": { + "react": 15, + "django": 14, + "spring": 8, + "angular": 7 }, - "by_experience": { - "junior": 52000, - "mid": 75000, - "senior": 95000 + "cloud_platforms": { + "aws": 16, + "azure": 8, + "gcp": 5 + }, + "databases": { + "postgresql": 12, + "mysql": 10, + "mongodb": 7, + "redis": 5 } } } @@ -205,9 +207,7 @@ POST /report/extract/ **Response:** ```json { - "message": "Extraction completed", - "processed_jobs": 15, - "extraction_time": "2024-01-16T14:25:00Z" + "message": "Extraction completed" } ``` @@ -251,14 +251,29 @@ POST /report/run/ "results": [ { "id": 7, - "name": "market_analysis", + "name": "skill_analysis", "result": { - "top_skills": ["Python", "JavaScript", "SQL"], - "trending_technologies": ["AI/ML", "Cloud Computing", "DevOps"], - "location_insights": { - "remote_friendly": 65, - "hybrid": 25, - "onsite": 10 + "programming_languages": { + "python": 18, + "javascript": 15, + "java": 8, + "typescript": 6 + }, + "frameworks_tools": { + "react": 12, + "django": 11, + "spring": 7, + "angular": 5 + }, + "cloud_platforms": { + "aws": 14, + "azure": 7, + "gcp": 4 + }, + "databases": { + "postgresql": 10, + "mysql": 8, + "mongodb": 6 } } } @@ -269,20 +284,7 @@ POST /report/run/ "content": "Market analysis reveals strong demand for full-stack developers..." } }, - "summary": { - "personalized_insights": "Based on your resume, you match 85% of the market requirements...", - "skill_gaps": ["Docker", "Kubernetes", "AWS"], - "recommended_actions": [ - "Consider learning containerization technologies", - "Gain cloud platform experience", - "Strengthen DevOps skills" - ], - "career_progression": { - "current_level": "Mid-level Developer", - "next_steps": ["Senior Developer", "Tech Lead"], - "timeline": "12-18 months with focused learning" - } - } + "summary": "# Job Market Analysis Summary\n\n## Key Insights\n\nBased on your resume, you match 85% of the market requirements for the analyzed positions. Here's a comprehensive breakdown:\n\n### Your Strengths\n- Excellent Python and Django experience\n- Strong problem-solving skills\n- Good understanding of web technologies\n\n### Skill Gaps to Address\n- **Docker**: High priority - containerization is increasingly important\n- **Kubernetes**: Essential for scalable deployments\n- **AWS**: Cloud platform experience is highly valued\n\n### Recommended Actions\n1. Complete Docker fundamentals course (2-3 weeks)\n2. Gain cloud platform experience with AWS\n3. Strengthen DevOps skills\n\n### Career Progression\n- **Current Level**: Mid-level Developer\n- **Next Steps**: Senior Developer, Tech Lead\n- **Timeline**: 12-18 months with focused learning" } ``` @@ -316,41 +318,7 @@ POST /report/{report_id}/insight/ **Response:** ```json { - "summary": { - "personalized_analysis": "Your profile shows strong alignment with 78% of analyzed positions...", - "strengths": [ - "Excellent Python and Django experience", - "Strong problem-solving skills", - "Good understanding of web technologies" - ], - "areas_for_improvement": [ - "Cloud platforms (AWS/Azure)", - "Containerization (Docker/Kubernetes)", - "Advanced database optimization" - ], - "market_insights": { - "average_requirements_match": "78%", - "top_missing_skills": ["Docker", "AWS", "React"], - "salary_potential": { - "current_estimate": "€65,000 - €75,000", - "with_improvements": "€80,000 - €95,000" - } - }, - "action_plan": [ - { - "priority": "High", - "skill": "Docker", - "learning_path": "Complete Docker fundamentals course", - "estimated_time": "2-3 weeks" - }, - { - "priority": "High", - "skill": "AWS", - "learning_path": "AWS Cloud Practitioner certification", - "estimated_time": "4-6 weeks" - } - ] - } + "summary": "# Personalized Career Analysis\n\n## Profile Assessment\n\nYour profile shows strong alignment with 78% of analyzed positions in the current job market.\n\n## Key Strengths\n- **Excellent Python and Django experience**: Core technologies in high demand\n- **Strong problem-solving skills**: Essential for technical roles\n- **Good understanding of web technologies**: Solid foundation for full-stack development\n\n## Areas for Improvement\n\n### High Priority Skills\n- **Cloud platforms (AWS/Azure)**: 65% of positions require cloud experience\n- **Containerization (Docker/Kubernetes)**: Critical for modern deployments\n- **Advanced database optimization**: Valuable for senior roles\n\n## Market Insights\n- **Requirements Match**: 78% alignment with target positions\n- **Top Missing Skills**: Docker, AWS, React\n- **Salary Potential**:\n - Current estimate: €65,000 - €75,000\n - With improvements: €80,000 - €95,000\n\n## Recommended Action Plan\n\n### Immediate Focus (Next 3 months)\n1. **Docker Fundamentals** (Priority: High)\n - Complete Docker fundamentals course\n - Estimated time: 2-3 weeks\n\n2. **AWS Cloud Practitioner** (Priority: High)\n - AWS certification preparation\n - Estimated time: 4-6 weeks\n\n### Career Progression\nWith focused learning on these key areas, you can advance to senior developer roles within 12-18 months." } ```