Personalized Cohort Learning

Build a cohort-based learning system using Resources API, Library API, and Outline API. There are two user roles: Instructor (designs a course / library) and Learner (requests a personalized learning path from that library).

End to end diagram flow

Instructor
   |
   |--(1) Uses Resources API → searches web +/or uploads own resources → receives streamed “resources + key topics”
   |        ↓
   |--(2) Creates a Library / Adds resources to it / Manages resources
   |        ↓
Learner (or Instructor preview)
   |
   |--(3) Learner supplies input (what they want to learn, how, in how much time, what format, etc.) + optional key topics
   |        ↓
   |--(4) Uses Outline API to generate a personalized outline (streamed SSE)
   |        ↓
   |--(5) Learner follows modules / lessons drawn from selected resources in the library

API	Purpose	Key Parameters	Response Type
Resources (GET /get_resource)	Search the web for resources based on input + optionally add custom resource links. Streams SSE events: start, web_search (with create_resource & key_topic actions), resource_done, complete. (docs.compasai.com)	input_str (string, required), content (list of custom resource URLs, optional), strict (boolean, optional) (docs.compasai.com)	SSE stream of incremental resource + topic info (docs.compasai.com)
Library	Create/fetch/delete a library; add/delete resources; update resources in library. Holds resource objects (with topics etc.). (docs.compasai.com)	For creating: name (required), tag (optional), description (opt) (docs.compasai.com); For adding resources: resource data including resource metadata + topics etc. (docs.compasai.com)	JSON confirming success / returning library with resources etc. (docs.compasai.com)
Outline (POST /get_outline or SSE /create_outline)	Generate a personalized outline for a learner based on library + learner’s input + optional key topics. Streams SSE: start, outline (with actions like create_section, create_module, create_lesson), complete. (docs.compasai.com)	input_str (string, required), library_id (int, required), key_topics (optional list), strict (boolean, optional) (docs.compasai.com)	SSE stream of outline sections/modules/lessons (docs.compasai.com)

Step-by-Step Implementation (TypeScript + Browser Fallback + UI/UX)

Here is a concrete tutorial for building the feature in a web app.

---

1. Instructor: Search / Add Resources via Resources API

UI Sketch / UX Suggestions

• A form where the instructor enters:

  What they want to teach (topic / proficiency / material types / hours)

• Optionally: a field to paste custom resource links / upload content.

• A “Search + Process” button.

• Show a loading / streaming state: as results come in, display resources and extracted key topics incrementally so instructor can preview and accept or remove.

TypeScript + Node / Frontend using EventSource

const API_KEY = "YOUR_API_KEY_HERE";

interface KeyTopic {
  idx: number;
  resource_id: number;
  topic: string;
  overview: string;
  score: { practical: number; explanatory: number; introductory: number };
  classification: string; // e.g. "core"
  prerequisites: string[];
  duration: string;
  topic_id: string;
  resource_type: string;
  resource_title: string;
  resource_url: string;
  content?: any;
}

interface Resource {
  title: string;
  type: string;
  description: string | null;
  uuid: number;
  url: string;
  preview: string;
}

interface SSEData {
  type: string;
  content: any;
}

function getResources(inputStr: string, customContent?: string[], strict?: boolean) {
  const params = new URLSearchParams();
  params.append("input_str", inputStr);
  if (customContent && customContent.length > 0) {
    params.append("content", JSON.stringify(customContent));
  }
  if (typeof strict === "boolean") {
    params.append("strict", strict.toString());
  }
  const url = `https://ai.compasai.com/api/agt/get_resource?${params.toString()}`;

  const es = new EventSource(url, {
    withCredentials: false,
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  } as any); // note: browsers may not support custom headers with EventSource; use fallback if needed.

  es.onmessage = (event) => {
    try {
      const data: SSEData = JSON.parse(event.data);
      switch (data.type) {
        case "start":
          console.log("Stream started:", data.content);
          break;
        case "web_search":
          // Could have action: create_resource or key_topic
          if (data.content.action === "create_resource") {
            const res: Resource = data.content.content;
            // Render new resource as card in UI
            console.log("New resource:", res);
          } else if (data.content.action === "key_topic") {
            const topic: KeyTopic = data.content.content;
            // Display topic under the resource
            console.log("Key topic:", topic);
          }
          break;
        case "resource_done":
          console.log("Done with this resource:", data.content);
          break;
        case "complete":
          console.log("All resources + topics fetched");
          es.close();
          break;
        default:
          console.warn("Unknown event type:", data.type);
      }
    } catch (err) {
      console.error("Failed parsing SSE data", err, event.data);
    }
  };

  es.onerror = (err) => {
    console.error("SSE error", err);
    es.close();
  };

  return es;
}

Browser Fallback / Proxy Because the standard EventSource in browsers does not allow setting custom authorization headers, you’ll need a fallback:

• Either proxy the SSE request via your backend, which adds the Authorization header.

• Or use fetch + stream if SSE not possible, although that’s less standard.

Example using backend proxy (Node.js / Express):

// Express route: /api/proxy/get_resource
app.get("/api/proxy/get_resource", (req, res) => {
  const query = req.query; // input_str, content, strict
  const token = process.env.COMPASAIA_API_KEY;

  const targetUrl = `https://ai.compasai.com/api/agt/get_resource?${new URLSearchParams(query).toString()}`;

  const fetch = require("node-fetch");
  fetch(targetUrl, {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "text/event-stream"
    }
  }).then((response) => {
    res.set({
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive"
    });
    response.body.pipe(res);
  }).catch((err) => {
    console.error("Error proxying SSE:", err);
    res.status(500).send("Proxy error");
  });
});

Your frontend then connects to /api/proxy/get_resource?... without needing custom headers.

---

2. Instructor: Create / Manage Library

Once the instructor is satisfied with resources & topics, they create a Library, and add the processed resources into it.

UI Sketch / UX Suggestions

• After resources have been collected & previewed, show a button: “Save as Library / Create Library”.

• Form to name the library, optionally tag it, give description.

• Afterwards, show listing of resources in library; allow editing: update resource metadata, remove resources.

Example TypeScript (fetch) Usage

interface Library {
  id: number;
  name: string;
  tag?: string;
  description?: string;
  resources?: ResourceObject[];
}

interface ResourceObject {
  title: string;
  type: "article" | "video" | "slides"; // supported resource types
  description?: string | null;
  uuid: string | number;
  url: string;
  preview?: string;
  topics: Topic[];
}

interface Topic {
  id: string;
  idx: string;
  score: {
    practical: number;
    explanatory: number;
    introductory: number;
  };
  topic: string;
  duration?: string;
  overview?: string;
  selected: boolean;
  prerequisites?: string[];
  classification?: "core" | "supplementary" | "advanced";
  content: VideoContent | ArticleContent | SlidesContent;
}

interface VideoContent {
  url: string;
  start_time?: string;
  end_time?: string;
}

interface ArticleContent {
  type: "article";
  title: string;
  description: string;
  duration?: string; // in format HH:MM:SS or minutes
  sources?: string[];
  pages?: ArticlePage[];
}

interface ArticlePage {
  title: string;
  objectives?: string[];
  description: string;
  duration?: string;
  order: number;
  content: string; // markdown or html
}

interface SlidesContent {
  type: "slides";
  duration?: string;
  title: string;
  slides: Slide[];
}

type Slide =
  | TitleSlide
  | OverviewSlide
  | ListSlide
  | ListWithImageSlide
  | MultiListSlide
  | ComparisonSlide
  | ConclusionSlide;

interface TitleSlide {
  type: "title";
  image?: SlideImage;
  title: string;
  subtitle?: string;
}

interface OverviewSlide {
  type: "overview";
  image?: SlideImage;
  header: string;
  paragraph: string;
}

interface ListSlide {
  type: "list";
  header: string;
  list: { topic: string; description: string }[];
}

interface ListWithImageSlide {
  type: "list_with_img";
  header: string;
  list: { topic: string; description: string; image?: SlideImage }[];
}

interface MultiListSlide {
  type: "multilist";
  header: string;
  subheader?: string;
  list: { topic: string }[];
}

interface ComparisonSlide {
  type: "comparison";
  header: string;
  description?: string;
  comparison: { header: string; description: string }[];
}

interface ConclusionSlide {
  type: "conclusion";
  image?: SlideImage;
  header: string;
  subheader?: string;
}

interface SlideImage {
  url: string;
  description?: string;
}

async function createLibrary(name: string, tag?: string, description?: string): Promise<Library> {
  const resp = await fetch("https://api.compasai.com/api/enterprise/library", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ name, tag, description })
  });
  if (!resp.ok) throw new Error("Failed creating library: " + (await resp.text()));
  const data = await resp.json();
  return data as Library;
}

async function addResourcesToLibrary(libraryId: number, resources: ResourceObject[]): Promise<void> {
  const resp = await fetch("https://api.compasai.com/api/enterprise/resources", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      library_id: libraryId,
      resources
    })
  });
  if (!resp.ok) throw new Error("Failed adding resources: " + (await resp.text()));
  // response confirms success
}

API Details from Docs

• Create a Library: POST /library with JSON body: name (string, required), tag (string, optional). Responds with { id: number, name, tag }. docs.compasai.com

• Fetch a Library: GET /library/<id> returns library including resources array. docs.compasai.com

• Delete Library: DELETE /library/<id> docs.compasai.com

• Add Resources: POST /resources (with library_id + list of ResourceObject) docs.compasai.com

• Update Resource in Library: PATCH /resources/<id> with updated resource object docs.compasai.com

• Delete Resource from Library: DELETE /resources/<id> docs.compasai.com

---

3. Learner: Generate a Personalized Outline via Outline API

Once the library is ready, the learner (or instructor previewing for a learner) can input their learning preferences and generate a custom outline.

UI Sketch / UX Suggestions

• Learner form with fields:

  Field	Description
  What you want to learn (topic + proficiency etc.)	e.g. “Cloud computing basics, beginner, slides + videos, ~10 hours”
  Prefered material types (videos, articles, slides etc.)	checkboxes / tags
  Key topics you want included (optional, from library’s key topics)	multi-select from previewed key topics
  Strictness: whether to only include those key topics or allow flexibility	toggle

• On submit, show streaming outline being built: show sections appearing, modules, lessons, durations, preview content. Allow learner to cancel / tweak parameters.

TypeScript + SSE Example

interface OutlineSection {
  action: "create_section" | "create_module" | "create_lesson";
  section: number;
  module?: number;
  section_title: string;
  module_title?: string;
  content?: any; 
  topic?: string;
  topic_id?: string;
  resource_id?: number;
  resource_type?: string;
  duration?: string;
}

interface OutlineEvent {
  type: string; // "start", "outline", "complete"
  content: OutlineSection | string;
}

function createOutline(inputStr: string, libraryId: number, keyTopics?: string[], strict?: boolean) {
  const params = new URLSearchParams();
  params.append("input_str", inputStr);
  params.append("library_id", libraryId.toString());
  if (keyTopics && keyTopics.length > 0) {
    params.append("key_topics", JSON.stringify(keyTopics));
  }
  if (typeof strict === "boolean") {
    params.append("strict", strict.toString());
  }

  const url = `https://ai.compasai.com/api/agt/create_outline?${params.toString()}`;

  const es = new EventSource(url, {
    withCredentials: false,
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  } as any);

  es.onmessage = (event) => {
    try {
      const data: OutlineEvent = JSON.parse(event.data);
      switch (data.type) {
        case "start":
          console.log("Outline generation started");
          break;
        case "outline":
          const sectionOrModule: any = data.content;
          // Render dynamically:
          // if action=create_section, show new section
          // if action=create_module, show module under section
          // if action=create_lesson, show lesson item
          console.log("Outline action:", sectionOrModule);
          break;
        case "complete":
          console.log("Outline generation completed");
          es.close();
          break;
        default:
          console.warn("Unknown event type:", data.type);
      }
    } catch (err) {
      console.error("Error parsing outline event", err, event.data);
    }
  };

  es.onerror = (err) => {
    console.error("SSE error in outline", err);
    es.close();
  };

  return es;
}

---

Reference Examples

Here are sample payloads / event streams from the docs:

• Resources SSE sample (excerpt): upon calling /get_resource

{
  "type": "web_search",
  "content": {
    "action": "create_resource",
    "content": {
      "title": "Video Production with Smartphone",
      "type": "article",
      "description": null,
      "uuid": 1,
      "url": "https://www.new-humanity.org/.../Video_Production_Smartphone.pdf",
      "preview": ""
    }
  }
}
// later:
{
  "type": "web_search",
  "content": {
    "action": "key_topic",
    "content": {
      "idx": 2,
      "resource_id": 1,
      "topic": "AWS VPC Security Configuration",
      "overview": "...",
      "score": { "practical": 0.35, "introductory": 0.29, "explanatory": 0.36 },
      "classification": "core",
      "prerequisites": ["subnets", "security groups", "network ACLs", "internet gateway", "NAT gateway"],
      "duration": "4:59",
      "topic_id": "c979",
      "resource_type": "video",
      "resource_title": "AWS Cloud Engineer Full Course for Beginners",
      "resource_url": "https://www.youtube.com/watch?v=j_StCjwpfmk",
      "content": {
        "url": "https://www.youtube.com/watch?v=j_StCjwpfmk",
        "start_time": "03:36",
        "end_time": "08:34"
      }
    }
  }
}
// and when resource is done
{
  "type": "resource_done",
  "content": 2
}
// when everything is complete
{
  "type": "complete",
  "content": "web_search"
}

• Outline SSE sample (excerpt): upon calling /create_outline

{
  "type": "outline",
  "content": {
    "action": "create_section",
    "label": "Generating Fundamentals of Cloud Computing Section Content…",
    "section": 1,
    "section_title": "Fundamentals of Cloud Computing",
    "status": "loading",
    "active": true
  }
}
{
  "type": "outline",
  "content": {
    "action": "create_module",
    "label": "Generating Introduction to Cloud Computing Benefits and Risks Module Content…",
    "section": 1,
    "module": 1,
    "section_title": "Fundamentals of Cloud Computing",
    "module_title": "Introduction to Cloud Computing Benefits and Risks",
    "status": "loading"
  }
}
{
  "type": "outline",
  "content": {
    "action": "create_lesson",
    "content": {
      "topic": "Cloud Computing Benefits Risks And Recommendations For",
      "topic_id": "7a07",
      "resource_id": 3,
      "resource_type": "article",
      "duration": "15:00",
      "content": ["abc"]
    }
  }
}
{
  "type": "complete",
  "content": "outline"
}

---

Putting It All Together: Sample End-to-End Code

Below is a minimal end-to-end flow in TypeScript (simplified) to illustrate how an application could wire this up.

async function instructorFlow() {
  // 1. Get resources
  const sseRes = getResources("Cloud computing beginner. Videos & slides only. 10 hours", ["https://custom-link.com/res1"], false);
  // here you'd accumulate resources + topics in UI as they stream

  // After finishing (listen for 'complete'), collect the list of ResourceObjects you want
  const selectedResources: ResourceObject[] = await new Promise((resolve) => {
    const acc: ResourceObject[] = [];
    sseRes.onmessage = (evt) => {
      const data: any = JSON.parse(evt.data);
      if (data.type === "web_search" && data.content.action === "create_resource") {
        acc.push(data.content.content);
      }
      if (data.type === "complete") {
        resolve(acc);
      }
    };
  });

  // 2. Create library
  const library = await createLibrary("Cloud Basics Cohort", "cloud-basics", "Beginner level cloud computing");
  
  // 3. Add resources to library
  await addResourcesToLibrary(library.id, selectedResources);

  return library;
}

async function learnerFlow(libraryId: number) {
  // Learner input
  const inputStr = "I want to learn cloud computing fundamentals, beginner level, videos & slides, around 10 hours.";
  const keyTopics = ["Cloud networking basics", "Security models", "Service models"];
  const strict = false;

  const outlineSse = createOutline(inputStr, libraryId, keyTopics, strict);
  
  // UI: render outline sections/modules/lessons as they come
  outlineSse.onmessage = (evt) => {
    const data: any = JSON.parse(evt.data);
    if (data.type === "outline") {
      // Render as suggested above
      console.log("Outline piece:", data.content);
    }
    if (data.type === "complete") {
      console.log("Outline done");
      outlineSse.close();
    }
  };
}

---

UI / UX Best Practices & Considerations

• Incremental feedback: As SSE events stream in, show parts of the result (resource cards, topics, sections/modules) immediately. Avoid leaving learners or instructors staring at loading spinner with no visible output.

• Preview content: For each resource & key topic, allow instructor / learner to preview (e.g. snippet, first few lines, video link) so they understand what is included.

• Selective editing: Instructor should be able to prune resources, deselect key topics, adjust order, etc., before finalizing library or outline.

• Time & effort estimation: Show durations (for resources, lessons) to help learner estimate total time needed; allow learner to adjust “hours” parameter to scale outline.

• Strict vs flexible: When learner picks key topics + strict = true, enforce that those are included; else allow the system more flexibility to include supplementary topics.

• Fallback & error handling: If SSE fails, show retry / fallback; handle network issues; show error states clearly.

• Permissions / roles: Ensure the UI separates instructor workflows (resource/library creation) vs learner workflows (selecting library / generating outline).

FAQ / Edge Cases

Question	Notes / Solutions
What if a learner picks a key topic not present in the library's resources?	The API may still attempt to include it, but it's better UX to only allow picking from available key topics; or warn about missing coverage.
Can library be updated over time?	Yes: using PATCH /resources/<id>, DELETE /resources/<id>, POST /resources to add new ones. After updates, learners may regenerate outlines to reflect new content. docs.compasai.com
How do you handle content types (video vs article vs slides)?	In input_str the learner can specify preferences; topics / resources include resource_type so you can filter / highlight accordingly.

---

Summary

This tutorial has walked you through:

1. Using the Resources API to fetch and/or upload learning resources + key topics in a streamed way.

2. Organizing those into a Library via the Library API.

3. Generating a Personalized Outline for learners via Outline API, with control over preferences and key topics.

4. UI/UX suggestions to make the process smooth for both instructors and learners.