134 lines
3.4 KiB
Markdown
134 lines
3.4 KiB
Markdown
# AI Platform - Lead Scoring Service
|
|
|
|
Lead Scoring service and internal Dev Console for the AI Platform.
|
|
|
|
## What runs locally
|
|
|
|
| Component | Purpose | Default address |
|
|
| --- | --- | --- |
|
|
| PostgreSQL 16 | Stores scoring runs and migrations | `localhost:5433` |
|
|
| Lead Scoring API | REST API, async scoring worker, OpenAPI | `http://localhost:8000` |
|
|
| Dev Console | Internal fixture and contract-testing UI | `http://localhost:5173` |
|
|
| AIHub | Optional external AI inference dependency | `http://localhost:8080` |
|
|
|
|
The service still runs if local AIHub is unavailable: the default config uses `rules_only_review` fallback. A reachable AIHub and a valid tenant VKey are required for live AI scoring.
|
|
|
|
## Requirements
|
|
|
|
Install before starting:
|
|
|
|
- Git
|
|
- Python 3.13 or newer
|
|
- [uv](https://docs.astral.sh/uv/)
|
|
- [Bun](https://bun.sh/)
|
|
- Docker with Docker Compose plugin
|
|
|
|
## Start from a fresh clone
|
|
|
|
```bash
|
|
git clone https://github.com/HungTran24/dotb_ai-platform.git
|
|
cd dotb_ai-platform
|
|
cp .env.example .env
|
|
cp apps/dev-console/.env.example apps/dev-console/.env
|
|
```
|
|
|
|
The copied `.env` files are local only and ignored by Git. Their example values are intentionally for development only.
|
|
|
|
### 1. Start PostgreSQL
|
|
|
|
```bash
|
|
docker compose up -d postgres
|
|
docker compose ps
|
|
```
|
|
|
|
The included Compose service exposes PostgreSQL on port `5433` to avoid conflicting with other local projects. If port `5433` is occupied, choose another port and update both values before migration:
|
|
|
|
```bash
|
|
POSTGRES_PORT=15432 docker compose up -d postgres
|
|
# Then set DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:15432/lead_scoring in .env
|
|
```
|
|
|
|
### 2. Install backend dependencies and migrate the database
|
|
|
|
```bash
|
|
uv sync
|
|
uv run alembic upgrade head
|
|
```
|
|
|
|
### 3. Start the Lead Scoring API
|
|
|
|
Run in a separate terminal from the repository root:
|
|
|
|
```bash
|
|
uv run uvicorn lead_scoring.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
Check the API:
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
OpenAPI UI: `http://localhost:8000/docs`
|
|
|
|
### 4. Start the Dev Console
|
|
|
|
Run in a second terminal:
|
|
|
|
```bash
|
|
cd apps/dev-console
|
|
bun install --frozen-lockfile
|
|
bun run dev
|
|
```
|
|
|
|
Open `http://localhost:5173`.
|
|
|
|
## Local configuration
|
|
|
|
Root `.env` configures the backend. `apps/dev-console/.env` configures the Vite development server.
|
|
|
|
| Variable | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `DATABASE_URL` | PostgreSQL at `localhost:5433` | Backend database connection |
|
|
| `AIHUB_BASE_URL` | `http://localhost:8080` | Optional AIHub endpoint |
|
|
| `DEV_CONSOLE_API_URL` | `http://localhost:8000` | Dev Console API proxy target |
|
|
| `DEV_CONSOLE_PORT` | `5173` | Dev Console development port |
|
|
| `DEV_CONSOLE_PREVIEW_PORT` | `4173` | Dev Console preview port |
|
|
| `DEV_CONSOLE_SERVICE_TOKEN` | `local-dev-token` | Must match the local backend `SERVICE_CALLERS` entry |
|
|
| `DEV_CONSOLE_TEST_VKEY` | `local-test-vkey` | Forwarded only to AIHub calls; replace for real AIHub use |
|
|
|
|
The local backend template includes an allowlisted `dev-console` caller and baseline scoring config version `1.0.0`, so the Dev Console can open immediately after startup.
|
|
|
|
## Stop local services
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
To remove the local database data too:
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
## Verification
|
|
|
|
Backend:
|
|
|
|
```bash
|
|
uv run pytest
|
|
uv run ruff check src tests
|
|
uv run ruff format --check src tests
|
|
uv run pyright
|
|
uv run ty check
|
|
```
|
|
|
|
Frontend:
|
|
|
|
```bash
|
|
cd apps/dev-console
|
|
bun run check
|
|
bun run test
|
|
bun run build
|
|
```
|