setup-genai-dev · diff
git:20260203.566fc00 to git:20260304.0624edd
36 added, 72 removed. Audit A to B.
---
name: setup-genai-dev
description: Set up the GenAI Engine development environment. Use when starting work on the project for the first time, or when environment needs to be reset. Handles Poetry, PostgreSQL, migrations, and environment variables.
- allowed-tools: Bash, Read, Write
+ allowed-tools: Bash, Read, Task
---
# Setup GenAI Engine Development Environment
- ## Prerequisites Check
-
- Before setup, verify these are installed:
- 1. Python 3.12 (`python3 --version`)
- 2. Docker is running (`docker ps`)
- 3. Poetry (`poetry --version`)
-
- If any are missing, inform the user and stop.
-
- ## Setup Steps
-
- Execute these steps in order:
+ ## Step 1 — GPT Key Gate
- ### 1. Navigate to Project Directory
- ```bash
- cd ./genai-engine
- ```
+ Use the Read tool to read `./genai-engine/.env`.
- ### 2. Configure Poetry Environment
- ```bash
- poetry env use 3.12
- poetry install --with dev,linters
- ```
+ Check that `GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS` is present and has a non-empty value (not just `GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS=` with nothing after the `=`).
- ### 3. Start PostgreSQL Database
- ```bash
- docker compose up -d db
- ```
+ If the value is missing or empty:
+ - **STOP immediately. Do not proceed to Step 2.**
+ - Tell the user: "Setup cannot continue. Please open `genai-engine/.env` and set `GENAI_ENGINE_OPENAI_GPT_NAMES_ENDPOINTS_KEYS` using the format: `MODEL_NAME::ENDPOINT_URL::API_KEY` (e.g. `gpt-4o::https://api.openai.com/::sk-...`). Run the skill again once the key is set."
- Wait for healthy status:
- ```bash
- sleep 5
- docker compose ps
- ```
+ ## Step 2 — Delegate Setup to Bash Sub-Agent
- ### 4. Set Environment Variables
+ Only proceed here if Step 1 passed. Spawn a Task sub-agent with subagent_type="Bash" and the following self-contained prompt:
- Export ALL of these environment variables:
- ```bash
- export POSTGRES_USER=postgres
- export POSTGRES_PASSWORD=changeme_pg_password
- export POSTGRES_URL=localhost
- export POSTGRES_PORT=5432
- export POSTGRES_DB=arthur_genai_engine
- export POSTGRES_USE_SSL=false
- export PYTHONPATH="src:$PYTHONPATH"
- export GENAI_ENGINE_SECRET_STORE_KEY="some_test_key"
- export GENAI_ENGINE_ENVIRONMENT=local
- export GENAI_ENGINE_ADMIN_KEY=changeme123
- export GENAI_ENGINE_INGRESS_URI=http://localhost:3030
- export GENAI_ENGINE_ENABLE_PERSISTENCE=enabled
- export ALLOW_ADMIN_KEY_GENERAL_ACCESS=enabled
- ```
+ ---
+ Run the following setup steps for the GenAI Engine development environment. Report success or failure for each step and stop immediately if any step fails.
- ### 5. Run Database Migrations
+ **Step 1 — Prerequisites check:**
```bash
- cd ./genai-engine
- poetry run alembic upgrade head
+ python3 --version && docker ps && poetry --version
```
+ If any fail, report which tool is missing and stop.
- ### 6. Verify Setup
- Check database is running:
+ **Step 2 — Configure Poetry and install dependencies:**
```bash
- docker compose ps
+ cd genai-engine && poetry env use 3.12 && poetry install --with dev,linters
```
- Check migrations applied:
+ **Step 3 — Start PostgreSQL:**
```bash
- poetry run alembic current
+ cd genai-engine && docker compose up -d db && sleep 5 && docker compose ps
```
- ## Output
-
- Report success/failure for each step.
-
- ### LLM Configuration
-
- Check for `OPENAI_API_KEY` in the `.env` file in the `./genai-engine` directory. If present, load it:
+ **Step 4 — Run database migrations with all required env vars:**
```bash
- source ./genai-engine/.env
- export OPENAI_API_KEY
+ cd genai-engine && \
+ set -a && source .env && set +a && \
+ export POSTGRES_USER=postgres \
+ POSTGRES_PASSWORD=changeme_pg_password \
+ POSTGRES_URL=localhost \
+ POSTGRES_PORT=5432 \
+ POSTGRES_DB=arthur_genai_engine \
+ POSTGRES_USE_SSL=false \
+ PYTHONPATH="src:$PYTHONPATH" \
+ GENAI_ENGINE_SECRET_STORE_KEY="some_test_key" \
+ GENAI_ENGINE_ENVIRONMENT=local \
+ GENAI_ENGINE_ADMIN_KEY=changeme123 \
+ GENAI_ENGINE_ENABLE_PERSISTENCE=enabled \
+ ALLOW_ADMIN_KEY_GENERAL_ACCESS=enabled && \
+ poetry run alembic upgrade head && poetry run alembic current
```
- If not present, inform the user they need to add their OpenAI API key to the `.env` file for LLM features to work.
-
- ## Troubleshooting
-
- - If Docker fails: ensure Docker Desktop is running
- - If Poetry fails: try `poetry env remove 3.12` then retry
- - If migrations fail: check PostgreSQL is healthy with `docker compose logs db`
+ Report the final migration revision that is current after running these steps.
+ ---