add readme, add defaults and uuid creation in routes

README.md

@@ -1 +1,62 @@
-# score_profiles
+# score_profiles
+
+AI-powered LinkedIn candidate sourcing and scoring microservice.
+
+## Features
+
+- FastAPI HTTP API with a `/jobs` endpoint  
+- URL extraction, SerpAPI search, GitHub & LinkedIn profile clients  
+- Profile data extraction & ranking via a `CandidateScorer`  
+- CORS enabled for all origins  
+- Comprehensive unit & integration tests using `pytest`, `respx` & FastAPI `TestClient`
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.12+
+- `uv` or `pip`
+- `.env` file copied from `.env.example`, populated with your api keys
+
+### Installation
+
+```sh
+# Using pip
+pip install -r requirements.txt
+# or using poetry
+uv sync
+```
+
+### Configuration
+
+Copy `.env.example` to `.env` and populate with your own fields:
+
+Additionally, check is you want to change any configs in `config.py` (though the defaults are sensible).
+
+### Running the Service
+
+```sh
+python app/main.py
+```
+
+Docker based setup is not ready yet.
+
+The API docs are available at `http://localhost:8000/docs`.
+
+## Testing
+
+All HTTP calls are stubbed using [`respx`](https://github.com/lundberg/respx) and fixtures under `test/data/`.
+
+```sh
+pytest
+```
+
+## Workflow
+
+1. Client POSTs to `/jobs` with `search_query` (job description).  
+2. `LinkedInSourcingAgent` orchestrates:
+   - `SerpAPIClient.search` → get LinkedIn & GitHub URLs  
+   - `LinkedInProfileClient.fetch_profile` & `GitHubClient.fetch_github_profile_html`  
+   - `LinkedInProfileExtractor` & `GitHubProfileExtractor` → normalized profile dicts  
+   - `CandidateScorer.batch_score_candidates` → rank & filter  
+3. Returns top-N scored

app/api/routes.py

@@ -1,4 +1,5 @@
 from fastapi import APIRouter
+import uuid
 from pydantic import BaseModel
 from app.core.job_parser import JobParserAgent
 from app.models.schemas import JobProcessingRequest, JobProcessingResponse
@@ -7,7 +8,7 @@ from app.services.agent import LinkedInSourcingAgent
 router = APIRouter()
 
 class HTTPJobRequest(BaseModel):
-    job_id: str
+    job_id: str = None
     search_query: str
     max_candidates: int = 50
     include_github: bool = False
@@ -15,6 +16,7 @@ class HTTPJobRequest(BaseModel):
 
 @router.post("/jobs", response_model=JobProcessingResponse)
 async def process_job(req: HTTPJobRequest):
+    req.job_id = str(uuid.uuid4())
     parser = JobParserAgent()
     job_desc = await parser.parse(req.search_query)