AI Event Intelligence Copilot Prototype

Related documentation: Backend modules overview · Backend implementation · Data ownership · Kisum System

Canonical implementation detail: workspace repository AI-Event-Intelligence-Copilot-Prototype.

Purpose

AI-Event-Intelligence-Copilot-Prototype is a standalone AI-assisted promoter workflow prototype.

Its current job is to accept natural-language event-planning questions, classify the query intent, combine Mongo-backed artist, venue, and agency data with optional live metric refreshes, run deterministic scoring and financial simulations, and return a chat-style answer plus structured metadata for a lightweight UI.

This page documents the prototype as it exists now. It is not the same thing as a formal Kisum Backend-Kisum-* module backend, and it is not yet integrated into the platform Auth/Core control plane.

Current status

Implemented now

Node.js + Express service with static built-in chat UI
Main orchestration endpoint: POST /api/copilot
MongoDB-backed conversation sessions with 30-day TTL
Intent branching for:
- artist_recommendation
- financial_simulation
- market_analysis
- agency_lookup
- similar_artist
- venue_lookup
- general_qa
- clarification_needed
Mongo-backed venue and agency lookup helpers
On-demand artist metric refresh through Viberate and Songstats with pseudo-data fallback
Deterministic artist scoring and simulation output

Present but still scaffolded

Redis + BullMQ worker entrypoints for metrics sync and score precompute
Non-Gemini model env settings

Not true today

No Kisum Auth JWT enforcement
No canonical x-org company-context enforcement
No published internal API contract with Admin/Auth/Core
No evidence that this service is currently a system of record for platform master data

Architectural position

Treat this repository as an adjunct AI prototype service.

It sits closer to experimentation and operator tooling than to the current authoritative platform backend layer:

User / operator → Copilot prototype → Mongo collections + optional external metrics APIs → response

Important boundary:

It may consume business data and produce planning guidance.
It must not be documented as the owner of users, memberships, company entitlements, or canonical shared business master records.

This makes it closer in classification to an AI adjunct service than to the current Finance/Market/Venue production module backends, even though the platform-level module map still reserves an eventual ai business domain.

Runtime shape

API surface

GET /
- serves the built-in static chat UI
GET /health
- returns { "ok": true }
POST /api/copilot
- main conversation/orchestration endpoint

Request contract

{
  "query": "I want to do a concert for Tyga in Indonesia, capacity 5000, ticket $80",
  "session_id": "optional-session-id"
}

Response characteristics

returns free-text assistant output in response
returns structured metadata
returns session information in session
uses snake_case session_id in the request body, unlike the camelCase sessionId used by Chat-Kisum-MCP-Node

That difference matters: these are separate systems and should not be documented as sharing one chat contract.

Data and dependencies

Runtime dependencies

Node.js 22+
MongoDB
Redis
Gemini API key when LLM_PROVIDER=gemini

Mongo-backed concerns used by the current code

conversations
artists
artist metrics
artist scores
venues
companies
company teams
company rosters

External dependencies used by the current implementation

Viberate
Songstats

Soundcharts credentials exist in the environment contract, but the current request path does not treat Soundcharts as a primary active runtime dependency.

Ownership boundaries

Concern	Owner
Users, memberships, JWT issuance, company access	Auth
Company commercial state and entitlements	Core
Shared canonical business entities in the main platform	Base / other domain owners as documented
Financial workflow truth	Finance
Venue operational truth	Venue
Market directory / shared-party truth where applicable	Market
Copilot conversation state, AI output metadata, prototype-local scores/metrics cache	This prototype repo only for its local runtime

Rule:

The prototype may keep operational AI/session/cache data for its own responses, but that does not make it a Kisum master-data owner.

Important current behaviors

Session memory

conversation sessions are stored in MongoDB
sessions expire after 30 days of inactivity
current context tracks country, last intent, genre, and last artist
the stored context window is limited to recent messages

Metrics refresh path

live requests can refresh stale artist metrics directly
the lazy refresh path currently runs inside the request flow
worker scripts exist, but are not yet the authoritative pipeline

Unknown-artist fallback

if an artist is not found in the database, the service returns general-knowledge guidance with a disclaimer instead of hard-failing

Venue and agency enrichment

the route can enrich responses with venue candidates
the route can resolve booking-agency information from Mongo-backed company/team/roster collections

Risks and limitations

The current route orchestration is concentrated in one large Express route module.
The service does not yet enforce the platform auth and tenancy boundary expected from first-class Kisum backends.
Redis is mandatory in env validation even though background workers are still scaffolded.
The current repository documentation had to be corrected to match implementation reality; future changes should keep the README and this page aligned.
No formal automated test harness is documented yet.

How to document it going forward

Describe it as a prototype or adjunct AI service unless the runtime is deliberately moved behind Kisum Auth/Core integration.
Keep its current request contract distinct from Chat-Kisum-MCP-Node.
Do not imply browser clients should treat it like a production control-plane or tenant-source backend.
If the service later gains JWT + x-org enforcement or a formal BFF/internal integration path, update this page and the data-ownership doc immediately.