Ucws Hackathon Agent

UCWS Singapore Hackathon 2026 Agent Track submission.

This is not a shopping chatbot. It is a social shopping operator that turns intent into a saved shortlist and an approval-gated community post.

GenPark Social Shopping Agent turns a shopping intent into an executable social-shopping workflow: it parses budget and needs, searches a product catalog, ranks candidates, saves a shortlist, drafts a Circle social handoff, and waits for explicit confirmation before any publishing side effect.

Judge Quick Start

• Submission brief: SUBMISSION.md
• Demo screenshot: docs/demo-screenshot.png
• Local demo: npm install, npm run dev, open http://localhost:3000
• Best demo prompt is prefilled in the UI

Why This Is An Agent

• Goal-directed workflow: shopping need -> shortlist -> saved collection -> approval-gated Circle handoff.
• Tool use: search, ranking, collection persistence, Circle draft handoff, and optional publishing webhook.
• Memory: the Vercel demo keeps per-session pending approvals, collections, posts, and traces in serverless memory.
• Safety: the community post remains a draft until confirm post; missing Circle publishing setup returns drafted_requires_setup instead of fake success.
• Evaluability: every response includes the plan, tool calls, products, constraints, draft, pending action, run id, observations, decision log, safety checks, next actions, and self-evaluation score.

Demo Flow

Use this prompt:

Find a work-from-home gift under $220 and draft a Circle post asking friends to choose.

Expected behavior:

1. The agent extracts the budget.
2. It searches and ranks products.
3. It saves the top candidates to the demo collection.
4. It drafts a Circle post.
5. It waits for confirm post before any publish attempt.
6. It exposes an operator audit with observations, decisions, safety checks, and the next best action.

If no Circle publishing webhook is configured, the confirmed handoff is saved as an approved draft with drafted_requires_setup. This is intentional: the project does not claim a real side effect happened unless it did.

Run Locally

npm install
npm run dev

Open http://localhost:3000.

For API-only usage:

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"user_id":"demo","session_id":"demo-1","message":"Recommend smart home products under $160 and draft a Circle post"}'

Deploy On Vercel

1. Import https://github.com/Alpha-Park/ucws-hackathon-agent into Vercel.
2. Keep the framework preset as Next.js.
3. Use the default install command npm install.
4. Use the default build command npm run build.
5. Deploy. Vercel will produce the public demo URL.

Optional environment variable:

• GENPARK_CIRCLE_WEBHOOK_URL: if provided, approved Circle drafts are sent to that webhook. Without it, the demo records approved drafts without faking a publish.

API Response Shape

POST /api/chat returns:

• answer: human-readable agent response
• plan: ordered workflow steps
• tool_calls: auditable tool trace
• products: ranked product shortlist
• collection: saved items for the user
• draft_post: proposed Circle post
• pending_action: action requiring user confirmation
• next_action: next instruction for the user
• scorecard: self-evaluation of run completeness and safety
• safety_checks: approval gates and no-fake-side-effect checks
• decision_log: why the agent chose its top actions

Architecture

flowchart LR
    UI["Next.js UI"] --> API["/api/chat Route Handler"]
    API --> Agent["Agent Workflow"]
    Agent --> Catalog["Product Catalog + Ranker"]
    Agent --> Store["Serverless Memory Store"]
    Agent --> Circle["Approval-Gated Circle Webhook"]
    Agent --> Audit["Self-Evaluation + Safety Checks"]

The deterministic workflow powers the hackathon demo so judges can run the product without private API keys. The hosted demo is optimized for public Vercel deployment; production persistence should use a database such as Vercel Postgres, Neon, Supabase, or Upstash.

Project Structure

app/
  page.jsx                Next.js UI
  api/chat/route.js       Agent API endpoint
  api/collection/route.js Collection endpoint
  api/health/route.js     Runtime health endpoint
lib/
  agent.js                Shopping-agent workflow orchestration
  agentIntelligence.js    Objective, audit, safety, scorecard, next actions
  catalog.js              Intent parsing, budget inference, ranking
  products.js             Deterministic demo catalog
  store.js                Serverless in-memory sessions and traces
  toolRegistry.js         Public tool contracts and side-effect policy
tests/
  agent.test.mjs          Workflow tests

Tech Stack

• Next.js
• React
• Vercel
• JavaScript
• API Routes
• Serverless
• Agent Workflow
• Tool Registry
• Approval Gates

Tests

npm test
npm run build

Current Limitations

• Product data is a deterministic local catalog for reproducible judging.
• Hosted demo memory can reset on serverless cold starts; production should use a durable database.
• Circle handoff is demo-safe by default: it drafts and records the approved post, while optional publishing uses GENPARK_CIRCLE_WEBHOOK_URL.
• Image attachment for Circle drafts is not implemented yet.
• For production, replace the catalog with a real GenPark API/search index and move auth behind a proper user session.