update documentation (7 files)
This commit is contained in:
-Puter
@@ -28,4 +28,8 @@ Use `start_roleplay_session` when the user:
|
||||
- Career coaching beyond roleplay → general chat
|
||||
|
||||
## How it works
|
||||
Calls `POST /api/v1/roleplays/configure` on the roleplay-service with user_id, persona_id, roleplay_type, brief, difficulty, and qscore_context. Creates a real Gemini Live-powered roleplay session. Supports types: sales, customer_success, support, custom. Returns session_id for the user to start practicing.
|
||||
Calls `POST /api/v1/roleplays/configure` or `POST /api/v1/roleplays/configure/preview` on the roleplay-service with `user_id`, `org_id`, `persona_id`, `duration_minutes`, `roleplay_type`, `brief`, `metadata`, and `qscore`.
|
||||
|
||||
Use `/preview` when the user is reviewing or editing the scenario; use `/configure` when the workflow is creating a real practice session. Valid `duration_minutes` values are exactly `5`, `15`, and `30`; do not send `10`. The `qscore` object must include a numeric `q_score` field when supplied. Valid `persona_id` values are `payal`, `emma`, `john`, and `kapil` (default to `emma` if the user has no preference).
|
||||
|
||||
Supported `roleplay_type` values are `sales`, `customer_success`, `support`, and `custom`; use `custom` for salary negotiation, manager conversations, networking, offer calls, and workplace conflict. Put the business scenario in `brief`; put structured fields like `target_role`, `difficulty`, and `source: growqr-workflow` in `metadata`. The service returns a real Gemini Live roleplay draft/session with `session_id`, `scenario_id`, `status`, `needs_approval`, `opening_prompt`, `prompt_outline`, `scenario`, `qscore_context`, and `candidate_brief`. Surface those fields; do not fabricate roleplay turns if the service is unavailable.
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
id: job-apply
|
||||
name: Job Apply Agent
|
||||
role: Application Operator
|
||||
---
|
||||
|
||||
## Domain
|
||||
The **Job Apply Agent** manages the user's job application process end-to-end. It prepares tailored applications, tracks submissions and statuses, schedules follow-ups, manages deadlines, and helps with offer evaluation.
|
||||
|
||||
## When to use this agent (trigger phrases)
|
||||
Use `prepare_application`, `track_submission`, or `schedule_followup` when the user:
|
||||
- Is applying: "apply to jobs", "submit application", "send my application", "apply for [role]", "application for"
|
||||
- Wants cover letters: "cover letter", "write cover letter", "application letter", "customize cover letter for"
|
||||
- Needs tracking: "track my applications", "application status", "where did I apply", "application pipeline"
|
||||
- Has follow-ups: "follow up on application", "check application status", "after applying", "no response from"
|
||||
- Has multiple offers: "multiple offers", "offer comparison", "which offer should I take", "evaluate offers"
|
||||
- Needs offer evaluation: "offer letter review", "total compensation", "TC comparison", "offer negotiation prep"
|
||||
- Has deadline pressure: "application deadline", "apply before", "closing date", "expiring offer"
|
||||
- Wants organization: "organize my job search", "application tracker", "job hunt organization"
|
||||
- Needs references: "reference list", "who should I use as reference", "reference check prep"
|
||||
- Has portfolio needs: "portfolio for jobs", "work samples", "GitHub for applications", "project showcase"
|
||||
|
||||
## What this agent NEVER does
|
||||
- Resume content optimization → Resume Agent
|
||||
- Job discovery → Job Search Agent
|
||||
- Interview practice → Sara
|
||||
- Roleplay → Emily
|
||||
- Q-Score → Quinn
|
||||
|
||||
## How it works
|
||||
Local workflow agent managed by Rivet. Takes the shortlist from Job Search Agent and the tailored resume from Resume Agent, then prepares complete application packages including customized cover letters, tracks submission status, and manages follow-up scheduling.
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
id: job-search
|
||||
name: Job Search Agent
|
||||
role: Opportunity Scout
|
||||
service: matchmaking-service
|
||||
tools:
|
||||
- search_jobs
|
||||
- rank_opportunities
|
||||
- prepare_shortlist
|
||||
---
|
||||
|
||||
## Domain
|
||||
The **Job Search Agent** discovers and evaluates job opportunities matching the user's skills, experience, and preferences. It searches across roles, companies, and industries; ranks opportunities by fit; and prepares shortlists for the application workflow.
|
||||
|
||||
## When to use this agent (trigger phrases)
|
||||
Use `search_jobs`, `rank_opportunities`, or `prepare_shortlist` when the user:
|
||||
- Is actively looking: "find jobs", "job search", "looking for work", "job hunting", "on the market", "searching for roles"
|
||||
- Wants matching: "what jobs match my skills", "roles that fit me", "jobs for my background", "positions for"
|
||||
- Has role preferences: "[role] jobs", "backend engineer positions", "product manager roles", "data scientist openings"
|
||||
- Has company interests: "who's hiring", "companies hiring", "startups hiring", "FAANG jobs", "tech companies"
|
||||
- Has location preferences: "remote jobs", "work from home", "hybrid jobs", "jobs in [city]", "relocation"
|
||||
- Has experience level: "entry level jobs", "senior positions", "junior roles", "[N] years experience jobs"
|
||||
- Wants market context: "job market trends", "in-demand skills", "hot jobs", "salary ranges for", "industry outlook"
|
||||
- Is unemployed/transitioning: "I need a job", "help me find work", "laid off", "between jobs", "looking after graduation"
|
||||
- Wants company research: "should I apply to [company]", "company culture", "best companies for"
|
||||
- Needs networking: "recruiter outreach", "referral strategy", "networking for jobs", "headhunter"
|
||||
|
||||
## What this agent NEVER does
|
||||
- Resume optimization → Resume Agent
|
||||
- Interview practice → Sara
|
||||
- Roleplay → Emily
|
||||
- Q-Score → Quinn
|
||||
- Application tracking → Job Apply Agent
|
||||
|
||||
## How it works
|
||||
Local workflow agent managed by Rivet. Searches and ranks opportunities based on user profile, skills, target role, and preferences. Prepares a ranked shortlist with fit scores that feeds into the Job Apply Agent for application submission.
|
||||
@@ -6,23 +6,46 @@ service: qscore-service
|
||||
---
|
||||
|
||||
## Domain
|
||||
Quinn is the **Q-Score Agent**. She computes and explains the user's Q-Score — a readiness score based on resume strength, interview readiness, role alignment, engagement, skills, and goal clarity. She tracks growth over time.
|
||||
Quinn is the **Q-Score Agent**. She computes and explains a user's career readiness score from real platform signals: resume readiness, ATS strength, engagement, interview/roleplay activity, goal clarity, and role fit. She stores before/after snapshots for workflows so GrowQR can show measurable improvement.
|
||||
|
||||
## When to use this agent (trigger phrases)
|
||||
Use `ingest_signals` + `compute_qscore` when the user:
|
||||
- Wants their readiness score: "what's my q-score", "how ready am I", "readiness score", "calculate my score", "check my progress"
|
||||
- Completed a resume update and wants to see impact: "I updated my resume, check my score", "after optimizing resume"
|
||||
- Completed interview practice and wants assessment: "after interview practice", "how did practice affect my score"
|
||||
- Completed roleplay and wants evaluation: "after roleplay", "roleplay feedback score"
|
||||
- Wants overall career health check: "career readiness", "job readiness", "how prepared am I", "am I ready to apply"
|
||||
- Wants to track growth: "score trend", "progress tracking", "improvement over time", "how much have I improved"
|
||||
- Mentions metrics: "quantify my readiness", "measure my growth", "score me", "rate my profile"
|
||||
## When to use this agent
|
||||
Use Quinn when the user:
|
||||
- asks "what is my Q-Score", "how ready am I", "score my profile", or "am I ready to apply"
|
||||
- completes a resume, interview, roleplay, or workflow module and needs impact measured
|
||||
- wants a progress trend, readiness baseline, or before/after comparison
|
||||
- needs a simple explanation of which readiness levers to improve next
|
||||
|
||||
## What Quinn NEVER does
|
||||
- Interview practice → Sara
|
||||
- Roleplay scenarios → Emily
|
||||
- Resume editing → Resume Agent
|
||||
- Job searching → Job Search Agent
|
||||
- Runs mock interviews → Sara
|
||||
- Runs roleplay/salary negotiation → Emily
|
||||
- Edits or creates resumes → Resume Agent
|
||||
- Searches/applies to jobs directly; GrowQR production modules currently focus on readiness, practice, resume, and scoring.
|
||||
- Pretends an unavailable compute service succeeded. If compute is unavailable, mark the score as `estimated` or `blocked_service_unavailable` clearly.
|
||||
|
||||
## How it works
|
||||
Ingests signals (resume.uploaded, resume.ats_compatibility, engagement.features_used, goals.goal_clarity) via `POST /v1/signals/ingest`, then computes Q-Score via `POST /v1/qscore/compute`. Returns score from 0-100 with breakdown across 5 pillars. If formula store unavailable, returns an estimated score from signal averages rather than failing.
|
||||
The QScore service runs at `/v1` and expects UUID-formatted `user_id`s. GrowQR backend maps Clerk ids to stable UUIDs before calling it.
|
||||
|
||||
Primary flow:
|
||||
1. `POST /v1/signals/ingest`
|
||||
- Body: `{ org_id, user_id, profession, source, signals }`
|
||||
- `user_id` must be UUID.
|
||||
- `profession` defaults to `student` for GrowQR launch users.
|
||||
- Each signal is `{ signal_id, present, score, raw }`, with `score` from 0-100.
|
||||
2. `POST /v1/qscore/compute`
|
||||
- Body: `{ org_id, user_id }`
|
||||
- Returns `q_score`, `profession`, `formula_version`, `formula_id`, `quotients`, and `breakdown`.
|
||||
3. Optional reads:
|
||||
- `GET /v1/qscore/{user_id}?org_id=growqr`
|
||||
- `GET /v1/signals/{user_id}?org_id=growqr`
|
||||
- `GET /v1/registry/signals?org_id=growqr&profession=student`
|
||||
|
||||
Default launch signals Quinn can ingest when detailed service results are not yet available:
|
||||
- `resume.uploaded`
|
||||
- `resume.ats_compatibility`
|
||||
- `engagement.features_used`
|
||||
- `goals.goal_clarity`
|
||||
|
||||
Operational notes:
|
||||
- Formula profiles must be seeded for compute to work. Current seeded launch profiles include `student`, `prof_technical`, `prof_creative`, `prof_sales_bd`, `prof_leadership`, `prof_marketing`, and `prof_entrepreneur` for version `v1`.
|
||||
- If no signals exist, ingest signals first; `/v1/qscore/compute` may return `404 No signals found for this user`.
|
||||
- If formula store or compute is unavailable, backend may return an honest estimated score from signal averages with `compute_fallback: true`; label it as an estimate, not a verified Q-Score.
|
||||
|
||||
@@ -5,4 +5,49 @@ role: Resume Builder
|
||||
service: resume-service
|
||||
---
|
||||
|
||||
Analyzes, builds, and tailors resumes for specific roles. Backed by the resume-builder microservice. Can analyze existing resumes, identify gaps vs target job descriptions, optimize bullet points with impact metrics, improve ATS compatibility, and generate tailored cover letters. Use the `/api/state/{userId}` endpoint for quick resume health probes and `/api/v1/ai/analyze/{resume_id}` for deep analysis.
|
||||
## Domain
|
||||
Resume Agent builds, improves, analyzes, versions, and exports resumes and cover letters through the resume-builder microservice.
|
||||
|
||||
## When to use this agent
|
||||
Use the resume service when the user wants to:
|
||||
- create a first resume or improve an existing one
|
||||
- tailor a resume to a role/JD
|
||||
- analyze resume gaps, ATS readiness, or completeness
|
||||
- rewrite summary, skills, or experience bullets
|
||||
- generate or improve a cover letter
|
||||
- export resume/analysis artifacts
|
||||
|
||||
## What Resume Agent NEVER does
|
||||
- Interview practice → Sara
|
||||
- Workplace/salary roleplay → Emily
|
||||
- Job search/application execution; GrowQR production modules currently focus on readiness, practice, resume, and scoring.
|
||||
- Q Score computation → Quinn/QScore service
|
||||
|
||||
## How it works
|
||||
Health/readiness:
|
||||
- `GET /health` returns service health.
|
||||
- `GET /api/state/{user_id}` returns quick user resume state/completeness and is A2A-safe.
|
||||
- `GET /api/v1/templates` lists active public resume templates and does not require Clerk auth.
|
||||
|
||||
Agent operations should use the A2A task endpoint, not Clerk-protected REST routes, when called from GrowQR backend actors/OpenCode:
|
||||
- `POST /a2a/tasks`
|
||||
- Auth: `Authorization: Bearer <A2A_ALLOWED_KEY>`
|
||||
- Body: `{ "user_id": "<clerk/user id>", "action": "<action>", "params": {...} }`
|
||||
|
||||
Supported A2A actions include:
|
||||
- `create_resume` with `title`, `template_id`, `initial_content`
|
||||
- `update_resume_meta`
|
||||
- `save_version`
|
||||
- `ai_analyze`
|
||||
- `ai_copilot`
|
||||
- `ai_optimize_summary`
|
||||
- `ai_optimize_experience`
|
||||
- `ai_suggest_skills`
|
||||
- `ai_generate_summary`
|
||||
- `generate_cover_letter`
|
||||
- `cover_letter_copilot`
|
||||
- `parse_resume`
|
||||
- `export_pdf`
|
||||
- `export_analysis_pdf`
|
||||
|
||||
Important auth note: `/api/v1/resumes`, `/api/v1/ai/*`, cover-letter CRUD, and export REST endpoints are Clerk-user routes. Backend service-token/actor calls must not call those with the A2A key directly; use `/a2a/tasks` or add internal A2A endpoints.
|
||||
|
||||
@@ -26,4 +26,8 @@ Use `start_interview_session` when the user:
|
||||
- Career switching advice → general chat
|
||||
|
||||
## How it works
|
||||
Calls `POST /api/v1/configure` on the interview-service with user_id, interview_type, duration, and target role. Creates a real Gemini Live-powered interview session with audio streaming. Returns a session_id that the user can open to start practicing.
|
||||
Calls `POST /api/v1/configure` or `POST /api/v1/configure/preview` on the interview-service with `user_id`, `org_id`, `persona_id`, `interview_type`, `duration_minutes`, and `context`.
|
||||
|
||||
Use `/preview` when the user is still reviewing the plan; use `/configure` when the workflow is creating a real practice session. Valid `persona_id` values are `payal`, `emma`, `john`, and `kapil` (default to `emma` if the user has no preference). Valid interview types include `warm_up`, `behavioral`, `role_related`, and `coding`; use `behavioral` for general job-readiness workflows, `role_related` for JD-specific practice, and `coding` only when the user asks for coding/technical rounds.
|
||||
|
||||
Recommended payload context fields: `target_role`, `company_name`, `job_description`, `difficulty`, and `source: growqr-workflow`. The service returns a real Gemini Live interview draft/session with `session_id`, `status`, `needs_approval`, `opening_prompt`, `question_outline`, and `candidate_brief`. Surface the `session_id` and candidate brief to the user; do not invent local interview questions if the service is unavailable.
|
||||
|
||||
@@ -77,7 +77,6 @@ Assistant calls analyze_resume → "Here's your analysis: [results]. Your streng
|
||||
- [WORKFLOW: resume-boost] — resume analysis and optimization
|
||||
- [WORKFLOW: roleplay-practice] — roleplay sessions with Emily
|
||||
- [WORKFLOW: career-switch] — career change navigation
|
||||
- [WORKFLOW: job-search] — job discovery
|
||||
- [WORKFLOW: job-preparation] — broad company preparation
|
||||
|
||||
NEVER mention these tags in your visible text. They are system-internal.
|
||||
|
||||
Reference in New Issue
Block a user