{"id":39797003,"url":"https://github.com/luillyfe/sourcing-agent","last_synced_at":"2026-01-18T12:25:18.209Z","repository":{"id":325478460,"uuid":"1095832421","full_name":"luillyfe/sourcing-agent","owner":"luillyfe","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-18T21:25:11.000Z","size":11987,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T13:23:05.809Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luillyfe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T15:20:21.000Z","updated_at":"2025-12-18T21:25:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luillyfe/sourcing-agent","commit_stats":null,"previous_names":["luillyfe/sourcing-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/luillyfe/sourcing-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luillyfe%2Fsourcing-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luillyfe%2Fsourcing-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luillyfe%2Fsourcing-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luillyfe%2Fsourcing-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luillyfe","download_url":"https://codeload.github.com/luillyfe/sourcing-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luillyfe%2Fsourcing-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28535997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T12:25:17.194Z","updated_at":"2026-01-18T12:25:18.184Z","avatar_url":"https://github.com/luillyfe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Developer Sourcing Agent - Stage 2\n\nA Go-based AI agent that discovers and qualifies developers using **Prompt Chaining** with **Gemini 3 Pro** on **Google Cloud Vertex AI**.\n\n## Overview\n\nThis is a **Stage 2: Multi-Prompt Sourcing Agent**, representing a significant evolution from the single-shot approach. It implements the **Prompt Chaining** pattern to break down the complex task of sourcing into a deterministic pipeline of specialized steps: requirements analysis, strategy generation, candidate enrichment, and final ranking.\n\n### What Makes This \"Stage 2\"?\n\n- **Prompt Chaining Architecture**: A sequential pipeline of 4 specialized LLM prompts.\n- **Dynamic Search Strategies**: Intelliqently generates primary and fallback search strategies based on requirements.\n- **Candidate Enrichment**: deeply analyzes developer repositories to assess technical fit beyond just bio matching.\n- **Weighted Scoring**: Programmatically calculates match scores based on skills, repo relevance, experience, and profile quality.\n- **Observability**: Built-in tracking for Token Usage, API Call Counts, and Memory execution stats.\n\n## Features\n\n- 🧠 **Smart Requirements Analysis**: Parses natural language into structured technical requirements.\n- 🎯 **Strategic Searching**: Generates optimal GitHub search queries + fallback options if results are scarse.\n- 🔬 **Deep Repository Analysis**: Fetches and analyzes user repositories to verify claimed skills.\n- 📊 **Programmatic Ranking**: Scores candidates on a weighted scale (Skills 40%, Repos 30%, Experience 20%, Quality 10%).\n- 🛡️ **Rate Limit Aware**: Optimized to work within GitHub's API constraints.\n- 👁️ **Full Observability**: Reports execution time, token usage, and API call counts for every run.\n\n## System Architecture\n\n\u003cimg src=\"Sourcing%20Agent%20Architecture%20Stage%202.png\" width=\"1200\" alt=\"Stage 2 System Architecture\"\u003e\n\n## Workflow: The 4-Step Pipeline\n\nThe agent follows a strict 4-step linear workflow:\n\n\u003cimg src=\"Sourcing%20Agent%20Stage%202.png\" width=\"250\" alt=\"Stage 2 Workflow\"\u003e\n\n1.  **Requirements Analyzer**: \"Find Go devs in Lima\" -\u003e `{Skills: [\"Go\"], Location: \"Lima\"}`\n2.  **Strategy Generator**: Creates a primary search (strict) and fallback searches (broader).\n3.  **Candidate Enricher**: Executes GitHub searches, then fetches repositories for each candidate to analyze code relevance.\n4.  **Ranker**: Calculates final scores and formats the top candidates.\n\n## Prerequisites\n\n- **Go 1.21 or higher**\n- **Google Cloud Project** with Vertex AI API enabled\n- **GitHub Personal Access Token**\n    - Required scope: `read:user`\n\n## Installation\n\n1.  Clone the repository:\n    ```bash\n    git clone https://github.com/luillyfe/sourcing-agent.git\n    cd sourcing-agent\n    ```\n\n2.  Install dependencies:\n    ```bash\n    go mod download\n    ```\n\n3.  Set up your environment variables:\n    ```bash\n    cp .env.example .env\n    ```\n\n4.  Edit `.env` and add your configuration:\n    ```env\n    VERTEX_PROJECT_ID=your_google_cloud_project_id\n    VERTEX_REGION=us-central1\n    GITHUB_TOKEN=your_actual_github_token_here\n    ```\n\n## Usage\n\n### Basic Usage\n\nRun the application with a natural language query:\n\n```bash\ngo run main.go \"Find Go developers in Lima\"\n```\n\n### Example Output\n\nThe agent provides real-time progress updates and a detailed JSON final report:\n\n```text\n=== GitHub Developer Sourcing Agent ===\nQuery: Find Go developers in Lima\n\nSearching...\n\nStep 1: Analyzing requirements...\nRequirements analysis took 1.2s\n  Usage: 154 input, 45 output tokens\n\nStep 2: Generating search strategy...\nStrategy generation took 1.5s\n  Usage: 450 input, 320 output tokens\n\nStep 3: Finding and enriching candidates...\nFound 12 candidates, analyzed 12\nCandidate search and enrichment took 4.5s\n\nStep 4: Ranking and presenting...\nRanking took 2.1s\n  Usage: 2100 input, 800 output tokens\n\n--------------------------------------------------\nTotal Token Usage: 2704 input + 1165 output = 3869 total\n--------------------------------------------------\n\n{\n  \"top_candidates\": [\n    {\n      \"rank\": 1,\n      \"username\": \"fermin_tech\",\n      \"final_match_score\": 0.92,\n      \"match_breakdown\": {\n        \"required_skills_score\": 1.0,\n        \"repository_relevance_score\": 0.9,\n        \"experience_score\": 0.8,\n        \"profile_quality_score\": 0.9\n      },\n      \"key_qualifications\": [\"Go\", \"Microservices\", \"Cloud\"],\n      \"match_reasoning\": \"Strong match with active Go repositories...\"\n    }\n  ],\n  \"summary\": {\n    \"total_candidates_found\": 12,\n    \"candidates_presented\": 10,\n    \"average_match_score\": 0.78,\n    \"search_quality\": \"excellent\"\n  }\n}\n\nTotal execution time: 9.35 seconds\nTotal LLM calls: 3\nTotal GitHub API calls: 14\nMemory usage: Alloc = 25 MiB...\n```\n\n## Project Structure\n\n```\nsourcing-agent/\n├── main.go               # Entry point, client initialization, observability setup\n├── pkg/\n│   ├── agent/            # Core Agent Logic\n│   │   ├── agent.go      # Pipeline orchestration (RunStage2)\n│   │   ├── prompts.go    # System prompts for each step\n│   │   └── types.go      # Data structures (Requirements, Strategy, etc.)\n│   ├── github/           # GitHub API Client\n│   ├── llm/              # LLM Interface definition\n│   ├── observability/    # Metrics (CountingTransport, CountingLLMClient)\n│   └── vertexai/         # Vertex AI specific implementation\n└── docs/                 # Design documents (Stage 1, Stage 2)\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n| :--- | :--- | :--- |\n| `VERTEX_PROJECT_ID` | Yes | Your Google Cloud Project ID |\n| `VERTEX_REGION` | Yes | Your Google Cloud Region (e.g., us-central1) |\n| `GITHUB_TOKEN` | Yes | Your GitHub Personal Access Token |\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluillyfe%2Fsourcing-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluillyfe%2Fsourcing-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluillyfe%2Fsourcing-agent/lists"}