# interview-agent

**Repository Path**: dantes_admin/interview-agent

## Basic Information

- **Project Name**: interview-agent
- **Description**: 使用Deep Agent创建的AI面试官项目
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# InterviewAgent

AI Mock Interview + Resume Evaluation + RAG Knowledge Base Platform

## Architecture

```
Agent Harness (deepagents + LangGraph)
├── Phase 1: Resume Management (upload → Tika → SHA-256 dedup → Redis Stream → AI analysis)
├── Phase 2: Mock Interview (question generation → Q&A → batch evaluation → PDF report)
├── Phase 3: Knowledge Base + RAG (vectorization → hybrid search → SSE streaming chat)
└── Phase 4: Integration (rate limiting → idempotency → E2E tests)
```

## Quick Start

### Prerequisites
- Docker Desktop
- Python 3.12+
- DeepSeek API Key
- DashScope API Key (for embeddings)

### 1. Clone & Configure
```bash
git clone <repo>
cd interview-agent
cp .env.example .env
# Edit .env with your API keys
```

### 2. Start Infrastructure
```bash
docker compose up -d
# Starts PostgreSQL 14 + pgvector, Redis 6, Apache Tika
```

### 3. Install Dependencies
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 4. Run Migrations
```bash
alembic upgrade head
```

### 5. Start Services
```bash
# Terminal 1: Web API
python scripts/start_web.py

# Terminal 2: Background Workers (resume analysis + interview evaluation + KB vectorization)
python scripts/start_consumers.py
```

### 6. Verify
```bash
curl http://localhost:8000/api/health
# → {"status": "ok", "service": "InterviewAgent"}

curl http://localhost:8000/api/resumes/health
# → {"status": "ok", "module": "resumes"}
```

## API Endpoints

| Module | Endpoints | Description |
|--------|-----------|-------------|
| Resumes | 7 | Upload, List, Detail, Delete, Reanalyze, Export PDF, Health |
| Interview | 11 | Create/Get/Delete Session, Current Question, Submit/Stage Answer, Complete, Report, Export |
| Knowledge Base | 11 | Upload, List, Detail, Delete, Revectorize, Download, Categories, Stats, Search, Health |
| RAG Chat | 8 | Create/List/Get Session, Update Title, Toggle Pin, Rebind KBs, Delete, Stream Message |

## Tech Stack

- **Backend**: Python 3.12, FastAPI, Uvicorn
- **Agent Framework**: deepagents v0.4.12 + LangGraph v1.1.3
- **Chat Model**: DeepSeek V4 Pro (main) + DeepSeek V4 Flash (summarization)
- **Embedding Model**: DashScope text-embedding-v3 (1024-dim)
- **Database**: PostgreSQL 14 + pgvector (HNSW + cosine)
- **Cache/Queue**: Redis 6 (Stream + Session Cache + Rate Limiting)
- **File Parsing**: Apache Tika 2.9 (Docker)

## Project Structure

```
interview-agent/
├── src/
│   ├── core/          # Config, DB (async/sync), Redis Stream, SSE, Exceptions
│   ├── agent/         # Agent Harness: main_agent, middlewares, prompts, subagents, tools
│   ├── models/        # SQLAlchemy ORM: resume, interview, knowledge
│   ├── schemas/       # Pydantic v2: request/response models
│   ├── services/      # Business logic: LLM, embeddings, file parsing, RAG, etc.
│   ├── tasks/         # Redis Stream consumers (3 workers)
│   └── api_view/      # FastAPI: routers, middleware, agent loader
├── alembic/           # Database migrations
├── docker/            # Docker init scripts
├── scripts/           # Start scripts
└── tests/             # pytest + pytest-asyncio
```

## Configuration

All settings via environment variables (see `.env.example`):

| Variable | Default | Description |
|----------|---------|-------------|
| `DEEPSEEK_API_KEY` | — | DeepSeek API key |
| `DASHSCOPE_API_KEY` | — | DashScope API key (embeddings) |
| `DATABASE_URL` | `postgresql+asyncpg://...` | PostgreSQL connection |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis connection |
| `TIKA_URL` | `http://localhost:9998` | Tika server URL |
| `EMBEDDING_MODEL` | `text-embedding-v3` | Embedding model name |
| `LLM_TIMEOUT` | `180` | LLM request timeout (seconds) |

## Key Design Decisions

1. **Agent Harness Architecture**: All business pipelines (resume analysis, question generation, evaluation, RAG) run through the Agent harness for stability — unified timeout, retry, error recovery, SSE streaming.
2. **Dual Engine**: FastAPI uses async (asyncpg), consumer processes use sync (psycopg) for langchain-postgres compatibility.
3. **Redis Stream**: Single consumer group, single thread, ACK-on-success, retry ≤3 for all async tasks.
4. **Configurable Models**: Chat and embedding models are fully configurable via environment variables.