devmate

AI-assisted teammate discovery for hackathons. The app turns a free-form request into ranked builder matches, complete with transparent agent reasoning and pgvector-backed retrieval.

Highlights

• Planner → executor → evaluator agents coordinate through lib/agents/orchestrator.ts, producing structured telemetry for every request.
• Vector search + metadata filters run against Postgres via Drizzle ORM with pgvector embeddings managed by lib/ai/embeddings.ts.
• React 19 / Next.js 16 front-end in app/page.tsx renders rich result cards, agent reasoning timelines, and benchmark snapshots.
• Observable pipeline with persisted logs (search_logs, search_traces) and per-phase latency metrics to track precision/recall over time.

Architecture at a Glance

1. The user submits a teammate brief from the UI (app/page.tsx).
2. POST /api/search validates the payload with Zod and delegates to the orchestrator.
3. lib/agents/planner.ts (GPT-4.1 mini) normalizes roles, skills, interests, and constructs a capped four-step search plan.
4. lib/agents/executor.ts embeds the requirement, runs multi-pass pgvector retrieval, and annotates candidates with provenance.
5. lib/agents/evaluator.ts (GPT-4.1) blends similarity, deterministic scores, and LLM grading to rank candidates and suggest refinements.
6. lib/agents/orchestrator.ts stitches results, metrics, and reasoning logs, persists them via Drizzle, and returns { success, data }.

> For a deeper walkthrough, see docs/architecture.md.

Key Directories

• app/ – Next.js app router, global styles, and API route.
• lib/agents/ – Planner, executor, evaluator, and orchestrator logic.
• lib/ai/ – OpenRouter provider wrapper plus embedding helpers.
• lib/db/ – Drizzle schema (builder_profiles, search_logs, search_traces, search_metrics) and Postgres client.
• scripts/ – Data seeding (seed.ts), combined setup with embeddings (setup-data.ts), and Windows install-pgvector.ps1.
• docs/ – Project status notes and architecture summaries.

Environment & Prerequisites

• Node.js 18.18 or later.
• PostgreSQL 15+ with the pgvector extension enabled.
• OpenRouter API access (OPENROUTER_API_KEY).
• Recommended: PowerShell 7 for scripting (commands below target Windows PowerShell).

Local Setup

Windows (PowerShell)

1. Install dependencies

   npm install

2. Copy environment template

   Copy-Item .env.example .env

3. Update .env

   • Set OPENROUTER_API_KEY.
   • Set DATABASE_URL (Postgres connection string with pgvector enabled).
   • Optionally override planner/evaluator/embedding models or OpenRouter headers.

4. Install pgvector (Windows helper)

   • Download pgvector build artifacts into %TEMP%\pgvector.

   • Run PowerShell as Administrator:

     .\install-pgvector.ps1

   • In Postgres, enable the extension:

     CREATE EXTENSION IF NOT EXISTS vector;

5. Apply database schema

   npm run db:push

6. Seed demo data and generate embeddings

   npm run db:setup

   (This seeds 50 builder profiles and batches OpenRouter embeddings.)

7. Start the dev server

   npm run dev

8. Visit http://localhost:3000, describe your ideal teammate, and review the ranked results plus agent reasoning stream.

macOS (Terminal)

1. Install system dependencies

   brew install node@20
   brew install postgresql@16
   brew install pgvector
   brew services start postgresql@16

2. Install project dependencies

   npm install

3. Copy environment template

   cp .env.example .env

4. Update .env

   • Set OPENROUTER_API_KEY.
   • Set DATABASE_URL (local Postgres connection string; e.g. postgres://postgres:postgres@localhost:5432/devmate).
   • Optionally override planner/evaluator/embedding models or OpenRouter headers.

5. Create the local database (if needed) and enable pgvector

   createdb devmate
   psql -d devmate -c "CREATE EXTENSION IF NOT EXISTS vector;"

   (Replace devmate with the database named in DATABASE_URL; if the database already exists you can ignore the createdb error.)

6. Apply database schema

   npm run db:push

7. Seed demo data and generate embeddings

   npm run db:setup

8. Start the dev server

   npm run dev

9. Visit http://localhost:3000, describe your ideal teammate, and review the ranked results plus agent reasoning stream.

Developer Scripts

• npm run db:generate – Create Drizzle migrations from the current schema.
• npm run db:migrate – Apply generated migrations.
• npm run db:push – Push schema without generating migrations (recommended for local setup).
• npm run db:seed – Insert synthetic builder profiles (no embeddings).
• npm run db:setup – Seed profiles and compute embeddings in one go.
• npm run db:studio – Launch the Drizzle Studio explorer.
• npm run lint – Run Next.js ESLint checks.

Observability & Data

• Search responses include per-phase metrics (planner, executor, evaluator, refinement) and a reasoning log for debugging.
• search_logs captures the normalized requirement, scores, and latency for each request; search_traces stores the planner plan plus reasoning for later analytics.
• UI benchmark cards compare the latest precision/recall snapshot against the previous run using client-side metrics.
• docs/progress-report.md tracks roadmap items, known gaps, and future optimizations.

Additional Notes

• Absolute imports (@/*) are configured in tsconfig.json.
• Tailwind CSS v4 powers the UI via app/globals.css; no additional CSS framework setup required.
• All agent prompts and model ids are centralized in lib/agents/* and lib/ai/embeddings.ts for quick iteration.