Project-Based Learning (PBL) Endpoints in OpenMAIC: Complete API Reference

OpenMAIC exposes five stateless HTTP endpoints under /api/pbl/v2 that handle project mutations, simulations, task retrieval, instructor actions, and final evaluations for Project-Based Learning workflows.

The OpenMAIC repository implements its Project-Based Learning (PBL) system as a deterministic, server-side API architecture. All PBL functionality is accessible through dedicated routes that process PBLProjectV2 objects and return mutated states to the client without maintaining server-side session data.

API Architecture and Design Principles

The PBL endpoints follow a strict stateless handler pattern located in the app/api/pbl/v2 directory. Each route acts as a thin wrapper that accepts a JSON payload, performs pure deterministic operations on the provided project object, and returns the result via standardized apiSuccess or apiError helpers.

Key architectural constraints include:

• Pure functions: Endpoints never invoke LLMs directly; all logic is deterministic
• Client-side persistence: The caller must store the returned PBLProjectV2 and resend it on subsequent requests
• Standardized contracts: Every endpoint expects a project field in the request body and returns a consistent response shape

The Five Core PBL Endpoints

Task State Management (/api/pbl/v2/task/update)

The POST /api/pbl/v2/task/update endpoint serves as the primary workspace UI state mutator. Implemented in app/api/pbl/v2/task/update/route.ts, this route handles micro-task lifecycle transitions through specific action types.

Supported operations include:

• start: Invokes startMicrotask to begin a new micro-task
• continue_handover: Triggers continueAfterHandover for milestone transitions
• complete_pending_task: Executes advanceMicrotask to finish active tasks
• enter_scenario: Prepares the project state for scene entry
• complete_act: Calls completeRoleplayAct to finalize role-play segments

Project Simulation (/api/pbl/v2/simulator)

Located at app/api/pbl/v2/simulator/route.ts, this POST endpoint runs deterministic simulations of PBL projects. It enables "preview" or "dry-run" functionality by invoking the simulator agent to generate a PBLProjectV2 snapshot without actual LLM involvement, allowing clients to validate project flow before deployment.

Task Retrieval (/api/pbl/v2/open-task)

The GET /api/pbl/v2/open-task endpoint (file: app/api/pbl/v2/open-task/route.ts) retrieves the next available micro-task for a given project. It examines the active milestone structure and returns the associated task configuration used by the frontend to render the current UI state.

Instructor Events (/api/pbl/v2/instructor)

Implemented in app/api/pbl/v2/instructor/route.ts, this POST route processes instructor-driven interactions. It accepts events such as role-play dialogue or act completion signals, invokes the instructor agent to process these events, and applies the resulting state mutations to the project object.

Final Evaluation (/api/pbl/v2/evaluate)

The evaluation endpoint at app/api/pbl/v2/evaluate/route.ts performs comprehensive project assessment. This POST route calls the evaluator agent to score completed milestones and generate structured learner-visible feedback, returning a complete evaluation result object to the client.

Client Integration and Code Examples

The following TypeScript patterns demonstrate how to interact with the OpenMAIC PBL endpoints from a client application:

// Helper to POST JSON and parse responses
async function postPbl<T>(path: string, body: any): Promise<T> {
  const r = await fetch(path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!r.ok) throw new Error(`API error ${r.status}`);
  return r.json();
}

// Start a specific micro-task
await postPbl('/api/pbl/v2/task/update', {
  project,           // Current PBLProjectV2 object
  action: 'start',
  microtaskId: 'micro-42',
});

// Continue after handover
await postPbl('/api/pbl/v2/task/update', {
  project,
  action: 'continue_handover',
});

// Run simulator preview
await postPbl('/api/pbl/v2/simulator', { project });

// Retrieve current task
const { task } = await fetch('/api/pbl/v2/open-task?projectId=123')
  .then(r => r.json());

// Send instructor dialogue
await postPbl('/api/pbl/v2/instructor', {
  project,
  event: { type: 'speak', content: 'Hello!' },
});

// Evaluate completed project
await postPbl('/api/pbl/v2/evaluate', { project });

Supporting libraries in lib/pbl/v2 (including agents/ and operations/ directories) provide the underlying logic consumed by these route handlers.

Summary

• OpenMAIC implements five primary PBL endpoints under the /api/pbl/v2 namespace
• All endpoints are stateless and require the client to persist the PBLProjectV2 object between calls
• The /api/pbl/v2/task/update route handles all workspace UI mutations through deterministic operations like startMicrotask and completeRoleplayAct
• Simulation, evaluation, and instructor actions are handled by dedicated POST endpoints that process project objects without LLM latency
• Source files are organized under app/api/pbl/v2/ with each route living in its own route.ts file

Frequently Asked Questions

What is the base path for all PBL endpoints in OpenMAIC?

All Project-Based Learning endpoints are mounted under /api/pbl/v2. This namespace contains the complete set of routes for task management, simulation, and evaluation.

Are the OpenMAIC PBL endpoints stateless?

Yes. The endpoints are completely stateless; they do not maintain session data or server-side project storage. The client must include the full PBLProjectV2 object in each request and handle persistence (typically in local storage or a database) between API calls.

Do these endpoints make direct LLM calls?

No. The PBL endpoints perform pure, deterministic operations only. Any LLM interactions are handled by separate agent systems; these API routes strictly mutate the project state object through functions like advanceMicrotask and continueAfterHandover without non-deterministic processing.

How do I retrieve the current micro-task for a project?

Use the GET /api/pbl/v2/open-task endpoint with a projectId query parameter. This route, defined in app/api/pbl/v2/open-task/route.ts, inspects the project's milestone structure and returns the active micro-task configuration for UI rendering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}