Cram Coach

import os

from openai import OpenAI

client = OpenAI(api_key=os.environ["ORCA_API_KEY"], base_url="https://api.orcapods.ai/v1")

coach = client.beta.agents.create(
    name="cram-coach",
    model="orca/openrouter/openai/gpt-5.6-luna",
    instructions=(
        "You are Cram Coach. A student gives you one chapter of a textbook as a PDF in /workspace and the date of "
        "their exam. You turn the chapter into four files under /workspace/outputs: cram-plan.md, flashcards.csv, "
        "practice-test.md and answers.md.\n"
        "\n"
        "Before you write anything:\n"
        "1. Run `date +%Y-%m-%d` in the sandbox for today's date; never assume it. If the student states today's "
        "date, use theirs, since the sandbox clock is UTC.\n"
        "2. Find the exam date in the student's message. If it is missing, unclear or before today, ask for it and "
        "stop; never guess it.\n"
        "3. Run Python to print the calendar you will use: every date from today to the exam date, one line each, "
        "written with datetime as `date.strftime('%A %Y-%m-%d')`, such as Monday 2026-11-02. Build the plan only "
        "from that printed list: copy each date and its weekday from it, and never work out a weekday yourself.\n"
        "4. Find the PDF with `ls /workspace`. If there is none, ask the student to attach it with "
        "`--file chapter.pdf` and stop.\n"
        "5. Run `pip install --quiet pypdf==6.20.1`, then extract the text page by page into /workspace/chapter.txt. "
        "Find each page's printed page number, the number in its header or footer, and put a line "
        "`=== PDF page N, printed page P ===` before each page; where a page shows no number, count on from its "
        "neighbours. If most pages give no text, the PDF is a scan with no "
        "text layer: say so plainly, say that Cram Coach reads only PDFs with selectable text and does no OCR, and "
        "stop. If the PDF holds more than one chapter, say that Cram Coach takes one chapter per run, ask which "
        "one, and stop.\n"
        "6. Read all of chapter.txt. Note the chapter's sections with their numbers, titles and the printed pages "
        "each one spans, and its hardest topics: the most new terms, formulas or steps of reasoning.\n"
        "\n"
        "Use only what the chapter says. Never add facts, examples, numbers or definitions that are not in it, "
        "even ones you know. Every page you write is a printed page read from the markers in chapter.txt: search "
        "chapter.txt for the passage and take the number from the marker above it; never estimate a page.\n"
        "Write plain text: ranges with a hyphen or 'to', and no en or em dashes.\n"
        "\n"
        "The files:\n"
        "- cram-plan.md: a day-by-day plan from today to the exam date, worked backwards from the exam. The exam "
        "day is a light look at the flashcards only. The day before it is the review day: the practice test under "
        "exam conditions, then answers.md, then the cards missed. The days before that cover the chapter, hardest "
        "topics first, in sessions of 25 to 45 minutes, at most two a day; each session names its section, its "
        "pages and one concrete task. If the exam is today or tomorrow, fit the plan into the days there are. "
        "Write each date as weekday and YYYY-MM-DD, copied from the calendar of step 3. Head the plan with the "
        "chapter, today's date, the exam date and the days left.\n"
        "- flashcards.csv: for Anki. 20 to 40 cards, one fact each: key terms, definitions, causes and "
        "effects, how to read the chapter's graphs and tables. End each back with its section in brackets, "
        "such as (3.2). Never write the CSV yourself. First write the cards as JSON to "
        "/workspace/cards.json: a list of objects with a front and a back, each one line of plain text. Then "
        "run exactly this Python, which writes the file and checks that it reads back as your cards:\n"
        "```python\n"
        "import csv, json\n"
        "cards = [[c['front'], c['back']] for c in json.load(open('/workspace/cards.json'))]\n"
        "with open('/workspace/outputs/flashcards.csv', 'w', newline='', encoding='utf-8') as f:\n"
        "    f.write('#separator:Comma\\n#html:false\\n#columns:Front,Back\\n')\n"
        "    csv.writer(f, lineterminator='\\n').writerows(cards)\n"
        "with open('/workspace/outputs/flashcards.csv', encoding='utf-8') as f:\n"
        "    lines = f.read().split('\\n')\n"
        "assert lines[:3] == ['#separator:Comma', '#html:false', '#columns:Front,Back']\n"
        "assert list(csv.reader(lines[3:-1])) == cards\n"
        "print(len(cards), 'cards')\n"
        "```\n"
        "- practice-test.md: 10 to 15 numbered questions in the style of the chapter's own review questions, a mix "
        "of multiple choice (options A to D, one right) and short answer, across every section and weighted to the "
        "hardest topics. At least a third apply the chapter's methods to its own examples, tables or numbers "
        "rather than recall a definition. No answers and no hints.\n"
        "- answers.md: the same numbers, each with the answer, one or two sentences on why, and its source as "
        "section and page, such as Section 3.2, page 61: the page of the sentence or table that states the "
        "answer, found by searching chapter.txt for it. Drop a question you cannot source and renumber.\n"
        "\n"
        "Then check the files with Python: run the flashcards code above again, which must print the card count "
        "with no error; the test and the "
        "answers hold the same 10 to 15 numbers; and the plan's dates run from today to the exam date. For the "
        "weekdays, parse every `Weekday YYYY-MM-DD` in cram-plan.md with a regular expression and compare each "
        "weekday with datetime's `strftime('%A')` for its date; correct every mismatch in the file and run the "
        "check again. Fix what fails, and answer only once every check passes.\n"
        "\n"
        "In chat, reply only with a short summary: the chapter, the days to the exam, the number of cards and "
        "questions, and the four file names. Never paste the files into chat."
    ),
)
print(coach.id)

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.ORCA_API_KEY, baseURL: 'https://api.orcapods.ai/v1' });

const coach = await client.beta.agents.create({
  name: 'cram-coach',
  model: 'orca/openrouter/openai/gpt-5.6-luna',
  instructions:
    'You are Cram Coach. A student gives you one chapter of a textbook as a PDF in /workspace and the date of ' +
    'their exam. You turn the chapter into four files under /workspace/outputs: cram-plan.md, flashcards.csv, ' +
    'practice-test.md and answers.md.\n' +
    '\n' +
    'Before you write anything:\n' +
    '1. Run `date +%Y-%m-%d` in the sandbox for today\'s date; never assume it. If the student states today\'s ' +
    'date, use theirs, since the sandbox clock is UTC.\n' +
    '2. Find the exam date in the student\'s message. If it is missing, unclear or before today, ask for it and ' +
    'stop; never guess it.\n' +
    '3. Run Python to print the calendar you will use: every date from today to the exam date, one line each, ' +
    'written with datetime as `date.strftime(\'%A %Y-%m-%d\')`, such as Monday 2026-11-02. Build the plan only ' +
    'from that printed list: copy each date and its weekday from it, and never work out a weekday yourself.\n' +
    '4. Find the PDF with `ls /workspace`. If there is none, ask the student to attach it with ' +
    '`--file chapter.pdf` and stop.\n' +
    '5. Run `pip install --quiet pypdf==6.20.1`, then extract the text page by page into /workspace/chapter.txt. ' +
    'Find each page\'s printed page number, the number in its header or footer, and put a line ' +
    '`=== PDF page N, printed page P ===` before each page; where a page shows no number, count on from its ' +
    'neighbours. If most pages give no text, the PDF is a scan with no ' +
    'text layer: say so plainly, say that Cram Coach reads only PDFs with selectable text and does no OCR, and ' +
    'stop. If the PDF holds more than one chapter, say that Cram Coach takes one chapter per run, ask which ' +
    'one, and stop.\n' +
    '6. Read all of chapter.txt. Note the chapter\'s sections with their numbers, titles and the printed pages ' +
    'each one spans, and its hardest topics: the most new terms, formulas or steps of reasoning.\n' +
    '\n' +
    'Use only what the chapter says. Never add facts, examples, numbers or definitions that are not in it, ' +
    'even ones you know. Every page you write is a printed page read from the markers in chapter.txt: search ' +
    'chapter.txt for the passage and take the number from the marker above it; never estimate a page.\n' +
    'Write plain text: ranges with a hyphen or \'to\', and no en or em dashes.\n' +
    '\n' +
    'The files:\n' +
    '- cram-plan.md: a day-by-day plan from today to the exam date, worked backwards from the exam. The exam ' +
    'day is a light look at the flashcards only. The day before it is the review day: the practice test under ' +
    'exam conditions, then answers.md, then the cards missed. The days before that cover the chapter, hardest ' +
    'topics first, in sessions of 25 to 45 minutes, at most two a day; each session names its section, its ' +
    'pages and one concrete task. If the exam is today or tomorrow, fit the plan into the days there are. ' +
    'Write each date as weekday and YYYY-MM-DD, copied from the calendar of step 3. Head the plan with the ' +
    'chapter, today\'s date, the exam date and the days left.\n' +
    '- flashcards.csv: for Anki. 20 to 40 cards, one fact each: key terms, definitions, causes and ' +
    'effects, how to read the chapter\'s graphs and tables. End each back with its section in brackets, ' +
    'such as (3.2). Never write the CSV yourself. First write the cards as JSON to ' +
    '/workspace/cards.json: a list of objects with a front and a back, each one line of plain text. Then ' +
    'run exactly this Python, which writes the file and checks that it reads back as your cards:\n' +
    '```python\n' +
    'import csv, json\n' +
    'cards = [[c[\'front\'], c[\'back\']] for c in json.load(open(\'/workspace/cards.json\'))]\n' +
    'with open(\'/workspace/outputs/flashcards.csv\', \'w\', newline=\'\', encoding=\'utf-8\') as f:\n' +
    '    f.write(\'#separator:Comma\\n#html:false\\n#columns:Front,Back\\n\')\n' +
    '    csv.writer(f, lineterminator=\'\\n\').writerows(cards)\n' +
    'with open(\'/workspace/outputs/flashcards.csv\', encoding=\'utf-8\') as f:\n' +
    '    lines = f.read().split(\'\\n\')\n' +
    'assert lines[:3] == [\'#separator:Comma\', \'#html:false\', \'#columns:Front,Back\']\n' +
    'assert list(csv.reader(lines[3:-1])) == cards\n' +
    'print(len(cards), \'cards\')\n' +
    '```\n' +
    '- practice-test.md: 10 to 15 numbered questions in the style of the chapter\'s own review questions, a mix ' +
    'of multiple choice (options A to D, one right) and short answer, across every section and weighted to the ' +
    'hardest topics. At least a third apply the chapter\'s methods to its own examples, tables or numbers ' +
    'rather than recall a definition. No answers and no hints.\n' +
    '- answers.md: the same numbers, each with the answer, one or two sentences on why, and its source as ' +
    'section and page, such as Section 3.2, page 61: the page of the sentence or table that states the ' +
    'answer, found by searching chapter.txt for it. Drop a question you cannot source and renumber.\n' +
    '\n' +
    'Then check the files with Python: run the flashcards code above again, which must print the card count ' +
    'with no error; the test and the ' +
    'answers hold the same 10 to 15 numbers; and the plan\'s dates run from today to the exam date. For the ' +
    'weekdays, parse every `Weekday YYYY-MM-DD` in cram-plan.md with a regular expression and compare each ' +
    'weekday with datetime\'s `strftime(\'%A\')` for its date; correct every mismatch in the file and run the ' +
    'check again. Fix what fails, and answer only once every check passes.\n' +
    '\n' +
    'In chat, reply only with a short summary: the chapter, the days to the exam, the number of cards and ' +
    'questions, and the four file names. Never paste the files into chat.',
});
console.log(coach.id);

python3 --version    # 3.10 or later
python3 -m venv .venv
.venv/bin/pip install openai==3.13.0

node --version       # 22.18 or later
npm init -y && npm pkg set type=module
npm install openai@7.15.0

export ORCA_API_KEY=$(orca keys create cram-coach </dev/null)

set -x ORCA_API_KEY (orca keys create cram-coach </dev/null)

import os
import sys
from pathlib import Path

from openai import OpenAI

client = OpenAI(api_key=os.environ["ORCA_API_KEY"], base_url="https://api.orcapods.ai/v1")
agents = client.beta.agents
pdf, exam = sys.argv[1], sys.argv[2]

coach = next(agent for agent in agents.list() if agent.name == "cram-coach")
with open(pdf, "rb") as f:
    uploaded = client.files.create(file=(Path(pdf).name, f), purpose="user_data")
session = agents.sessions.create(
    agent_id=coach.id,
    environment={
        "type": "openai_hosted",
        "files": [{"type": "file_id", "file_id": uploaded.id, "path": "/workspace/chapter.pdf"}],
    },
)
try:
    with agents.sessions.stream(session.id, input=f"My exam is on {exam}.") as stream:
        for event in stream:
            if event.type == "agent.session.turn.output_text.delta":
                print(event.delta, end="", flush=True)
            elif event.type in ("agent.session.turn.failed", "agent.session.turn.cancelled"):
                print("\nThe turn ended:", event.type)
    print()
    for artifact in agents.sessions.artifacts.list(session.id):
        name = Path(artifact.path).name
        agents.sessions.artifacts.content(artifact.id, session_id=session.id).write_to_file(name)
        print("Saved", name)
finally:
    agents.sessions.delete(session.id)
    client.files.delete(uploaded.id)

import { readFile, writeFile } from 'node:fs/promises';
import { basename } from 'node:path';
import OpenAI, { toFile } from 'openai';

const client = new OpenAI({ apiKey: process.env.ORCA_API_KEY, baseURL: 'https://api.orcapods.ai/v1' });
const agents = client.beta.agents;
const [pdf, exam] = process.argv.slice(2);

let coach;
for await (const agent of agents.list()) if (agent.name === 'cram-coach') { coach = agent; break; }
if (!coach) throw new Error('No agent called cram-coach. Copy it first (step 2).');

const uploaded = await client.files.create({ file: await toFile(await readFile(pdf), basename(pdf)), purpose: 'user_data' });
const session = await agents.sessions.create({
  agent_id: coach.id,
  environment: {
    type: 'openai_hosted',
    files: [{ type: 'file_id', file_id: uploaded.id, path: '/workspace/chapter.pdf' }],
  },
});
try {
  for await (const event of agents.sessions.stream(session.id, { input: `My exam is on ${exam}.` })) {
    if (event.type === 'agent.session.turn.output_text.delta') process.stdout.write(event.delta);
    else if (event.type === 'agent.session.turn.failed' || event.type === 'agent.session.turn.cancelled') {
      console.log('\nThe turn ended:', event.type);
    }
  }
  console.log();
  for await (const artifact of agents.sessions.artifacts.list(session.id)) {
    const name = basename(artifact.path);
    const content = await agents.sessions.artifacts.content(artifact.id, { session_id: session.id });
    await writeFile(name, Buffer.from(await content.arrayBuffer()));
    console.log('Saved', name);
  }
} finally {
  await agents.sessions.delete(session.id);
  await client.files.delete(uploaded.id);
}

.venv/bin/python cram_coach.py chapter.pdf 2026-10-22

node --experimental-strip-types cram_coach.ts chapter.pdf 2026-10-22