diff --git a/.env.example b/.env.example index 9b77206..79dc92b 100644 --- a/.env.example +++ b/.env.example @@ -22,7 +22,7 @@ SERVE_STATIC_PAGES=true # ----------------------------------------------------------------------------- # 2. LLM PROVIDERS (Choose ONE for LLM_PROVIDER) -# Options: "gemini" (recommended), "nvidia-nim", "groq", "openai", "mock" (offline & free) +# Options: "gemini", "nvidia-nim", "groq", "openai", "anthropic", "openrouter", "mock" (offline & free) # ----------------------------------------------------------------------------- LLM_PROVIDER=mock @@ -32,8 +32,8 @@ GEMINI_MODEL=gemini-3.5-flash-lite GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta # Gemini Live realtime interviews (direct browser audio with a constrained, -# one-use ephemeral token). For the local panel demo, set this to true and -# open http://localhost:8000/app/interview.html?demo=1. +# one-use ephemeral token). Set this to true to enable live interviews; open +# an interview from a real shortlisted application to exercise the full flow. GEMINI_LIVE_ENABLED=true GEMINI_LIVE_MODEL=gemini-3.8-live GEMINI_LIVE_VOICE=Aoede @@ -58,6 +58,14 @@ OPENAI_API_KEY=your_openai_api_key_here OPENAI_MODEL=gpt-4-turbo-preview # OPENAI_ORGANIZATION=your_org_id +# Anthropic Claude +ANTHROPIC_API_KEY=your_anthropic_api_key_here +ANTHROPIC_MODEL=claude-3-5-sonnet-latest + +# OpenRouter (OpenAI-compatible endpoint) +OPENROUTER_API_KEY=your_openrouter_api_key_here +OPENROUTER_MODEL=openai/gpt-4o-mini + # ----------------------------------------------------------------------------- # 3. EMBEDDINGS & VECTOR STORE # ----------------------------------------------------------------------------- @@ -101,9 +109,9 @@ DATABASE_URL= # ----------------------------------------------------------------------------- # 6. AUTHENTICATION & SECURITY (JWT) # ----------------------------------------------------------------------------- -# AUTH_ENABLED=false serves all requests as anonymous principal (development default). -# In production, set AUTH_ENABLED=true and supply a secure JWT_SECRET_KEY. -AUTH_ENABLED=false +# Profile, account, and BYOK pages require authenticated user identities. +# Set false only for anonymous local API experiments; never for the frontend. +AUTH_ENABLED=true AUTH_REQUIRED_BY_DEFAULT=false # CRITICAL FOR PRODUCTION: Generate with python3 -c "import secrets; print(secrets.token_urlsafe(32))" @@ -128,7 +136,7 @@ CORS_MAX_AGE=600 # ----------------------------------------------------------------------------- # 8. BRING YOUR OWN KEY (BYOK) ENCRYPTION # ----------------------------------------------------------------------------- -# 32-byte urlsafe base64 Fernet key used to encrypt candidate-provided API keys at rest. +# 32-byte urlsafe base64 Fernet key used to encrypt recruiter-provided LLM keys at rest. # Optional: if unset, BYOK endpoints remain disabled. # Generate with: python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" BYOK_ENCRYPTION_KEY= diff --git a/.gitignore b/.gitignore index 1532533..52a6b5c 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ *.cert *.dump *.sql +!repositories/postgres/migrations/*.sql scripts/restore_rds.sh # Python Artifacts & Bytecode diff --git a/README.md b/README.md index 53a081b..6481c96 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,10 @@ GEMINI_API_KEY=your_gemini_api_key Start the API and open: ```text -http://localhost:8000/app/interview.html?demo=1 +Open an interview from a shortlisted application to exercise the live interview flow. ``` -The demo endpoint is unavailable in staging and production. +The standalone demo endpoint is retired; live interviews require a persisted job and shortlisted application. --- diff --git a/api/dependencies.py b/api/dependencies.py index da5e43b..6fd9868 100644 --- a/api/dependencies.py +++ b/api/dependencies.py @@ -14,6 +14,36 @@ from core.security import Principal, PrincipalType, require_authenticated +async def resolve_candidate_practice_llm_provider( + *, principal: Principal, job_id: str, candidate_id: str, + application_id: str | None, settings: AppSettings, container, + jobs, candidate_service, +): + """Resolve candidate BYOK only for the owner's candidate-created mock job.""" + if not ( + settings.auth_enabled and settings.byok_encryption_key + and principal.principal_type is PrincipalType.CANDIDATE + and principal.subject_id and application_id is None + ): + return None + from core.errors import NotFoundError + + try: + job = await jobs.get_job(job_id) + except NotFoundError: + return None + if not job.is_practice or job.created_by_user_id != principal.subject_id: + return None + await candidate_service.validate_candidate_ownership(candidate_id, principal.subject_id) + from services.llm_credential_service import LLMCredentialService + + service = LLMCredentialService( + credential_repository=container.llm_credential_repository, + encryption_key=settings.byok_encryption_key, + ) + return await service.resolve_provider_for_user(principal.subject_id) + + async def apply_llm_context_for_recruiter( principal: Principal = Depends(require_authenticated), settings: AppSettings = Depends(get_settings), diff --git a/api/models_llm_credentials.py b/api/models_llm_credentials.py index cd86b50..4ae96c7 100644 --- a/api/models_llm_credentials.py +++ b/api/models_llm_credentials.py @@ -9,10 +9,7 @@ from core.errors import BadRequestError from repositories.interfaces import CredentialStatus, LLMCredentialRecord -# Gemini-only for now - the other three native providers remain fully -# supported in `build_provider` and can be re-enabled here later without a -# schema migration. -_SUPPORTED_PROVIDERS = {"gemini"} +_SUPPORTED_PROVIDERS = {"openai", "gemini", "anthropic", "groq", "nvidia_nim", "openrouter"} class SaveLLMCredentialRequest(BaseModel): @@ -20,6 +17,8 @@ class SaveLLMCredentialRequest(BaseModel): provider: str = Field(min_length=1) api_key: str = Field(min_length=1) + name: Optional[str] = Field(default=None, min_length=1, max_length=80) + credential_id: Optional[str] = None model: Optional[str] = None def validate_provider(self) -> None: @@ -31,22 +30,35 @@ def validate_provider(self) -> None: class LLMCredentialResponse(BaseModel): + credential_id: str + name: str provider: str model: Optional[str] key_hint: str status: CredentialStatus last_error: Optional[str] last_error_at: Optional[str] + health_status: str = "not_tested" + auth_status: str = "unknown" + last_tested_at: Optional[str] = None + last_successful_test_at: Optional[str] = None + health_error_code: Optional[str] = None @classmethod def from_domain(cls, record: LLMCredentialRecord) -> "LLMCredentialResponse": return cls( + credential_id=record.credential_id, + name=record.name, provider=record.provider, model=record.model, key_hint=record.key_hint, status=record.status, last_error=record.last_error, last_error_at=record.last_error_at.isoformat() if record.last_error_at else None, + health_status=record.health_status, auth_status=record.auth_status, + last_tested_at=record.last_tested_at.isoformat() if record.last_tested_at else None, + last_successful_test_at=record.last_successful_test_at.isoformat() if record.last_successful_test_at else None, + health_error_code=record.health_error_code, ) @@ -56,6 +68,7 @@ class TestLLMCredentialRequest(BaseModel): provider: Optional[str] = "gemini" api_key: Optional[str] = None model: Optional[str] = None + credential_id: Optional[str] = None def validate_provider(self) -> None: if self.provider and self.provider not in _SUPPORTED_PROVIDERS: @@ -73,9 +86,42 @@ class TestLLMCredentialResponse(BaseModel): message: str +class LLMCredentialSettingsRequest(BaseModel): + model_config = ConfigDict(extra="forbid") + mode: str + default_credential_id: Optional[str] = None + provider: Optional[str] = None + fallback_to_other_keys: bool = True + fallback_to_platform: bool = True + model: Optional[str] = None + + def validate_mode(self) -> None: + if self.mode not in {"byok", "platform"}: + raise BadRequestError("Mode must be 'byok' or 'platform'.") + if self.provider and self.provider not in _SUPPORTED_PROVIDERS: + raise BadRequestError( + f"Unsupported provider {self.provider!r}. " + f"Supported: {', '.join(sorted(_SUPPORTED_PROVIDERS))}." + ) + + +class LLMCredentialMetadataRequest(BaseModel): + model_config = ConfigDict(extra="forbid") + name: Optional[str] = Field(default=None, min_length=1, max_length=80) + model: Optional[str] = None + provider: Optional[str] = None + api_key: Optional[str] = Field(default=None, min_length=1) + + def validate_provider(self) -> None: + if self.provider and self.provider not in _SUPPORTED_PROVIDERS: + raise BadRequestError(f"Unsupported provider {self.provider!r}.") + + __all__ = [ "LLMCredentialResponse", "SaveLLMCredentialRequest", "TestLLMCredentialRequest", "TestLLMCredentialResponse", + "LLMCredentialSettingsRequest", + "LLMCredentialMetadataRequest", ] diff --git a/api/routes/auth.py b/api/routes/auth.py index f8915a6..e2076b4 100644 --- a/api/routes/auth.py +++ b/api/routes/auth.py @@ -212,7 +212,12 @@ async def update_my_profile( return UserProfileResponse.from_record(user) -@router.post("/me/password", status_code=status.HTTP_204_NO_CONTENT) +@router.post( + "/me/password", + response_class=Response, + response_model=None, + status_code=status.HTTP_204_NO_CONTENT, +) async def change_my_password( request: ChangePasswordRequest, service: AuthService = Depends(get_auth_service), diff --git a/api/routes/interview.py b/api/routes/interview.py index 1475394..639a165 100644 --- a/api/routes/interview.py +++ b/api/routes/interview.py @@ -25,6 +25,7 @@ from api.errors import InvalidRequestError from api.exceptions import SessionNotFoundError from core.errors import ConflictError, NotFoundError +from api.dependencies import resolve_candidate_practice_llm_provider from api.models import ( CreateSessionRequest, CreateSessionResponse, @@ -41,7 +42,11 @@ get_candidate_service, get_evaluation_service, get_interview_service, + get_job_service, ) +from core.config import get_settings +from core.dependencies import get_container +from core.llm_context import reset_context_provider, set_context_provider from core.security import Principal, get_principal, require_authenticated from repositories.interfaces import EvaluationJob, EvaluationStatus from schemas.application import ApplicationStatus @@ -49,6 +54,7 @@ from services.candidate_service import CandidateService from services.evaluation_service import EvaluationService from services.interview_service import InterviewService +from services.job_service import JobService from utils.interview_session import SessionStatus router = APIRouter(prefix="/sessions", tags=["interview"]) @@ -132,6 +138,9 @@ async def create_session( service: InterviewService = Depends(get_interview_service), applications: ApplicationService = Depends(get_application_service), candidate_service: CandidateService = Depends(get_candidate_service), + jobs: JobService = Depends(get_job_service), + container=Depends(get_container), + settings=Depends(get_settings), principal: Principal = Depends(require_authenticated), ) -> CreateSessionResponse: """POST /sessions - create an interview session and ask the first @@ -200,13 +209,28 @@ async def create_session( application_id=payload.application_id, ) - session_id, runner = await service.create_session( - job_description=payload.job_description, - parsed_resume=payload.parsed_resume, - candidate_id=payload.candidate_id, - max_questions=payload.max_questions, - application_id=payload.application_id, + # Candidate-owned credentials are intentionally resolved only for a + # candidate's own practice job. Real interview sessions and evaluations + # retain the existing platform/recruiter resolution paths. + practice_provider = await resolve_candidate_practice_llm_provider( + principal=principal, job_id=payload.job_id, + candidate_id=payload.candidate_id, application_id=payload.application_id, + settings=settings, container=container, jobs=jobs, + candidate_service=candidate_service, ) + + context_token = set_context_provider(practice_provider) if practice_provider is not None else None + try: + session_id, runner = await service.create_session( + job_description=payload.job_description, + parsed_resume=payload.parsed_resume, + candidate_id=payload.candidate_id, + max_questions=payload.max_questions, + application_id=payload.application_id, + ) + finally: + if context_token is not None: + reset_context_provider(context_token) # Available to the InterviewSessionError handler, which needs the # runner's status to choose between 409 and 500 (api/errors.py). request.state.runner = runner @@ -231,6 +255,9 @@ async def get_session_state( service: InterviewService = Depends(get_interview_service), evaluations: EvaluationService = Depends(get_evaluation_service), candidate_service: CandidateService = Depends(get_candidate_service), + jobs: JobService = Depends(get_job_service), + container=Depends(get_container), + settings=Depends(get_settings), principal: Principal = Depends(get_principal), ) -> SessionStateResponse: """GET /sessions/{id} - a controlled snapshot of session state. Never @@ -283,6 +310,9 @@ async def submit_answer( service: InterviewService = Depends(get_interview_service), evaluations: EvaluationService = Depends(get_evaluation_service), candidate_service: CandidateService = Depends(get_candidate_service), + jobs: JobService = Depends(get_job_service), + container=Depends(get_container), + settings=Depends(get_settings), principal: Principal = Depends(get_principal), ) -> SubmitAnswerResponse: """POST /sessions/{id}/answers - the candidate's answer is untrusted @@ -302,6 +332,7 @@ async def submit_answer( # Resolved before submitting so the error handler has the runner even if # submit_answer() is what fails. runner = await service.get_runner(session_id) + session_record = await service.get_record(session_id) request.state.runner = runner await _enforce_session_ownership( session_id, runner.candidate_id, principal, @@ -309,7 +340,22 @@ async def submit_answer( allow_public_capability=True, ) - result = await service.submit_answer(session_id, payload.answer_text) + practice_provider = await resolve_candidate_practice_llm_provider( + principal=principal, + job_id=runner.job_description.job_id, + candidate_id=runner.candidate_id, + application_id=session_record.application_id, + settings=settings, + container=container, + jobs=jobs, + candidate_service=candidate_service, + ) + context_token = set_context_provider(practice_provider) if practice_provider is not None else None + try: + result = await service.submit_answer(session_id, payload.answer_text) + finally: + if context_token is not None: + reset_context_provider(context_token) response = SubmitAnswerResponse.from_domain(result) # `runner` is the same object submit_answer() just advanced, so this diff --git a/api/routes/jobs.py b/api/routes/jobs.py index c57d7f9..816c7fb 100644 --- a/api/routes/jobs.py +++ b/api/routes/jobs.py @@ -27,6 +27,7 @@ LeaderboardResponse, ) from core.dependencies import ( + get_container, get_application_service, get_job_service, get_recruiter_service, @@ -34,6 +35,8 @@ from core.config import get_settings from core.errors import ForbiddenError from core.security import Principal, PrincipalType, require_authenticated, require_candidate, require_scopes +from core.llm_context import reset_context_provider, set_context_provider +from core.container import ServiceContainer from services.application_service import ApplicationService from services.job_service import JobPatchValidationError, JobService from services.recruiter_service import RecruiterService @@ -53,6 +56,7 @@ async def create_job( payload: CreateJobRequest, service: JobService = Depends(get_job_service), + container: ServiceContainer = Depends(get_container), principal: Principal = Depends(require_authenticated), ) -> JobResponse: """POST /jobs - analyze raw job-description text (via the existing @@ -71,14 +75,34 @@ async def create_job( if settings.auth_enabled and payload.is_practice and principal.principal_type is not PrincipalType.CANDIDATE: raise ForbiddenError("Only candidate accounts can create mock interviews.") - record = await service.create_job( - description=payload.description, - job_id=payload.job_id, - openings=payload.openings, - title=payload.title, - is_practice=payload.is_practice, - created_by_user_id=principal.subject_id or "user_anonymous", - ) + practice_context = None + if ( + settings.auth_enabled and settings.byok_encryption_key and payload.is_practice + and principal.principal_type is PrincipalType.CANDIDATE and principal.subject_id + ): + from services.llm_credential_service import LLMCredentialService + # Resolve only the authenticated candidate's own settings. This path + # is restricted to candidate-created practice jobs above; real job + # creation and recruiter operations cannot use candidate credentials. + credential_service = LLMCredentialService( + credential_repository=container.llm_credential_repository, + encryption_key=settings.byok_encryption_key, + ) + provider = await credential_service.resolve_provider_for_user(principal.subject_id) + if provider is not None: + practice_context = set_context_provider(provider) + try: + record = await service.create_job( + description=payload.description, + job_id=payload.job_id, + openings=payload.openings, + title=payload.title, + is_practice=payload.is_practice, + created_by_user_id=principal.subject_id or "user_anonymous", + ) + finally: + if practice_context is not None: + reset_context_provider(practice_context) return JobResponse.from_record(record) diff --git a/api/routes/live_interview.py b/api/routes/live_interview.py index 5ea90c5..472ecc0 100644 --- a/api/routes/live_interview.py +++ b/api/routes/live_interview.py @@ -46,13 +46,10 @@ NotFoundError, UnauthorizedError, ) -from core.security import Principal, get_principal, require_authenticated +from core.security import Principal, get_principal, require_authenticated, require_candidate from repositories.interfaces import SessionRecord from schemas.application import ApplicationStatus -from schemas.job import Competency, JobDescription from schemas.live_interview import LiveInterviewStatus -from schemas.resume import ParsedResume -from schemas.rubric import AnchoredCompetency, JobRubric, RubricStatus from services.application_service import ApplicationService from services.candidate_service import CandidateService from services.evaluation_service import EvaluationService @@ -77,71 +74,6 @@ async def issue_live_audio_test_token( return LiveAudioTestTokenResponse(**issued.__dict__) -def _demo_competency(name: str, definition: str, weight: float) -> AnchoredCompetency: - return AnchoredCompetency( - name=name, - definition=definition, - weight=weight, - anchors={ - 1: "No relevant evidence provided.", - 2: "Limited evidence with substantial gaps.", - 3: "Adequate evidence for routine situations.", - 4: "Strong evidence with clear ownership and judgment.", - 5: "Exceptional evidence with measurable impact and depth.", - }, - ) - - -def _demo_context() -> tuple[JobDescription, ParsedResume, JobRubric]: - """Small, deterministic context for exercising only the live panel.""" - job_id = "job_local_live_demo" - candidate_id = "candidate_local_live_demo" - competencies = [ - Competency(name="Problem solving", weight=0.34, importance="critical"), - Competency(name="Technical communication", weight=0.33, importance="high"), - Competency(name="Software design", weight=0.33, importance="high"), - ] - job = JobDescription( - job_id=job_id, - title="Software Engineer", - description=( - "A local realtime interview used to exercise the OpenHire voice " - "panel, interruption handling, captions, and session resumption." - ), - required_skills=["Problem solving", "Software design", "Communication"], - competencies=competencies, - interview_topics=["problem solving", "system design", "project experience"], - ) - resume = ParsedResume( - candidate_id=candidate_id, - candidate_name="Local Candidate", - summary="Software engineer testing the realtime interview experience.", - skills=["Python", "APIs", "Databases", "System design"], - raw_text=( - "Local Candidate is a software engineer with experience building " - "APIs and reliable backend services." - ), - ) - rubric = JobRubric( - rubric_id="rubric_local_live_demo", - job_id=job_id, - version=1, - status=RubricStatus.APPROVED, - competencies=[ - _demo_competency( - "Problem solving", "Breaks down ambiguous technical problems.", 0.34 - ), - _demo_competency( - "Technical communication", "Explains decisions clearly.", 0.33 - ), - _demo_competency( - "Software design", "Designs maintainable software systems.", 0.33 - ), - ], - ) - return job, resume, rubric - - def _response( record: SessionRecord, reconnect_after_seconds: int = 540 ) -> LiveSessionResponse: @@ -315,34 +247,91 @@ async def create_live_session( "/live-sessions/demo", response_model=LiveSessionResponse, status_code=201 ) async def create_demo_live_session( +) -> None: + """Retired: standalone demo records used fabricated job/candidate IDs. + + Every live session must now be created from a persisted job, candidate, + approved rubric, and (for a real application) its application link. + ``interview.html`` bootstraps those through the normal authenticated + application flow instead of writing orphan demo records. + """ + raise NotFoundError( + "Standalone demo sessions are retired. Open an interview from a real shortlisted application." + ) + + +@router.post("/live-sessions/{session_id}/upgrade", response_model=LiveSessionResponse) +async def upgrade_legacy_session( + session_id: str, request: Request, live: LiveInterviewService = Depends(get_live_interview_service), + applications: ApplicationService = Depends(get_application_service), + candidates: CandidateService = Depends(get_candidate_service), container: ServiceContainer = Depends(get_container), settings: AppSettings = Depends(get_app_settings), + principal: Principal = Depends(require_candidate), ) -> LiveSessionResponse: - """Create an isolated local session without the hiring pipeline. + """Upgrade a persisted adaptive session to Gemini Live using its real records. - This endpoint is intentionally unavailable in staging and production. - It persists only in the configured session repository and carries no - application link, so completing it seals the transcript without starting - the evaluation pipeline. + This supports old candidate links that contain only session_id. Recovery + is allowed for an owned shortlisted application, or for the candidate's + own practice job. Unlinked real interviews cannot be reconstructed safely. """ - if settings.environment not in {"development", "test"}: - raise NotFoundError("The live interview session was not found.") - await _ensure_configured_before_creation( + legacy = await container.session_repository.get(session_id) + if legacy is None: + raise NotFoundError("The interview session was not found.") + if legacy.interview_mode == "gemini_live" and legacy.live_state is not None: + return _response( + legacy, reconnect_after_seconds=settings.gemini_live_reconnect_seconds + ) + + user_id = principal.subject_id or "user_anonymous" + await candidates.validate_candidate_ownership(legacy.candidate_id, user_id) + job_record = await container.job_repository.get(legacy.job_id) + if job_record is None: + raise NotFoundError("The job for this interview could not be found.") + + application_id = legacy.application_id + if application_id: + application = await applications.get_application(application_id) + if ( + application.job_id != legacy.job_id + or application.candidate_id != legacy.candidate_id + ): + raise ConflictError("The interview link does not match its application.") + if application.status.value not in ("shortlisted", "interview_linked"): + raise ConflictError("This application is not ready for an interview.") + elif not ( + job_record.is_practice and job_record.created_by_user_id == user_id + ): + raise ConflictError( + "This interview has no linked application and cannot be safely recovered." + ) + + job_description = legacy.job_description or job_record.job + candidate_record = await container.candidate_repository.get(legacy.candidate_id) + parsed_resume = legacy.parsed_resume or ( + candidate_record.resume if candidate_record is not None else None + ) + if parsed_resume is None: + raise NotFoundError("The candidate profile for this interview could not be found.") + + return await create_live_session( + payload=CreateSessionRequest( + candidate_id=legacy.candidate_id, + job_id=legacy.job_id, + job_description=job_description, + parsed_resume=parsed_resume, + application_id=application_id, + ), request=request, - settings=settings, + live=live, + applications=applications, + candidates=candidates, container=container, - recruiter_user_id=None, - ) - job, resume, rubric = _demo_context() - record = await live.create_session( - job_description=job, - parsed_resume=resume, - rubric_snapshot=rubric, - candidate_id=resume.candidate_id, + settings=settings, + principal=principal, ) - return _response(record, reconnect_after_seconds=settings.gemini_live_reconnect_seconds) @router.get("/live-sessions/{session_id}", response_model=LiveSessionResponse) diff --git a/api/routes/llm_credentials.py b/api/routes/llm_credentials.py index f4e2c35..657bf7c 100644 --- a/api/routes/llm_credentials.py +++ b/api/routes/llm_credentials.py @@ -11,6 +11,7 @@ the API sees the same "not found" a disabled feature should show. """ from typing import Optional +from uuid import uuid4 from fastapi import APIRouter, Body, Depends, Response @@ -19,12 +20,15 @@ SaveLLMCredentialRequest, TestLLMCredentialRequest, TestLLMCredentialResponse, + LLMCredentialSettingsRequest, + LLMCredentialMetadataRequest, ) from core.config import AppSettings, get_settings from core.dependencies import get_llm_credential_service -from core.errors import NotFoundError -from core.security import Principal, require_authenticated +from core.errors import BadRequestError, ForbiddenError, NotFoundError +from core.security import Principal, PrincipalType, require_authenticated from services.llm_credential_service import LLMCredentialService +from services.provider_health import PROVIDERS, check_provider, platform_credentials router = APIRouter(prefix="/auth/me", tags=["byok"]) @@ -34,10 +38,135 @@ def _require_byok_enabled(settings: AppSettings = Depends(get_settings)) -> None raise NotFoundError("BYOK is not enabled on this deployment.") +async def _require_recruiter( + principal: Principal = Depends(require_authenticated), + settings: AppSettings = Depends(get_settings), +) -> Principal: + if not settings.auth_enabled: + return principal + if principal.principal_type not in (PrincipalType.CANDIDATE, PrincipalType.RECRUITER, PrincipalType.ADMIN): + raise ForbiddenError("BYOK is available to signed-in accounts.") + return principal + + +_require_account = _require_recruiter + + +@router.get("/llm-provider-health", dependencies=[Depends(_require_byok_enabled)]) +async def get_provider_health(service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + """Health view scoped to this account; platform keys are only reported as status.""" + credentials = await service.list(principal.subject_id) + settings = await service.get_settings(principal.subject_id) + rows = [] + for record in credentials: + rows.append({"provider": record.provider, "credential_id": record.credential_id, "name": record.name, + "model": record.model or "provider default", "status": record.health_status, + "auth_status": record.auth_status, "connected": record.health_status == "connected", + "last_tested_at": record.last_tested_at.isoformat() if record.last_tested_at else None, + "last_successful_test_at": record.last_successful_test_at.isoformat() if record.last_successful_test_at else None, + "error_code": record.health_error_code, "message": record.last_error}) + configured = platform_credentials() + saved_platform_health = {row["provider"]: row for row in await service.get_platform_health()} + for provider in PROVIDERS: + key, model, _ = configured[provider] + checked = saved_platform_health.get(provider, {}) + last_test = checked.get("last_tested_at") + last_success = checked.get("last_successful_test_at") + rows.append({"provider": provider, "credential_id": "platform", "name": "OpenHire Platform", + "model": checked.get("model") or model, "status": checked.get("status") or ("not_tested" if key else "not_configured"), + "auth_status": checked.get("auth_status") or ("not_tested" if key else "not_configured"), "connected": checked.get("status") == "connected", + "last_tested_at": last_test.isoformat() if hasattr(last_test, "isoformat") else last_test, + "last_successful_test_at": last_success.isoformat() if hasattr(last_success, "isoformat") else last_success, + "error_code": checked.get("error_code"), + "message": checked.get("message") or ("Test connection to verify the platform key." if key else "No platform key configured.")}) + return {"mode": settings.get("mode", "platform"), "providers": rows} + + +@router.post("/llm-provider-health/test", dependencies=[Depends(_require_byok_enabled)]) +async def test_provider_health(payload: TestLLMCredentialRequest, service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + payload.validate_provider() + provider = payload.provider or "gemini" + configured = platform_credentials() + if provider not in configured: + raise BadRequestError(f"Unsupported provider {provider!r}.") + if payload.credential_id == "platform": + key, model, _ = configured[provider] + result = await check_provider(provider, key, payload.model or model) + if principal.principal_type is PrincipalType.ADMIN: + await service.save_platform_health(provider, result) + elif payload.credential_id: + result = await service.test_saved(principal.subject_id, payload.model, payload.credential_id) + elif payload.api_key: + result = await service.test_key(provider=provider, api_key=payload.api_key.strip(), model=payload.model) + else: + key, model, _ = configured[provider] + result = await check_provider(provider, key, payload.model or model) + return result + + +@router.get("/llm-credentials", dependencies=[Depends(_require_byok_enabled)]) +async def list_llm_credentials(service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + return [LLMCredentialResponse.from_domain(r) for r in await service.list(principal.subject_id)] + + +@router.post("/llm-credentials", response_model=LLMCredentialResponse, dependencies=[Depends(_require_byok_enabled)]) +async def create_llm_credential(payload: SaveLLMCredentialRequest, service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + payload.validate_provider() + record = await service.save(user_id=principal.subject_id, credential_id=str(uuid4()), name=payload.name or "My API key", provider=payload.provider, api_key=payload.api_key, model=payload.model) + settings = await service.get_settings(principal.subject_id) + if not settings.get("default_credential_id"): + settings["default_credential_id"] = record.credential_id + await service.save_settings(principal.subject_id, settings) + return LLMCredentialResponse.from_domain(record) + + +@router.patch("/llm-credentials/{credential_id}", response_model=LLMCredentialResponse, dependencies=[Depends(_require_byok_enabled)]) +async def update_llm_credential(credential_id: str, payload: LLMCredentialMetadataRequest, service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + current = await service.get_by_id(principal.subject_id, credential_id) + if current is None: + raise NotFoundError("Credential not found.") + if payload.api_key: + payload.validate_provider() + record = await service.save( + user_id=principal.subject_id, credential_id=credential_id, + name=payload.name if payload.name is not None else current.name, + provider=payload.provider or current.provider, api_key=payload.api_key, + model=payload.model if "model" in payload.model_fields_set else current.model, + ) + return LLMCredentialResponse.from_domain(record) + record = await service.update_metadata(principal.subject_id, credential_id, name=payload.name, model=payload.model, name_provided="name" in payload.model_fields_set, model_provided="model" in payload.model_fields_set) + if record is None: + raise NotFoundError("Credential not found.") + return LLMCredentialResponse.from_domain(record) + + +@router.delete("/llm-credentials/{credential_id}", status_code=204, dependencies=[Depends(_require_byok_enabled)]) +async def delete_llm_credential_by_id(credential_id: str, service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + if not await service.get_by_id(principal.subject_id, credential_id): + raise NotFoundError("Credential not found.") + await service.delete_key(principal.subject_id, credential_id) + + +@router.get("/llm-settings", dependencies=[Depends(_require_byok_enabled)]) +async def get_llm_settings(service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + return await service.get_settings(principal.subject_id) + + +@router.put("/llm-settings", dependencies=[Depends(_require_byok_enabled)]) +async def put_llm_settings(payload: LLMCredentialSettingsRequest, service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + payload.validate_mode() + return await service.save_settings(principal.subject_id, payload.model_dump()) + + +@router.get("/llm-usage", dependencies=[Depends(_require_byok_enabled)]) +async def get_llm_usage(service: LLMCredentialService = Depends(get_llm_credential_service), principal: Principal = Depends(_require_recruiter)): + return await service.get_usage(principal.subject_id) + + @router.get("/llm-credential", response_model=None, dependencies=[Depends(_require_byok_enabled)]) async def get_llm_credential( service: LLMCredentialService = Depends(get_llm_credential_service), - principal: Principal = Depends(require_authenticated), + principal: Principal = Depends(_require_recruiter), ): """GET /auth/me/llm-credential. 204 (no body) when none is saved - never a 404, since "no credential saved" is the normal, expected state @@ -52,7 +181,7 @@ async def get_llm_credential( async def save_llm_credential( payload: SaveLLMCredentialRequest, service: LLMCredentialService = Depends(get_llm_credential_service), - principal: Principal = Depends(require_authenticated), + principal: Principal = Depends(_require_recruiter), ) -> LLMCredentialResponse: """PUT /auth/me/llm-credential. Validates the key with one live call before persisting (400 on failure, writes nothing - see @@ -70,7 +199,7 @@ async def save_llm_credential( @router.delete("/llm-credential", status_code=204, dependencies=[Depends(_require_byok_enabled)]) async def delete_llm_credential( service: LLMCredentialService = Depends(get_llm_credential_service), - principal: Principal = Depends(require_authenticated), + principal: Principal = Depends(_require_recruiter), ) -> None: """DELETE /auth/me/llm-credential. Idempotent - removing an already-absent credential still returns 204.""" @@ -81,7 +210,7 @@ async def delete_llm_credential( async def test_llm_credential( payload: Optional[TestLLMCredentialRequest] = Body(None), service: LLMCredentialService = Depends(get_llm_credential_service), - principal: Principal = Depends(require_authenticated), + principal: Principal = Depends(_require_recruiter), ) -> TestLLMCredentialResponse: """POST /auth/me/llm-credential/test. Tests an entered API key in place without saving, or tests the user's currently saved credential if no key @@ -93,10 +222,14 @@ async def test_llm_credential( api_key=payload.api_key.strip(), model=payload.model, ) + res.setdefault("provider", payload.provider or "gemini") + res.setdefault("message", f"Could not validate {payload.provider or 'gemini'} API key." if not res.get("success") else "API key is valid and the selected model is accessible.") return TestLLMCredentialResponse(**res) res = await service.test_saved( user_id=principal.subject_id, model=payload.model if payload else None, + credential_id=payload.credential_id if payload else None, ) + res.setdefault("message", "API key is valid and the selected model is accessible." if res.get("success") else "Provider connection failed.") return TestLLMCredentialResponse(**res) diff --git a/config/settings.py b/config/settings.py index d42d0e8..ff7651e 100644 --- a/config/settings.py +++ b/config/settings.py @@ -77,6 +77,10 @@ # the primary target. Kept for backward compatibility. GROQ_API_KEY = os.getenv("GROQ_API_KEY", "") GROQ_MODEL = os.getenv("GROQ_MODEL", "openai/gpt-oss-20b") +ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "") +ANTHROPIC_MODEL = os.getenv("ANTHROPIC_MODEL", "claude-3-5-sonnet-latest") +OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY", "") +OPENROUTER_MODEL = os.getenv("OPENROUTER_MODEL", "openai/gpt-4o-mini") # Embedding Configuration # Default: mock provider for offline development (no API key required). diff --git a/docs/byok.md b/docs/byok.md index 78d1c1a..2a26cb6 100644 --- a/docs/byok.md +++ b/docs/byok.md @@ -1,78 +1,47 @@ # Bring Your Own Key (BYOK) -A user can save their own LLM provider API key on their profile page -(`pages/profile.html`, "API Keys" card). The credential storage, encryption, -and API are provider-agnostic infrastructure, and the supported provider -is currently narrowed to Gemini (see "Supported providers" below). - -**Pipeline Resolution:** -- **Recruiter keys:** When an authenticated recruiter saves a key, `apply_llm_context_for_recruiter` - (`api/dependencies.py`) resolves that key for synchronous operations like job description analysis - (`POST /jobs`) and resume matching (`POST /jobs/{job_id}/match`). During post-interview evaluation - (`services/evaluation_service.py`), the job's owning recruiter's key is resolved to run evaluations. -- **Candidate keys:** Candidate credentials can be saved and managed on their profile page. Connecting - a candidate's saved key directly to candidate-facing interview question generation is a documented - follow-up. - -## Enabling it - -Set `BYOK_ENCRYPTION_KEY` to a Fernet key: - -```bash -python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" +BYOK settings are per account. Recruiters may use their selected credentials +for their existing AI operations. Candidate credentials are available in the +same Profile → API Keys section, but are resolved only when the authenticated +candidate starts a practice interview against a practice job they created. +Candidate keys are not attached to real interview sessions, resume processing, +evaluation, scoring, reports, or recruiter actions. Candidate practice +interview usage is attributed to that candidate's selected credential. + +The profile API Keys card supports an encrypted, recruiter-owned LLM credential. +Configure `BYOK_ENCRYPTION_KEY` as a Fernet key to enable the feature; generate +one with: + +```sh +python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" ``` -Unset (the default), BYOK is completely inert: the credential table is -never read, and the profile page shows an explanatory placeholder instead -of the form. - -## Supported providers - -Gemini only, for now. The underlying provider infrastructure -(`build_provider`, the Postgres schema's CHECK constraint) still supports -all four native providers (`openai`, `gemini`, `groq`, `nvidia_nim`), but -API-level request validation and the profile page's UI are deliberately -narrowed to `gemini` — the other three can be re-enabled later without a -schema migration. No `litellm`-style universal routing regardless. - -## API - -- `GET /auth/me/llm-credential` → `{provider, model, key_hint, status, - last_error, last_error_at}`, or `204` when none is saved. -- `PUT /auth/me/llm-credential` → body `{provider, api_key, model?}`. Makes - one live validation call before saving; a bad key returns `400` and - writes nothing. -- `POST /auth/me/llm-credential/test` → body `{provider?, api_key?, model?}`. - Tests an entered key (or the saved credential if `api_key` is omitted) - in place against the provider without saving, returning - `{success, provider, model, latency_ms, message}`. -- `DELETE /auth/me/llm-credential` → removes the credential; the account - reverts to OpenHire's system key. - -All four require an authenticated principal (`require_authenticated`) -— unauthenticated requests get `401`. None of them ever returns the key itself. - -## Key handling - -The key is encrypted at rest (`cryptography.Fernet`) and decrypted only in -memory, for the duration of one provider construction. It is never logged, -never included in any API response, never written to an `AuditLog` entry, -and the profile page never writes it to `localStorage`, `sessionStorage`, -or a cookie. - -## Failure behaviour - -If a saved key stops working (revoked, rate-limited), that one call falls -back to OpenHire's system key automatically and the credential is marked -`status: "failed"` with `last_error` — surfaced on the profile page. (This -fallback mechanism is exercised today only by the still-recruiter-wired -call sites described above, since those never actually resolve a -candidate's credential under the current access model.) - -## Supersedes - -This replaces the August design in `docs/superpowers/specs/2026-08-25-byok-design.md` -and `docs/superpowers/plans/2026-08-25-byok.md`, written when OpenAI was -the only provider and before a real accounts system existed. See -`docs/superpowers/specs/2026-09-06-byok-design.md` for the full design -this implementation follows. +Keep the value stable across restarts and backups. Losing or rotating it without +re-encrypting stored credential ciphertext makes saved keys unreadable. When the +setting is empty, the BYOK API stays disabled and provider resolution continues +to use the existing platform configuration. + +Recruiters can save multiple credentials, including multiple keys from one +provider. Each credential has a user-defined name and provider model. Keys are +encrypted at rest and APIs return only a masked suffix. Each recruiter chooses +BYOK or platform mode, a default credential and per-key model, and whether +failed calls may try another saved key or platform credentials. These settings +are scoped to that recruiter. Usage is tracked per credential and provider; +provider-reported token totals are used where available, with estimates for +adapters that do not report usage. + +Supported key providers are OpenAI, Gemini, Anthropic, Groq, NVIDIA NIM, and +OpenRouter. Credential save/test performs a live provider request; the test +suite mocks provider responses and never reports a mock as a live key check. + +For existing PostgreSQL deployments, apply +`repositories/postgres/migrations/20261102_byok_multi_credentials.sql` once +after the previous BYOK schema has been created. It assigns an ID and default +name to each existing row, preserving its encrypted key and user association, +then creates the per-user settings and usage tables. New databases can use +`repositories/postgres/schema.sql` directly. + +Use the profile page's **API Keys** section to create/test credentials, edit a +credential name or model, set its default, configure fallback behavior, or +switch that recruiter to platform keys. Deleting a credential removes only +that credential; its aggregate usage history remains available to its owner. diff --git a/pages/create-job.html b/pages/create-job.html index cde16b3..fe91d4a 100644 --- a/pages/create-job.html +++ b/pages/create-job.html @@ -9,7 +9,7 @@ - + @@ -50,15 +50,19 @@

Job details

+
+ - + + - + diff --git a/pages/job-detail.html b/pages/job-detail.html index ede83fd..194f4a2 100644 --- a/pages/job-detail.html +++ b/pages/job-detail.html @@ -9,7 +9,7 @@ - + @@ -40,7 +40,7 @@

- + +
@@ -13,12 +13,18 @@

Start a mock interview

Private practice
+ +

+

Your mock interviews

Loading mock interviews…

- + diff --git a/pages/profile.html b/pages/profile.html index 40258f5..74c628d 100644 --- a/pages/profile.html +++ b/pages/profile.html @@ -9,7 +9,7 @@ - + @@ -98,7 +98,7 @@

API Keys

- + diff --git a/pages/recruiter.html b/pages/recruiter.html index bac71db..524a8a9 100644 --- a/pages/recruiter.html +++ b/pages/recruiter.html @@ -10,7 +10,7 @@ - + @@ -76,8 +76,8 @@

${job.ti ${(job.competencies || ['Technical']).slice(0, 3).map(c => `${c}`).join('')}
-
+
+

AI settings for retry scoring

+
+
+
0
@@ -91,10 +96,11 @@

- +