Career_AGENT

Imported from Agnes0224/Career_AGENT (AGENTS.md). Install upstream with npx skills add Agnes0224/Career_AGENT. Copyright stays with the author.

Career Agent — AI Coding Agent Guide

This is a LangGraph-based multi-agent system that evaluates whether a GitHub project aligns with a target AI Agent internship role. Use this guide to understand the codebase structure, execution flow, and development conventions.

Quick Reference

• Framework: LangGraph (supervisor-controlled state machine)
• State: Single CareerAgentState TypedDict shared across all agents
• Entry points: python main.py (CLI) or streamlit run app.py (Web UI)
• Database: SQLite at storage/career_agent.db
• Key config: core/config.py (GitHub token, timeouts, retry limits)

Architecture: The Supervisor Pattern

The graph executes a deterministic sequence of agents controlled by a rule-based supervisor:

START 
  ↓
load_memory (fetch SQLite context)
  ↓
supervisor (decide next action)
  ↓
  ├─ PARSE_INFO → info_parser_agent
  ├─ SEARCH_AND_EVALUATE_PROJECTS → project_agent
  ├─ GENERATE_CAREER_STRATEGY → career_strategy_agent
  ├─ UPDATE_MEMORY → memory_update_node
  └─ FINAL_REPORT → final_report_node
  ↓
[loop back to supervisor until FINAL_REPORT]
  ↓
END

Supervisor Decision Logic

See core/supervisor.py decide_next_action() for the exact policy:

1. PARSE_INFO if user_profile or jd_requirements missing
2. SEARCH_AND_EVALUATE_PROJECTS if no evaluated projects (unless GitHub error)
3. SEARCH_AND_EVALUATE_PROJECTS (retry) if search quality is low and retry_count["project_agent"] < MAX_GITHUB_RETRIES (default: 2)
4. GENERATE_CAREER_STRATEGY if no strategy generated (unless max retries exceeded)
5. UPDATE_MEMORY if memory not yet persisted
6. FINAL_REPORT when complete or on error

State Management

Single source of truth: CareerAgentState (TypedDict in core/schema.py)

Key fields:

• resume_text, jd_texts, target_role — user inputs
• user_profile, jd_requirements, skill_gaps — parsed info
• evaluated_projects, career_strategy — outputs
• messages — execution trace
• quality_flags, retry_count — supervisor decision signals

Pattern: Agents read from state, compute, then update state fields and add messages via add_message().

Module Organization

core/

• schema.py: CareerAgentState TypedDict, constants, message utilities
• config.py: Environment-loaded settings (GitHub token, timeouts, retry limits, database path)
• graph.py: Build and run the LangGraph (build_graph(), run_career_agent())
• supervisor.py: Deterministic routing logic (decide_next_action(), route_next_action())
• memory.py: Load/persist SQLite context (load_memory_node(), memory_update_node())

agents/

• info_parser_agent.py: Parse resume/JDs, compute skill gaps (keyword-based, v1)
• project_agent.py: GitHub search, fetch READMEs, score projects, reflect on quality
• career_strategy_agent.py: Reflective strategy generation with deterministic fallback

tools/

Pure functions, no graph side-effects:

• resume_tool.py: parse_resume(), parse_job_descriptions(), compute_skill_gaps()
• github_tool.py: search_projects(), handles API errors gracefully
• scoring_tool.py: evaluate_project() (6-factor weighted formula), reflect_search_quality()
• llm_tool.py: Optional Qwen/DashScope JSON helper using the OpenAI-compatible API

storage/

• memory_store.py: SQLite I/O (recommendation history, user feedback, preferences, filters)

tests/

Unit tests for key functions; run with pytest

Agent Responsibilities

InfoParserAgent

Input: resume_text, jd_texts
Output: user_profile, jd_requirements, skill_gaps
Logic: Keyword extraction (regex word boundary match) on a ~30-skill vocabulary

Key: Deterministic in v1; may be replaced with LLM-based extraction in v2.

ProjectAgent

Input: skill_gaps, target_role (from supervisor)
Output: evaluated_projects, quality_flags["project_search"]
Logic:

1. Run a bounded internal ReAct loop for up to 3 search rounds
2. Use only allowed actions: generate_queries, search_github, fetch_readmes, score_projects, reflect_search_quality, refine_queries, stop
3. Search GitHub API (~8 results per query) and fetch READMEs through github_tool.py
4. Score via deterministic scoring_tool.evaluate_project(); Qwen cannot overwrite final_score
5. Reflect with deterministic reflect_search_quality()
6. If low-quality, Qwen may suggest refined queries; invalid or unavailable Qwen output falls back to deterministic query generation
7. Stop when quality is acceptable or max rounds are reached, then write trace metadata to quality_flags["project_react_trace"]

Key gotchas:

• GitHub rate limits: 60 req/hr without token → set GITHUB_TOKEN for 5000 req/hr
• Large READMEs (>25KB) penalize feasibility; handles base64 decoding
• No README found → auto-fail project
• ProjectAgent owns search retry/refinement internally; the supervisor should not repeatedly rerun low-quality GitHub searches after project_agent_exhausted

CareerStrategyAgent

Input: evaluated_projects, skill_gaps, user_profile
Output: career_strategy
Logic:

• Pick top-scored project (or recommend existing project if no GitHub candidate scores > 6.0)
• Draft, critique, and optionally revise a structured strategy for up to 2 reflection rounds
• Fall back to deterministic strategy if Qwen is unavailable or returns invalid JSON
• Generate:
  • 12-day roadmap (4 phases: understand baseline, add skills, make defensible, package for resume)
  • Resume bullets (3 achievement-focused points)
  • Interview Q&A prep (3 common questions with expected answers)
  • Top 5 ranking snapshot

Output format: Structured JSON for Streamlit rendering + final report assembly, plus reflection metadata in quality_flags["strategy_reflection_trace"] and quality_flags["strategy_quality"]

MemoryUpdateNode

Input: evaluated_projects, user_feedback
Logic: Persist top 5 recommendations and optional feedback to SQLite Output: quality_flags["memory_updated"] = True

Logging & Debugging

Logging enabled by default (set in core/config.py):

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)

Trace supervisor decisions:

• supervisor.py decide_next_action() logs all condition checks and the chosen action
• Each agent logs entry/exit and key metrics
• State is included in final report under messages field

Example:

streamlit run app.py  # Terminal shows full log stream

Code Requirements & Development Standards

Bug Fixes & Code Changes

• Fix bugs completely: Every code modification must fix all related bugs at once. Do NOT add fallback/workaround code for partial fixes.
• No placeholder patches: Ensure all changes are production-ready; avoid temporary fixes that will need revisiting later.
• Root cause: Identify and fix the root cause, not symptoms.

Plan Documentation

• Maintain PLAN.md as current project status, not a changelog: After completing any development work:
  • Update the existing sections in place.
  • Move completed work from "Next Priorities", "Partially Implemented", or "Not Implemented Yet" into "Implemented".
  • Move important resolved bugs from "Open Issues" into "Fixed Issues", or remove them if they are no longer important.
  • Keep unresolved bugs in "Open Issues".
  • Remove items that are no longer relevant.
  • Keep "Next Priorities" limited to the real next 3-5 priorities in order.
  • Do not append "Session YYYY-MM-DD" sections or long session summaries.

Common Patterns

Error Handling

• GitHub failures (network, rate limit, invalid token): Caught in project_agent, surfaced in quality_flags["github_error"], triggers early exit to final report
• Parsing gaps: Agents check for empty skill lists; defaults provided
• Memory failures: SQLite errors logged but don't block workflow

State Updates

def my_agent(state: CareerAgentState) -> CareerAgentState:
    state["my_output"] = result
    state["quality_flags"]["my_check"] = is_ok
    return add_message(state, "my_agent", f"Did something: {details}")

Adding New Logic

1. Add new node to graph in core/graph.py build_graph()
2. Add routing case in supervisor.py decide_next_action() and route_next_action()
3. Add state fields to CareerAgentState in core/schema.py if needed
4. Log entry/exit with logger.info() for debuggability

Setup & Development

First Run

cd career_agent
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
set GITHUB_TOKEN=your_token_here  # optional but recommended

Run

streamlit run app.py              # Interactive UI on localhost:8501
python main.py                    # CLI with sample data → prints JSON
pytest                            # Unit tests

Environment Variables

• GITHUB_TOKEN: GitHub API token (default: empty → 60 req/hr rate limit)
• GITHUB_API_BASE: Override API endpoint (default: https://api.github.com)
• GITHUB_TIMEOUT_SECONDS: Request timeout (default: 20)
• MAX_GITHUB_RETRIES: Retry on low-quality search (default: 2)
• MAX_AGENT_RETRIES: Retry career_strategy if needed (default: 2)
• DEFAULT_SEARCH_LIMIT: GitHub results per query (default: 8)

Key Files to Understand First

1. core/schema.py — Understand CareerAgentState structure
2. core/graph.py — How the graph is built and executed
3. core/supervisor.py — Routing decision logic
4. agents/project_agent.py — Most complex agent; GitHub integration
5. README.md — High-level overview

Tips for AI Agents

• State is single source of truth: Don't create side effects outside the state object
• Supervisor is deterministic: Add new decision criteria to decide_next_action(); routing follows fixed rules and should not become a ReAct agent
• Reasoning patterns differ by expert: ProjectAgent uses bounded ReAct, CareerStrategyAgent uses Reflection, InfoParserAgent remains structured extraction
• Logging helps debugging: All major steps are logged; trace messages in final report to see execution history
• GitHub failures are expected: Set GITHUB_TOKEN to avoid rate limits; handle API errors gracefully
• Memory is persistent: Recommendations and feedback accumulate in SQLite; check memory_context to understand historical context
• Testing via CLI is faster: python main.py with sample data runs in seconds; useful for iteration

Next Steps for Contributors

• Add LLM-based skill extraction: Replace keyword matching in info_parser_agent with LLM prompts
• Enhance project scoring: Add more factors (license quality, documentation depth, etc.)
• Multi-target role support: Extend supervisor to handle multiple simultaneous role evaluations
• User feedback loop: Improve memory to rank projects based on collected feedback
• Performance optimization: Batch GitHub API calls, cache README fetches