Skip to content

User Guide

This guide covers the editorial workflow in the Luminarium Proof prototype — from logging in through price capture and assessment.

Key Concepts

Concept Description
MAG Market Assessment Group — a collection of related commodity markets (e.g., Cobalt-London, SA Vegoils)
Market An individual commodity market within a MAG with specific unit, location, and methodology
Contact A market participant (trader, broker, producer) who provides price intelligence
Observation A price data point from any source — calls, chat messages, historical imports
Assessment The process of evaluating observations to produce published prices for a MAG
Assessment Period The date range over which observations are gathered for an assessment
Effective Date The prototype uses historical test data; the effective date picker lets you simulate different dates

Login and Navigation

  1. Navigate to the application URL (Cloudflare Access will authenticate you first)
  2. Log in with your email and password
  3. The sidebar provides navigation:
    • Home — MAG dashboard
    • Contacts — contact directory
    • Calls — call session list
    • Admin (ADMIN role only) — user management

The effective date picker in the header lets you set the date context for the prototype, since test data is from historical periods.

MAG Dashboard

The home page shows all Market Assessment Groups assigned to you:

  • Search — typeahead search by MAG name or code
  • Columns — MAG name, code, next due date (relative time), average data points, overdue indicators
  • Assess button — starts the assessment workflow for a MAG

Click a MAG row to see its detail page with assessment readiness: market coverage, observation counts, and contact data status.

Price Capture Workflow

Price capture follows the path: call → transcription → extraction → review → observations.

1. Start a Call

Navigate to a contact, then start a call session. The during-call interface shows:

  • Live call timer
  • Expected data points table with last value, change, and trend columns (sparklines)
  • Contact context panel

2. Transcription

After the call ends, the audio recording is transcribed. The prototype supports AI-generated test audio via TTS for evaluation purposes.

3. Extraction

The AI extracts structured price data points from the transcript:

  • Market name, price/range, volume, price type (bid, offer, deal, indication)
  • Forward curve tenor (M1–M6) for vegoils
  • Source references back to transcript lines
  • Confidence scores

4. Post-Call Review

The post-call review page shows extracted data for analyst verification:

  • Each extracted price is shown with its market, value, type, and confidence
  • Market name resolution maps AI-extracted names to database market IDs
  • Analysts accept, reject, or modify extractions
  • Accepted extractions create PriceObservation records

For chat-sourced entries (e.g., from Slack), a right-side panel replaces the audio/transcript UI, showing the original message and attached images.

5. Observations

Accepted price data becomes observations that feed into the assessment pipeline. Observations can come from:

  • Post-call review (most common)
  • Historical data imports (MIND UAT data)
  • Chat sources (Slack price submissions)

Assessment Workflow

Assessment produces published prices for all markets in a MAG.

1. View Assessment Readiness

On the MAG detail page, check readiness: which markets have sufficient observations, which contacts have provided data, and overall coverage.

2. Start Assessment

Click Assess to create or continue an assessment for the current period.

3. Review Observations

The assessment observations view shows:

  • Collapsible sections per market
  • Observations table with contact, price, type, date
  • Include/exclude toggles to control which observations feed the AI

4. Run AI Assessment

Click Run AI to trigger the assessment pipeline:

  1. The system gathers included observations and calculates deterministic statistics
  2. Related market context is fetched (sibling MAG prices, directional indicators)
  3. The LLM assesses each market using the methodology, observations, and statistics
  4. For derived markets (e.g., SYP Lumber formula markets), TypeScript applies formulas to benchmark results
  5. Results are persisted with per-market rationale, confidence, and flags

5. Review AI Results

The AI produces for each market:

  • Assessed price range (low–high)
  • Confidence score
  • Rationale — structured explanation citing specific observations
  • Key drivers — what moved the price
  • Flags — warnings about sparse data, conflicting signals, etc.

6. Approve and Publish

Review the AI proposals, make amendments if needed, then approve. Published prices become FinalMarketPrice records.

Admin Features

Users with the ADMIN role can access:

  • User management — list, create, edit users
  • MAG assignments — assign analysts to MAGs
  • Role management — set user roles (ADMIN / ANALYST)

Navigate to Admin via the sidebar (only visible to ADMIN users).