[{"data":1,"prerenderedAt":2759},["ShallowReactive",2],{"docs-index":3,"docs-page-harness\u002Fdiagnosis-checks":2738},[4,162,528,679,1017,1203,1313,2299,2683],{"id":5,"title":6,"lead":7,"pages":8},"start","Get started","What VIABLE is made of, and its words.",[9,27,59,127],{"path":10,"title":11,"description":12,"updated":13,"minutes":14,"sections":15},"start\u002Fhow-it-fits","What's what in VIABLE","The VIABLE Learning Platform, the VIABLE Developer Platform, the VIABLE Engine and the VIABLE Harness - what each is for, and which website is which.","2026-11-14",4,[16,19,23],{"id":17,"title":17,"text":18},"","VIABLE is a family of tools for AI that teaches the way a teacher wants, made by VIABLE Lab. It has four parts, and you need only the one that fits what you want to do. Each part stands on the one below it, one way only, so nothing is built twice. From the top: The VIABLE Developer Platform (everything, every setting) and the VIABLE Learning Platform (Ask, and simple forms) both stand on the hosted VIABLE API and learner pages, which stand on the VIABLE Engine (agents, courses, class lists, pages), which stands on the VIABLE Harness (what teaching needs around any AI). The VIABLE Engine and th",{"id":20,"title":21,"text":22},"the-names","The names","VIABLE on its own means the whole family, never one part. It comes from the lab's name: Versatile Innovations in Affect, Behavior, and Learning Engineering. VIABLE Lab is the people, at the University of Florida. It's where to ask for more credit, or anything else. VIABLE Learning Platform is where teachers and learners go. VIABLE Developer Platform is where researchers and builders work. These docs live here, and cover all four parts. The VIABLE API is how programs reach the VIABLE Developer Platform. It's part of it, not a fifth thing. VIABLE Engine is the open server, and its console is its",{"id":24,"title":25,"text":26},"which-website-is-which","Which website is which","viablelearning.org is for teaching and learning. viablelab.org is for the lab and for building. Address What it is For www.viablelearning.org The VIABLE Learning Platform: where a teacher sets up a class, and where learners type a course code Teachers and learners page.viablelearning.org What learners open from a teacher's link. Nothing to sign up for Learners developers.viablelab.org The VIABLE Developer Platform, and these docs Researchers, builders, developers api.viablelab.org The VIABLE API, and the VIABLE Harness's hosted MCP address Programs github.com\u002FVIABLE-Learning-Lab\u002Fviable The VIA",{"path":28,"title":29,"description":30,"updated":31,"minutes":32,"sections":33},"start\u002Fkey-ideas","Key ideas","Agents, activities, studies and evidence - the four ideas the VIABLE Developer Platform is built on, and who does what.","2026-11-05",2,[34,36,39,43,47,51,55],{"id":17,"title":17,"text":35},"VIABLE sits between AI models and learners. It turns what a teacher or researcher intends into what the AI does with each learner, and keeps the evidence, for K-12 classes, university courses, adult learning, and libraries, museums and websites. Not sure which part of VIABLE you need? What's what in VIABLE.",{"id":37,"title":38,"text":17},"four-ideas","Four ideas",{"id":40,"title":41,"text":42},"1-agent-how-the-ai-works","1. Agent: how the AI works","An agent is an AI made of steps: it can search a knowledge base, check its reply with a VETTING step, then answer. Each publish is a numbered version, and learners always meet the published one. Your first agent",{"id":44,"title":45,"text":46},"2-activity-what-learners-do","2. Activity: what learners do","A course is one link a class opens all term. Each activity in it puts the work, such as Writing or Questions, beside the AI, and How the AI helps says what it is for and how much the AI does. A library can put an agent on a chat page instead, with no sign-in. Your first class",{"id":48,"title":49,"text":50},"3-study-what-a-study-decides","3. Study: what a study decides","A study sits over courses or a chat page. It asks for consent, decides who gets which version, and pins each agent's version while it runs. Your first study",{"id":52,"title":53,"text":54},"4-evidence-what-is-recorded","4. Evidence: what is recorded","Every run keeps each step and VETTING round. Learners' messages and the replies are turns, kept beside their work. Researchers code them and download one documented export, by learner code. The research export",{"id":56,"title":57,"text":58},"who-does-what","Who does what","Who What they do Where they work Teacher, librarian, workshop lead Runs classes, follows progress Teach: Courses, Question sets, Learners Researcher Runs studies and their data Research: Studies, Coding, Export Builder, learning designer Makes and tests agents Build: Agents, Knowledge App developer Connects an app Build → Apps, and the API Owner Members, keys and costs Operate, Account Learners need no account: they open one link. These are jobs, not permissions. A member's project role decides what they can change, and a course can be shared with one teacher. See Members and roles. Your first",{"path":60,"title":61,"description":62,"updated":63,"minutes":14,"sections":64},"start\u002Fglossary","Glossary","Look up the words VIABLE uses on screen and in these docs, each in one line, with a link to where it is explained.","2026-11-10",[65,67,71,75,79,83,87,91,95,99,103,107,111,115,119,123],{"id":17,"title":17,"text":66},"The words VIABLE uses on screen and in these docs, one line each. Use it when a term is new to you.",{"id":68,"title":69,"text":70},"a","A","Activity: One thing to do in a course: a lesson, pre-test, post-test or survey. Agent: An AI workflow made of steps. Learners and apps meet its published version. Agent test: A case (what a learner says, what a good reply does) run against a version of an agent, its reply rated pass or fail by a judge model. Agent profile: An agent's name, avatar, greeting, suggested questions and notice, shown on its chat page and in activities. AI key: The API key that pays for a course's AI. API key: A credential with scopes, limits and model access that lets code call VIABLE. App: An outside app calling yo",{"id":72,"title":73,"text":74},"b","B","Block: A group of steps folded into one box on the canvas. It can say what the steps do and show some of their settings.",{"id":76,"title":77,"text":78},"c","C","Chat page: An agent published for open use on websites. Visitors need no account. Codebook: Codes with definitions and examples, for coding messages, turns or AI replies. Comparative study: A study that sets what learners get, comparing groups or units. Courses only. Condition: What one group gets in a comparative study, such as no AI or another agent. Consent: A learner's decision on a study's versioned form. It decides whose data counts. Course: What learners open: one link with its sections, units and activities. Course code: The code in a course's link (…\u002Fcourse\u002FRC8K85JH). Learners can als",{"id":80,"title":81,"text":82},"d","D","Durable skill: Collaboration, communication or critical thinking at one of four levels, from the Carnegie Skills Progressions, for an activity to aim at.",{"id":84,"title":85,"text":86},"f","F","Final codes: The codes the team decides where coders differ. For each: A step that runs the same steps once for every item of a list, then carries on with what each pass kept. Flag: A moment a teacher should see, such as a safety reply, under To look at in Progress.",{"id":88,"title":89,"text":90},"h","H","How the AI helps: An activity's goal, standard, how much the AI does and when it writes first.",{"id":92,"title":93,"text":94},"l","L","Learner: A person known to the project by a learner code, the same on every device. Learner code: A learner's ID in data and exports, like L-7F3KQ2. Names never leave VIABLE. Learning component: A smaller piece a standard breaks into. List: An LLM step's field that holds several items, each with fields of its own, such as pictures to draw.",{"id":96,"title":97,"text":98},"m","M","Member: A person in a project, with a role. Misconception: A common mistake that hinders a math skill, from Eedi's graph, that an activity's AI can listen for. Model coder: A model that codes a sample as one more coder, with a confidence and a reason per item.",{"id":100,"title":101,"text":102},"o","O","Observational study: A study that follows how courses or a chat page are used, with no conditions.",{"id":104,"title":105,"text":106},"p","P","Panel: What learners work in: Questions, Writing, Reading or Embedded page. Personal code: A learner's code on a printed card, like K7Q2-M9XC. A personal link skips typing it. Picture number: How a learner refers to a picture a conversation showed (\"picture 2\"); later turns change it by that number. Project: A team's space for agents, courses, studies, keys and logs, paid for by its owner. Provider key: Your own model provider's key, billed there instead of VIABLE credits.",{"id":108,"title":109,"text":110},"r","R","Research notice: A study's text people read before taking part. Not the agent's notice. Role: Owner, editor or viewer: what a member can change. Viewers see codes, not names. Run: One execution of an agent, step by step, listed in its Run history. Run step: Runs one step once from the last Try it run, to try a change to it. Nothing is saved.",{"id":112,"title":113,"text":114},"s","S","Section: A class period or group, with its own link and opening times. Section link: A course link for one section, like …?section=p2. Standard: A learning standard an activity aims at, kept as it was when chosen. Step settings: The panel where a step is set up: Setup, Options, When something goes wrong and what later steps can use. Study: A protocol over courses or a chat page: consent, design and data.",{"id":116,"title":117,"text":118},"t","T","Trace: A run's record of what each step received and returned, and each VETTING round. Turn: A learner's message and the reply, kept in the export.",{"id":120,"title":121,"text":122},"u","U","Unit: A week or topic grouping a course's activities, with optional dates.",{"id":124,"title":125,"text":126},"v","V","Values: A step that works out named values from earlier steps, each able to use the ones above it. VETTING: A step where a reviewer model checks each reply against your rules and sends failed ones back to be rewritten. Visitor: An anonymous chat page user: one browser on one device, shown in data by a visitor code (V-…). Key ideas: what VIABLE is made of, and who does what. Your first class: make a course and share its link.",{"path":128,"title":129,"description":130,"updated":63,"minutes":14,"sections":131},"start\u002Fopen-kit","VIABLE Open Kit","VIABLE's public code, MIT licensed. The VIABLE Harness makes any AI agent teach the way a teacher wants. The VIABLE Engine runs classes on your own server.",[132,134,138,142,146,150,154,158],{"id":17,"title":17,"text":133},"One repository holds two things you can take apart: the VIABLE Harness and the VIABLE Engine. The code that runs every agent here is the same code, not a second product.",{"id":135,"title":136,"text":137},"see-it-work","See it work","In this order, each a few minutes: How it works. One activity a teacher set up, one message from a learner, and what the model is told before it replies. Library. What it draws on and from whom: guidance from research, and the public resources it reaches, each with how it is connected and its license. What has been measured. Each test of the Harness, what it found and where it falls short. A tutor whose steps code decides did the step a teacher's policy requires on 83 to 89 turns in 100, and a carefully written prompt with a guardrail on 57 to 73. Examples. Courses that work, to look at and co",{"id":139,"title":140,"text":141},"take-what-you-need","Take what you need","You have You want Take An AI agent or an education product It to know how to teach, whatever it's built on The VIABLE Harness A school, a library or a lab, and your own server Agents, courses and class lists you run yourself, on any model The VIABLE Engine A course or agent here The same thing on your own server The VIABLE Engine, from a package A study, a workflow to draw, nothing to host Consent, a research export, a visual editor The VIABLE Developer Platform, here You take only what you need. The Harness installs without the Engine.",{"id":143,"title":144,"text":145},"the-viable-harness","The VIABLE Harness","Without extra context, a model often gives the answer, explains at length and answers every learner the same way. The Harness works out what this moment needs from what the teacher set and open resources such as standards and misconceptions, and gives it to the model before it replies. Afterward it can check the reply and record what happened. Your AI assistant, with nothing to install. npx skills add VIABLE-Learning-Lab\u002Fviable --skill teaching-with-viable teaches it the moves. VIABLE's hosted MCP server gives it the tools. Any app, by changing one URL. The gateway sits in front of any OpenAI-",{"id":147,"title":148,"text":149},"the-viable-engine","The VIABLE Engine","Your own server, set up in the browser: npx @viable-lab\u002Fengine start, and its console opens. Add a model. Any OpenAI-compatible provider, on your own machine or elsewhere. Say what each model is for, and voice, reading aloud, attachments and search by meaning turn on as you do. Make a course, or add one. Activities, how the AI helps in each, and when each is open. Say who is in it. Anyone with the link, or a class list with personal codes and sections. Share it, and follow it. A link or QR code, then Progress. It also makes chat pages for a website, and agents from a form. Its README has the r",{"id":151,"title":152,"text":153},"move-a-course-or-agent-to-your-own-server","Move a course or agent to your own server","Download it. On a course, press Download as package → With its files (.zip). For an agent with a chat page and no course, open Agents, then ⋯ → Export… → With its knowledge (.zip). Add it. In the Engine's console: Courses → From a file. Choose the models. On Models. An agent's steps use the models you set there. Tell learners. It is a new link. Learners and their work stay here, so paste your class list there and share the new link. It goes the other way too: download it from the course's Settings in the console, then import it here from Courses. Models not available here become its default, a",{"id":155,"title":156,"text":157},"what-stays-on-the-viable-developer-platform","What stays on the VIABLE Developer Platform","Here On the VIABLE Engine The visual workflow editor, Try it and the Assistant A form for simple agents. Workflows from here run as they are Knowledge bases from any file and from websites, kept up to date Text, Markdown, CSV, JSON and HTML files, and snapshots of websites you refresh Consent, studies, coding and the research export Who has done what, how replies went, suggested changes, and your own records Logs, usage, keys and billing Your model provider's bill",{"id":159,"title":160,"text":161},"credit","Credit","Both carry open data from Learning Commons under CC BY 4.0, with the attribution to keep. If you use them in research, cite them as the repository says. Examples and packages: download any course as a package. Your first run: the request your app sends. VETTING: the reply check the Harness also runs.",{"id":163,"title":164,"lead":165,"pages":166},"teach","Teach","Run a class, a workshop or a seminar with an AI beside the work.",[167,251,288,323,367,386,417,441,469,496],{"path":168,"title":169,"description":170,"updated":13,"minutes":171,"sections":172},"teach\u002Flearning-platform","Teach on the VIABLE Learning Platform","Sign in, say what you're teaching, and get a course with a link for your class, with no agents or keys to set up.",15,[173,175,179,183,187,191,195,199,203,207,211,215,219,223,227,231,235,239,243,247],{"id":17,"title":17,"text":174},"This page is for teachers who want a class running today. On the VIABLE Learning Platform you sign in and tell Ask, VIABLE's setup assistant, what you are teaching. There are no agents, keys or models to choose. The rest of this section describes the same courses on the VIABLE Developer Platform, which has more settings. The words on the pages are the same, and a course made in one shows in the other under the same account.",{"id":176,"title":177,"text":178},"set-up-a-class","Set up a class","Sign in. Open the VIABLE Learning Platform, and sign in. Say what you're teaching. The subject, who it's for, and what they find hard. Ask makes the course and its activities and shows you each step. For a longer request, such as a week of lessons, it shows its plan and ticks each part off, and the course's card then shows everything it made, unit by unit. If you'd rather fill in forms, Courses has them, and the two work on the same course. Try it as a learner. Try it opens the course as your learners will see it. What you do there stays out of Progress. Add your class, if you want names. Past",{"id":180,"title":181,"text":182},"what-an-activity-is","What an activity is","What learners do, in order: a page to read, questions, writing or a web page, up to six steps, each with the AI beside them or not. Ask writes out what they read, says what the AI does in each step and what it says first, so nobody faces an empty box, and arranges it in a way research supports, such as predict, observe, explain. The activity's page says which way it used, what's known about it and what isn't, and offers others. Everything Ask wrote can be changed there, and one Save saves whatever you changed. What learners read is edited as it will look, with buttons for bold, headings, lists",{"id":184,"title":185,"text":186},"plan-with-goals","Plan with goals","Plan a unit the way instructional designers do: what learners will be able to do first, then the activities that work toward it, then a check that shows it. Add goals on a course's Activities tab. Write them one a line, or paste a list from anywhere, such as LOGEN AI, a VIABLE tool for turning what you want to teach into goals. Each belongs to a unit or to the whole course. Add goals is under the course's goals at the top of its Activities tab, and in a unit's ⋯ menu for that unit. Each goal says where it's practised and where it's checked, by the activities' names. One no check covers yet say",{"id":188,"title":189,"text":190},"start-from-what-you-already-have","Start from what you already have","Press + in the box, or drop a file on the page. A file. PDF, Word, PowerPoint, Excel, text or a picture, up to 15 MB. Ask reads what it needs, and writes from it. A Google Doc, Slides or Sheet. Paste its link. It has to be shared as \"Anyone with the link can view\", and if it isn't, Ask says how. It keeps a copy from today, which doesn't change when the original does. Something you added before. From your materials lists them. Your file stays as you gave it. Materials lists them all: open the original, see the words the AI took from it, or delete it. Keep them in folders: each course has its ow",{"id":192,"title":193,"text":194},"change-what-you-ve-made","Change what you've made","Every course and activity has Ask about it on its page. Or choose it with the course button in Ask's box, beside where you type: it names what Ask is working on, and No course starts something new. Once Ask has made a course, the button names it, so your next message is about that course. Your latest courses are also under Courses in the sidebar, and each opens on the tab you're on. Ask can change an activity's steps, title, goal, how much the AI does, when it writes first, its questions and most of its settings. If learners can already reach it, Ask shows you what would change and a button, a",{"id":196,"title":197,"text":198},"give-it-a-link-or-have-it-look","Give it a link, or have it look","Put a link in your message and Ask reads it: a web page, or a PDF, Word, PowerPoint or Excel file at that address. Some sites don't let a program read them, and some pages need a browser to show their words. Ask says so, and you can paste the words or add the file. A page it reads doesn't become one of your materials. To keep a copy, add the file. Ask can also search the web when you ask it to find something, or when it needs a fact it isn't sure of. It shows what it looked for and the pages it found, with links, and says where what it uses came from. A search goes to OpenAI and its results co",{"id":200,"title":201,"text":202},"when-the-class-can-see-the-screen","When the class can see the screen","On a projector, or a computer the class shares, start the conversation with Don't remember this conversation, the crossed-out eye in the box. Ask doesn't use or keep what it remembers, and the conversation isn't in Earlier: it's deleted a day after you last use it. What it sets up in your courses stays, as always.",{"id":204,"title":205,"text":206},"say-it-instead-of-typing","Say it instead of typing","Press the microphone, speak, then Done. Your words appear in the box for you to check, and nothing is sent until you send it. The recording is turned into words and not kept. Your browser asks for the microphone the first time. Please don't say learners' names: what you say goes to a model to be written down.",{"id":208,"title":209,"text":210},"what-ask-remembers","What Ask remembers","Ask remembers what you tell it about how you work: how you like its replies, your setting (45-minute periods, shared iPads), what you're working toward. It says so when it keeps something, and you can tell it \"remember…\" or \"forget…\". With each message it uses what you keep always in mind and the few things that fit what you asked, and when you mention something from before, it can look in your earlier conversations here. What you say now always comes first: if it remembers grade 5 and you ask for adults, you get adults. It's told to keep nothing about a learner and refuses any name on your cl",{"id":212,"title":213,"text":214},"what-s-kept","What's kept","What Ask remembers is kept with your account until you delete it. What you say to Ask, what it reads and what it answers are kept in VIABLE Lab's logs, with your account's address. The people who run the platform can read them, to check Ask works and how it's used. Deleting a conversation takes it off Earlier, and doesn't remove them. What Ask kept from it stays in What Ask remembers until you delete it there. A recording isn't kept: the logs hold only its size and what it cost, and its words only if you send them.",{"id":216,"title":217,"text":218},"what-it-costs","What it costs","What Who pays What happens at the end Setting up with Ask VIABLE Lab, within a daily limit Ask says so and comes back the next day. Everything else keeps working Your learners' conversations with the AI Your AI credit Learners can still open their activities, write and answer questions. The AI beside them stops replying, and tells them to let you know Your name at the foot of the menu opens your account, with the credit left as a bar, and a dot on your name says when it runs low. A class of 30 sending 10 messages each uses roughly $0.10 to $0.20. AI credit has a button for asking VIABLE Lab fo",{"id":220,"title":221,"text":222},"how-your-learners-sign-in","How your learners sign in","Choose on a course's People page. Way What it means Good for Personal codes on cards You print a card for each learner, and only codes on your list open the course Children: nothing to spell, and their work follows the code on any computer They type their name or student ID The first time, on one device. Anywhere else they use the personal code they are shown then A class that knows its own names Nobody signs in Each browser is one learner One sitting. On another computer, they are someone new",{"id":224,"title":225,"text":226},"the-two-tutors","The two tutors","Each activity with AI uses one of two, and its page says which. Tutor. A second reader checks every reply before the learner sees it: against the answer key while a question is open, and against what you set the rest of the time. It checks for giving too much away, not whether a reply is a good one, so read a few yourself. Replies take about ten seconds. Quick tutor. No second reader, so replies come in a few seconds, and one may give an answer away. Use it where there is no answer to give away. An activity's page shows what its tutor does with a message, step by step, and links to it on the V",{"id":228,"title":229,"text":230},"how-much-the-ai-does","How much the AI does","One scale on each activity's page, from Only checks to Explains, where each level does what the one before does and one thing more: Only checks, Asks questions, Gives hints, Shows an example, Explains. A new activity starts on Shows an example: it asks first, then hints, and once they have really tried and are still stuck it works through an example with other numbers, then sends them back to their own. Whichever you choose, it is told to say so when a learner has it. As you choose, the words the AI reads light up on the right, so you see what the level changes. More on how the AI helps.",{"id":232,"title":233,"text":234},"what-the-ai-listens-for","What the AI listens for","Under More ways to shape the AI on an activity's How the AI helps: Misconceptions to listen for (math): the ones listed. If you choose none, the common ones for the activity's goal are chosen for you. Guidance from research: if you choose none, four pieces that suit how much the AI does are chosen for you. Standard or skill: only if you want the AI to work on one with learners. It is never chosen for you. Each message, the AI takes from these what fits the moment: research for a learner who is stuck is different from research for one who just answered. What is chosen for you is shown there; Ch",{"id":236,"title":237,"text":238},"when-the-ai-writes-first","When the AI writes first","Off unless you choose. It can check in after some quiet minutes, or after they've worked a while without asking; ask about an answer that was wrong, or why one that was right works; and look at their writing every few hundred words, or when they hand it in, by asking how it's going, pointing to a place to look again, or saying what to fix. Each time is one message from your credit, at most twice in a step and three minutes apart unless you choose otherwise, and learners see why it began. When the AI writes first.",{"id":240,"title":241,"text":242},"see-what-the-ai-did","See what the AI did","Try it opens the activity as a learner, with What the AI did beside it: what VIABLE read of each moment, each draft, what the reviewer said and what reached the learner. It is kept with each reply, so it reads the same after a reload, and the activity's page lists your tries under What the AI did in your tries, in any browser. A reply that isn't what you wanted has Not what you wanted? Tell Ask under it: Ask opens with the activity and what happened written in the box, and you finish the sentence.",{"id":244,"title":245,"text":246},"how-it-looks-to-learners","How it looks to learners","A course's Settings has six looks and a color for its pages. Try it to see them.",{"id":248,"title":249,"text":250},"when-you-d-want-the-viable-developer-platform","When you'd want the VIABLE Developer Platform","For agents of your own, knowledge bases, other models, a project with colleagues, and studies with consent and conditions. Sign in at developers.viablelab.org with the same account, and your courses are there, in your personal project. What each part of VIABLE is for.",{"path":252,"title":253,"description":254,"updated":255,"minutes":256,"sections":257},"teach\u002Ffirst-class","Your first class","Make a course, add one activity with an AI, share its link or QR code, and see your first learner in Progress.","2026-11-08",3,[258,260,264,268,272,276,280,284],{"id":17,"title":17,"text":259},"This page takes you from nothing to a working class in about ten minutes. Use it the first time you teach with VIABLE.",{"id":261,"title":262,"text":263},"before-you-start","Before you start","You need a project where you are an owner or editor, and a published agent in it: the AI your learners talk with. If you have none yet, start with Your first agent.",{"id":265,"title":266,"text":267},"make-the-course","Make the course","Start a course. Open Teach → Courses and press New course. Name it. Type a Name, such as \"Biology 101 · Period 2 and 3\". Choose what kind. Under What kind of course, pick A class over weeks, A one-off session or A course for research. Say who it is for. Choose Adults, Teenagers (13 to 17) or Children (under 13). Create it. Press Create course. It starts as a Draft, so its link doesn't open for learners yet. Who it is for decides how learners get in. Children always get personal codes on printed cards. In a class over weeks, adults and teenagers type their name. You can change all of this later",{"id":269,"title":270,"text":271},"add-an-activity-with-the-ai","Add an activity with the AI","Pick a kind. On the Activities tab, choose Writing task. Check the AI. Learners talk with is already set to your most recently changed published agent. Pick another if you like. Write the task. Under Content, type The task, for example \"Should school start later? Take a side and give two reasons.\" Add it. Leave Opens on Open and press Add activity. A preview appears beside the form: \"As a learner sees it · nothing here counts\". It shows the Writing panel with your agent beside it, on Desktop or Phone.",{"id":273,"title":274,"text":275},"choose-how-it-looks","Choose how it looks","In the course's Settings → Appearance, pick a look for its home and activities, and for the study's consent step if it has one. Clear is the default; Playground suits young learners. Under Color, keep the look's own or choose another; text on it turns dark or light so it stays readable. Press Preview to see it at full size, on a computer or a phone, in light and dark.",{"id":277,"title":278,"text":279},"open-and-share-it","Open and share it","Clear what's missing. Before it opens lists anything left. If it asks you to Choose the AI key that pays for its AI, pick one in Settings → The AI and press Save settings. Try it. Press Preview to go through the course as a new learner. Beside an activity with an AI, What the AI did shows what happened behind each reply. Previews stay out of Progress. The link works for anyone who has it for 4 hours, so keep it from learners. Open it. Press Open course. Share it. On the Link & QR tab, copy The course's link, or press Show to the class for a full-screen QR code that phones can scan. In an LMS, ",{"id":281,"title":282,"text":283},"see-your-first-learner","See your first learner","A learner opens the link, types their name and starts. On the Progress tab, they appear with a dot under the activity once they start, and a check once they're done. That's a working class.",{"id":285,"title":286,"text":287},"when-it-s-over","When it's over","In the course's Settings → Archive, press Archive course. Learners can't open it, and it moves to Archived at the foot of Courses. From there, Restore brings it back as it was, with its learners and their work, and Delete takes it out of your courses for good. What learners did stays in Teach → Learners and the research export. Activities and panels: lessons, tests, surveys, and the panels learners work in. How the AI helps: tell the AI the goal and how far it may go. Learners and sign-in: sections, your class list, code cards and shared computers.",{"path":289,"title":290,"description":291,"updated":63,"minutes":14,"sections":292},"teach\u002Factivities","Activities and panels","Choose an activity's kind, give learners panels to work in, show them in steps, and set what the AI sees.",[293,295,299,303,307,311,315,319],{"id":17,"title":17,"text":294},"An activity is one thing learners do in a course, with an AI beside it or none. Use this page when you add a lesson, a test or a survey.",{"id":296,"title":297,"text":298},"kinds-of-activity","Kinds of activity","On the course's Activities tab, press Add an activity and choose a kind: Lesson: panels, a chat, or both. Start from Chat with an AI, Practice questions, Writing task, Reading or Embedded page. Pre-test and Post-test: no AI, one try, no hints, results at the end or none. A pre-test stays open to learners who join after it closes. Survey: your form's Survey address. The form receives the learner's ID or learner code under The ID goes in (pid by default). In the activity's page, Kind can also make a lesson a Check: see below.",{"id":300,"title":301,"text":302},"goals-and-checks","Goals and checks","Plan a unit as instructional designers do: what learners will be able to do, then the activities that work toward it, then a check that shows it. Add goals is at the top of the course's Activities, and Add goals to this unit in a unit's ⋯ menu. Write them one a line, or paste a list: it keeps its order, without its numbers or bullets. Each goal is the whole course's or a unit's. Each goal says where it's practised and where it's checked, by the activities' names, or No check yet. Its ⋯ menu changes its words or its unit, or removes it; the activities that worked toward it keep everything else.",{"id":304,"title":305,"text":306},"archiving-an-activity","Archiving an activity","Archive, in an activity's ⋯ menu or at the top of its page, takes it off the course: learners can't open it, and it waits under Archived at the foot of the course's Activities. Restore brings it back as it was, after the others in its unit. Delete takes it out of the course for good, after asking. Either way, what learners did in it stays in Teach → Learners and the research export. A course's Settings tell hiding, closing, archiving and deleting apart.",{"id":308,"title":309,"text":310},"panels","Panels","Panels are what learners work in. An activity has up to six; with none, it is a chat. Questions: a Question set, with your choice of feedback, tries and hints. Writing: The task, an optional plan, a Rubric of up to 12 criteria, word limits and A Hand in button. Drafts save as learners write. Reading: a PDF from your knowledge bases, or Upload a PDF. Learners can highlight and add notes. Embedded page: The page's address, such as a simulation. It must allow https:\u002F\u002Fpage.viablelearning.org to frame it.",{"id":312,"title":313,"text":314},"showing-panels-in-steps","Showing panels in steps","With two or more panels, set How the panels are shown to In steps (up to four). Two ready patterns: Read, then answer and Read with the AI, then answer alone. For each step, choose what it Shows, whether The AI is There or Not in this step, and how it Opens: When they're ready or On its own after some minutes. A later step's questions don't reach learners' browsers early. A step without the AI is the sure way to keep it out of part of an activity, such as a final quiz.",{"id":316,"title":317,"text":318},"what-the-ai-sees","What the AI sees","Each panel has What [agent] is shown of this panel: Panel Choices Writing All, Task only, Nothing, Custom Questions The question, Nothing, Custom Reading The page in view, The selection, The whole document, Nothing, Custom Embedded page Its events, Nothing, Custom Learners are told shows what learners read about it. Preview what [agent] reads shows exactly what the AI gets. Answer keys are never in it.",{"id":320,"title":321,"text":322},"voice-and-photos","Voice and photos","Learners can speak if the agent's published version has a Transcribe step, and hear replies if it has a Speech step. Then turn on Learners may speak and choose Read replies aloud. Transcription is billed per audio minute. Learners may attach photos and Learners may attach PDFs allow up to 4 files a message, 8 MB each. If they aren't offered, the editor names the agent step to change. Every saved change makes a new version, which learners get the next time they open the activity. How the AI helps: tell the AI the goal and how far it may go. Question sets: write, import or draft the questions a ",{"path":324,"title":325,"description":326,"updated":63,"minutes":327,"sections":328},"teach\u002Fai-helps","How the AI helps","Tell the AI what an activity is for, how much it does, when it writes first and what its reviewer reads.",10,[329,331,335,339,341,345,347,351,355,359,363],{"id":17,"title":17,"text":330},"How the AI helps tells the agent what one activity is for and how much it does. It appears in the activity editor once you choose who Learners talk with. The agent reads it with every message. Learners don't see it.",{"id":332,"title":333,"text":334},"goal","Goal","Under Goal, write what learners should be able to do by the end, in your own words. For example: \"Explain each step of a two-step word problem in their own words.\" A goal alone is enough for any learners, from a university seminar to a library session. You don't need a standard.",{"id":336,"title":337,"text":338},"a-standard-a-skill-or-misconceptions","A standard, a skill or misconceptions","Standard or skill is optional: a K-12 standard, or a durable skill for any age. For math, Misconceptions to listen for suggests common misconceptions. See Standards, skills and misconceptions. An activity can also hold guidance from research: short pieces from a framework or a study, each with where it came from. They come with a course package or through the API, and How the AI helps lists them. The AI reads them where they fit.",{"id":228,"title":229,"text":340},"One scale, from the least the AI does for a learner to the most. Each level does what the one before it does, and one thing more: Level What it adds Use it for It sounds like Only checks Says what is right and which part to look at again. Nothing more. Their own writing, a quiz, showing what they know. “Your second step is right. Look again at your first.” Asks questions Also asks questions that help them find the way, one at a time. No hints. Discussion and reasoning, where the thinking has to stay theirs. “What makes you say that?” Gives hints Also gives hints, one step at a time. Never the ",{"id":342,"title":343,"text":344},"hold-each-step-by-counting-tries","Hold each step by counting tries","Under Shows an example there is one more switch. Off, the AI judges for itself when a learner has \"really tried\". On, the tries are counted for it and each turn's step is decided before it writes: The learner has The turn gets Not tried yet One question about how they got it or what they think Tried once, or says they are stuck One hint for the next step Tried twice or more A worked example of a similar problem, then their own again The right answer Told so, and asked why it works With a question open, a try is an answer the page has checked, and the page's own marking says when they have it. ",{"id":236,"title":237,"text":346},"By default the AI answers only when a learner writes to it. Under When [agent] writes first, unasked, it can begin at moments you choose. Each is off until you pick a time for it: Moment When What it does They've been quiet on a step After 2 to 10 minutes with nothing written, answered, clicked or scrolled, with the page in view Offers one small way in, or asks what they are thinking, and makes it easy to say they're fine They've worked a while without asking After 5 to 20 minutes busy on the step without writing to it Asks how it's going, or offers to look at something An answer is wrong The ",{"id":348,"title":349,"text":350},"what-a-reviewer-reads","What a reviewer reads","With a VETTING step (the Learning Platform's Tutor has one), a second reader checks each reply before the learner sees it. Under What a reviewer reads: Only the reply (the default). A learner can't argue with it. But it can't tell a learner's own idea from one handed to them, so now and then a good reply is held back and rewritten, and it can't tell a reply that doesn't answer them. The reply and the learner's message. It holds back fewer good replies, and it also holds back replies that don't answer what the learner said. Their message reaches it as data, never instructions, but a learner who",{"id":352,"title":353,"text":354},"only-what-each-moment-needs","Only what each moment needs","Turn on Give [agent] only what each moment needs and it stops getting everything you set with every message. It reads what the learner just did (gave an answer, asked for the answer, got stuck, or tried more than once), then gets your goal and how much it does, a teaching move for that moment, and only the parts of the standard and misconceptions that message calls for. It is read by simple rules, so it adds no cost and no wait. The rules read English best. In a test on 50 learner messages, replies kept the answer back more often with it than with the settings given whole (what was measured). ",{"id":356,"title":357,"text":358},"guidance-from-research","Guidance from research","Under Guidance from research, choose what you want the AI to have in mind: sentences on scaffolding, feedback, tutoring talk, self-explanation, worked examples, productive struggle, recall and spacing, and metacognition. Each names the studies it draws on, and once chosen, that name opens to the full references. Each topic says what the research shows and what isn't known. Most of it is about human tutors, so try the activity and see what it does. You can choose up to 20. With each message the AI gets at most two that fit what the learner just did, and they take turns as the conversation goes ",{"id":360,"title":361,"text":362},"different-for-a-section","Different for a section","Under Different for a section, give a section, such as an extra-support period, its own level and a note (up to 500 characters) the agent reads only in that section's chats. Each message's record keeps which section's settings it used (teaching_section in the research export). It isn't offered on a study's design or while a course's study runs, where every section follows the design, nor for one learner: a note about a person would go to a model.",{"id":364,"title":365,"text":366},"check-what-the-ai-is-given","Check what the AI is given","Open What [agent] is told with every message to see the exact text the agent gets. With a section of its own, choose it under As read by. This is an instruction, not a lock. To keep the AI out of part of an activity, show the panels in steps with a step that has no AI. See Activities and panels. With a VETTING step, its reviewer checks each reply against this too, and replies that can't pass show up under To look at. Progress also suggests changes here from what the activity's records show, such as less help when replies keep giving too much away. Edit first opens this section with the change ",{"path":368,"title":369,"description":370,"updated":255,"minutes":32,"sections":371},"teach\u002Fstandards-and-skills","Standards, skills and misconceptions","Align an activity to a K-12 standard or a durable skill, and give its AI common math misconceptions to listen for.",[372,374,378,382],{"id":17,"title":17,"text":373},"In an activity's How the AI helps, you can say what it aims at beyond your own goal: a K-12 standard or a durable skill, and for math, the misconceptions its AI should listen for. All of it is optional and comes from Learning Commons. Under Standard or skill, choose K-12 standard for US state standards and Common Core, or Durable skill for collaboration, communication and critical thinking at any age.",{"id":375,"title":376,"text":377},"a-k-12-standard","A K-12 standard","Standards cover math, English language arts, science and social studies. Say where. Choose your State (or Common Core (Multi-State)), a Subject and a Grade. Search. Type words, or a code such as 4.OA.A.3, and press Search. Pick one. It comes with what It breaks into and the Standards before it, for the AI to go back to. Untick what doesn't fit. Untick what this activity doesn't reach.",{"id":379,"title":380,"text":381},"a-durable-skill","A durable skill","Durable skills come from the Carnegie Skills Progressions. Each indicator, such as \"Check in and circle back with group progress\", grows through four levels: Exploring, Analyzing, Integrating and Extending. Choose the Level learners work toward, then search with words like evidence or feedback. The AI reads what a learner does At this level, and The level before to go back to. Either way, what you choose is kept in the activity as it was, with its CC BY 4.0 attribution: the line under it names where it came from, and opens to the attribution. Later changes at Learning Commons don't change what",{"id":383,"title":384,"text":385},"misconceptions-to-listen-for","Misconceptions to listen for","For math, Misconceptions to listen for suggests misconceptions from Eedi's graph, through Learning Commons: at once for a math standard, or, with only a goal, from Teaching math? Find misconceptions to listen for. Each suggestion is a math skill whose words match the standard or goal, with the misconceptions that hinder it; you can also search with your own words. Tick up to eight; nothing is ticked for you. The agent, and a VETTING reviewer, get them as a short list. Under the ones you chose, From Eedi Misconceptions Graph v1.0 opens to its attribution. In a Preview, What the AI did names it ",{"path":387,"title":388,"description":389,"updated":63,"minutes":256,"sections":390},"teach\u002Fsign-in","Learners and sign-in","Choose how learners sign in, set up sections and a class list, print code cards, and give a section its own times.",[391,393,397,401,405,409,413],{"id":17,"title":17,"text":392},"Set up who is in a course and how they get in, before your first class or a new term.",{"id":394,"title":395,"text":396},"how-learners-sign-in","How learners sign in","Choose in Settings → How learners sign in. It's the same in every activity, so a learner's work follows them across devices. Option Best for Personal codes on cards Young learners and shared devices They type their name Quick starts with no list They type an ID they already have Matching your records Their ID comes in the link Arrivals from a survey or online panel Each device One sitting: each browser is one learner A typed name opens someone's work only the first time, or on the browser they used. Anywhere else the page asks for their code, which their course home shows them and you can find",{"id":398,"title":399,"text":400},"sections","Sections","A section is a class period or group, with its own link. On People, type a name under Sections, press Add section, then Save sections. Section links appear on Link & QR. Then choose How learners get into their section: By their section's link, They pick it themselves, once, or From your class list only.",{"id":402,"title":403,"text":404},"your-class-list","Your class list","A class list is optional. It gives everyone a section and a personal code at once, and shows them in Progress before their first visit. Open the list. On People, press Add people. Paste your names. Type one person per row, or paste rows from a spreadsheet. Import a CSV file works too. Fill the gaps. Student ID or email and Section are optional; Section for rows that leave it empty fills them. Add them. Check the summary and press Add. Add up to 1,000 people at a time. Anyone already in the course keeps their work and code.",{"id":406,"title":407,"text":408},"code-cards","Code cards","Everyone on the list gets a personal code, like K7Q2-M9XC. Print cards on People prints each learner's name, section, code and a QR code for their section's link. Allow pop-ups if they don't open. For a lost card, press New code on the learner's page in Teach → Learners.",{"id":410,"title":411,"text":412},"shared-computers","Shared computers","For a laptop cart or a lab, turn on Shared computers in Settings → How learners sign in (on by default for children). Each visit, and any return after 20 minutes idle, asks \"Are you Sam?\". Learners also get Sign out. Don't use Each device on shared computers: everyone on that browser becomes one learner.",{"id":414,"title":415,"text":416},"opening-times-and-extra-time","Opening times and extra time","An activity's Opens is Open, At a time or When I open it; Closes is optional. Once it's saved, each section gets its own row, so Period 2 can start Monday and Period 3 Tuesday. In class, Open now asks Everyone or one section only. To keep one activity open longer for a learner, open their cell in Progress, set Open for them until under More time, and press Give more time. It only moves a close later; Take back more time ends it. For a learner who shouldn't be hurried anywhere in the course, choose Give extra time in their ⋯ menu in People. No step timer moves them on: a step set to open on its",{"path":418,"title":419,"description":420,"updated":421,"minutes":32,"sections":422},"teach\u002Fsharing","Sharing a course","Share one course by email with a teacher who runs it or an assistant who follows it, without giving them the rest of the project.","2026-10-29",[423,425,429,433,437],{"id":17,"title":17,"text":424},"Share one course with a co-teacher or an assistant, like sharing a document. They get that course, not the rest of your project.",{"id":426,"title":427,"text":428},"share-it","Share it","Open the course. In Teach → Courses, open it and press Share at the top. Add them. Type their email, choose Teacher or Assistant, and press Add. That's it. We email them the link. They have the course as soon as they sign in with that email, with or without an account today. There is nothing to accept. Under People with access, the dialog lists everyone in the project first, then each person you shared it with.",{"id":430,"title":431,"text":432},"who-can-do-what","Who can do what","Teacher and assistant are roles on this course; editor and viewer are roles in the whole project. Teacher Assistant Editor Viewer Progress, flags and learners' work, with names Yes Yes Yes Codes only Mark what to look at as seen Yes Yes Yes No Class list, sections, opening times, extra time Yes No Yes No The course's settings (not its AI key) Yes No Yes No Share the course Yes No Yes No Activities, the AI key, deleting the course No No Yes No A teacher or assistant from outside the project sees only the courses shared with them: the project switcher shows the project as Shared course, and Teac",{"id":434,"title":435,"text":436},"a-study-in-several-schools","A study in several schools","A study's courses can sit in one project, one per school. Share each school's course with its own teachers: each sees only their course and its learners. The activities stay the study's design, the same at every school. Project editors can change every course in the project. Make someone an editor only if they build activities or the study; share a course with a teacher who runs one class.",{"id":438,"title":439,"text":440},"stop-sharing","Stop sharing","In Share, choose another role from a person's role menu, or press × to remove them. They lose the course at once; what their learners did stays. A teacher can remove themselves, which the dialog calls leaving the course. Learners and sign-in: sections, code cards and extra time. Following progress: see who has done what, and what to look at. Members and roles: roles that cover the whole project.",{"path":442,"title":443,"description":444,"updated":63,"minutes":445,"sections":446},"teach\u002Fprogress","Following progress","See who has done what, act on what the AI flags and on suggested changes to how it helps, open a learner's work, and download progress with names.",5,[447,449,453,457,461,465],{"id":17,"title":17,"text":448},"Progress shows who has done what in a course, and what you may want to look at. Open it during class, or after, before you plan the next lesson.",{"id":450,"title":451,"text":452},"the-grid","The grid","Progress has a row for each learner and a column for each activity, with how many are done. Everyone on the class list has a row, joined or not. Each cell is done, started or not opened. Search names and codes, filter by section, and press Refresh to catch up.",{"id":454,"title":455,"text":456},"to-look-at","To look at","Above the grid, To look at lists moments from the last 30 days of your learners' work with the AI. Safety replies and calls for a person come first, then the newest. Safety reply: the agent's VETTING step stopped a reply for safety. Needs a person: the VETTING step asked for a person. No reply passed review: no reply passed VETTING in the attempts allowed, so the learner got the last one unapproved. The AI couldn't answer: the agent itself said it couldn't answer, or wanted a person. Rated not helpful: the learner rated a reply not helpful. The reply failed: the learner got an error instead of",{"id":458,"title":459,"text":460},"suggested-changes","Suggested changes","Below To look at, Suggested changes proposes changes to How the AI helps in one activity, from what its records show. Choose the activity at the top when the course has more than one with an AI. A suggestion appears when the current version's records show a pattern: Gives too much away: at least 30% of 5 or more replies its VETTING step reviewed failed their first review for giving too much away. It suggests one step less help, such as from Explains to Hints only. Replies not passing review: at least 20% of 5 or more reviewed replies never passed. It asks you to read them; nothing to accept. M",{"id":462,"title":463,"text":464},"a-learner-s-work","A learner's work","Open a cell to see one learner's work in that activity: Extra time, when you gave it in People: no step timer moves them on. It also shows beside their name in the grid when they started and finished, and how long they were active their plan, draft and hand-in each answer, Right or Not right, with tries; Listen plays a spoken answer when recordings are kept their highlights and notes their last 20 Messages with the agent, typed or spoken, and whether they rated each reply helpful. What the AI did under each opens that reply's run: what the Harness read, each draft and what the reviewer said. A",{"id":466,"title":467,"text":468},"the-download-with-names","The download with names","Download with names (CSV) lists each person's name, student ID, section and visits, and each activity done, started or not yet. Use it for your records or gradebook. The file has learners' names and IDs. Keep it somewhere safe. Viewers get Download (CSV) instead, by learner code only. The research export also uses learner codes, never names. How the AI helps: set the goal and how much the AI does, or adjust a suggested change. Learners and sign-in: sections, code cards and extra time. Export: download your course's data for research, by learner code.",{"path":470,"title":471,"description":472,"updated":421,"minutes":32,"sections":473},"teach\u002Fquestion-sets","Question sets","Write, import or draft questions with AI, then use one set as practice in one activity and a quiz in another.",[474,476,480,484,488,492],{"id":17,"title":17,"text":475},"A question set is a list of questions any activity's Questions panel can ask. Build one here, or reuse one across activities. Sets live in Teach → Question sets, listed by the course and unit that ask them. You can also press New set on an activity's Questions panel. Learners never see the answers.",{"id":477,"title":478,"text":479},"write-questions","Write questions","Start a set. Press New question set and give it a Title. Add a question. Press Add a question and choose its type. Add help. Give it up to five Hints, an Explanation, a Skill and Points. Check it. Preview shows the question with its key marked. The types are Multiple choice, Select all that apply, Fill in, Fill the blanks, Put in order, Short answer, Open answer, Program and Spoken answer. Open answers and programs aren't graded automatically. Short and open answers can Show the model answer after they answer. A set holds up to 200 questions.",{"id":481,"title":482,"text":483},"import-questions","Import questions","Press Import questions, then paste them or choose a PDF, Word, PowerPoint, Excel or CSV file. Spreadsheets with a header row, lettered choices (Moodle's Aiken format) and JSON are read without AI; Formats read without AI has templates. Anything else can be Read with AI, which keeps your questions and answers as they are. Untick what you don't want and press Add.",{"id":485,"title":486,"text":487},"draft-with-ai","Draft with AI","Draft with AI writes questions from your material: Pick the material. In What to draw on, choose Your documents (up to 10, whole or by sections or pages), A file, or Text, with an optional focus. Say what to write. In What to write, set how many (up to 30), a level and the types. Choose who writes. In Who writes them, pick a key, which is billed, and a model. Each question comes with a skill, hints and an explanation, drawn from your material only. Nothing joins the set until you press Add. Spoken answers and programs aren't drafted.",{"id":489,"title":490,"text":491},"feedback-and-tries","Feedback and tries","Feedback, tries and hints are set on each activity's Questions panel, so one set can be practice in one activity and a quiz in another: Right or wrong is shown: After each answer for practice, At the end for a quiz, Never for a test. Tries per question: 0 for any number, up to 10. Hints: learners open them one at a time, and each is recorded. Pre-tests and post-tests always get one try and no hints.",{"id":493,"title":494,"text":495},"changing-and-archiving","Changing and archiving","Asked in lists every activity that uses the set. A saved change shows in all of them and makes a new version; answers already given keep theirs. To change one activity only, use Make a copy on the Question sets page. Archive removes a set from the list and from new panels. Activities already using it keep working. Activities and panels: put a set in a Questions panel, alone or in steps. Following progress: see each answer, and who is stuck on a question.",{"path":497,"title":498,"description":499,"updated":500,"minutes":14,"sections":501},"teach\u002Fexamples-and-packages","Examples and packages","Start from a working example, download any course with or without its files, and move it to another project. Learners and keys never travel with it.","2026-11-09",[502,504,508,512,516,520,524],{"id":17,"title":17,"text":503},"An example is a whole course to start from: its activities, the AI beside the work and how far it may go, the questions and rubrics it uses, and the files it reads. A package is the file any course travels as, and each example is one.",{"id":505,"title":506,"text":507},"start-from-an-example","Start from an example","Docs → Examples has six, each arranged differently: fractions practice with a checked tutor, a PDF reading with a Socratic tutor, an argument essay, English speaking practice by voice, a density lab on an embedded page, and a library research desk that answers from its guides. Choose one. Press Use in my project on an example, or press From an example or a file on Teach → Courses and Use one. Choose the AI key. Pick the key that pays for the course's AI. You can change it later in the course's Settings. Create it. Press Create course. It is added as a draft to the project you have open, with i",{"id":509,"title":510,"text":511},"download-a-course-as-a-package","Download a course as a package","On a course, press Download as package, then choose: The course (.json): one file with the course's settings, units and activities, the agents they use (each one's published version) and the question sets their Questions panels ask. Reading panels and knowledge bases stay behind. With its files (.zip): the same, plus each Reading panel's PDF and the knowledge bases its agents search: their uploaded files, and the addresses of their websites, which are read again where it's imported. Up to 25 MB. The project's owners and editors can download it, since it carries the agents' workflows. A course ",{"id":513,"title":514,"text":515},"download-an-agent-on-its-own","Download an agent on its own","An agent with a chat page and no course can leave too: on Agents, open its ⋯ menu, choose Export…, then With its knowledge (.zip). It's a package with no course. Importing it makes the agents and knowledge bases, and no course. See Chat pages.",{"id":517,"title":518,"text":519},"duplicate-a-course","Duplicate a course","On a course, press Duplicate and choose Into the project: this one, or another where you're an owner or editor. You get a new draft with the course's settings, look, units and activities, and none of its learners: no class list, sections or anyone's work, and activities with dates start hidden. In the same project, the copy is called \"… (copy)\" and uses the same agents, question sets and readings, with the course's AI key. In another project, that project gets its own copies of the agents, question sets and knowledge bases, and you choose one of its keys. The knowledge bases come with their pa",{"id":521,"title":522,"text":523},"bring-a-file-into-a-project","Bring a file into a project","In the project, open Teach → Courses, press From an example or a file, then Choose file under Upload a package and pick the .viable.json or .viable.zip. If you own or edit more than one project, choose Into the project. The course arrives as a new draft, with new knowledge bases for its files. An agent whose name the project already uses gets \"(imported)\" after it. If something can't be made, nothing half-made is left open.",{"id":525,"title":526,"text":527},"what-a-package-never-carries","What a package never carries","Learners, the class list, sections, or anyone's work. The course's key, or the first project's IDs. In a .json without files: knowledge bases. A Reading panel comes without its PDF and is left out, so add it again, and an agent comes without the knowledge bases it searches. Download it with its files to keep them. The headers of an agent's Fetch URL steps, and email addresses in the course information. Opening dates. Each activity is open, or hidden until you open it. A .viable.json can be up to 2 MB and a .viable.zip up to 25 MB, with up to 20 agents, 50 question sets and 100 activities. A pa",{"id":529,"title":530,"lead":531,"pages":532},"research","Research","Study learning with AI, from consent to a documented dataset.",[533,552,571,594,629,652],{"path":534,"title":535,"description":536,"updated":63,"minutes":256,"sections":537},"research\u002Ffirst-study","Your first study","Start a study from your situation and work through its checks until it is ready to open.",[538,540,544,548],{"id":17,"title":17,"text":539},"Start here the first time you run research on VIABLE. You go from your situation to a study whose checks are all done, ready to open.",{"id":541,"title":542,"text":543},"start-from-your-situation","Start from your situation","Open Research → Overview. Under What are you studying? (or Start another study), pick a card. Card What it sets up Button A study in your own course A study on a course you have: follow use, compare units or compare groups Start with your course A study in schools Comparing groups on a new course for children, with personal codes and parental permission for minors Start a study in schools An online study Comparing groups on a new course for adults, who sign in by the ID in their link (PROLIFIC_PID, the ID the Prolific panel puts in the link) Start an online study Open learning on a chat page A",{"id":545,"title":546,"text":547},"create-the-study","Create the study","Say what you want to find out. In New study, the card chooses step 1, except for your own course. When comparing units, also choose The same for everyone or Two orders, half the learners each. Name it. Give the study a name your team will recognize. Choose where learners take part. Pick A course you have, A new course (with Who it is for: Adults, Teenagers or Children) or, for an observational study, A chat page. It starts with lists the defaults. Create it. Select Create study. If you haven't chosen where, the button reads Create, and add where later. Work down the checks. On the study's page",{"id":549,"title":550,"text":551},"the-checks","The checks","Every study: add the courses it runs in (or where it runs). None of them may be in another open study. A study that tells or asks people: add the consent form (or the research notice). A comparative study: define at least two conditions, add the activities and make the conditions differ. Have learners sign in the same way every visit, publish an agent, and choose the key that pays for the AI. Depending on how it assigns: add the pre-test, make consent about the use of data, add sections to each course, and give each section its condition. On a chat page: turn on an agent's chat page. Recommend",{"path":553,"title":554,"description":555,"updated":421,"minutes":32,"sections":556},"research\u002Fdesigns","Choosing a study design","Choose whether a study follows use, compares units or compares groups, and where it runs.",[557,559,563,567],{"id":17,"title":17,"text":558},"Choose the kind of study by what changes for learners. What changes for learners Choose The study is Nothing: you follow how a class uses a course, or how visitors use a chat page Follow how it is used Observational, with no conditions The same learners have the AI in some units and not others, or one agent and then another Compare units, with the same learners Comparative, comparing units: one plan, or two orders drawn at random Learners or whole classes get different versions Compare groups of learners Comparative, comparing groups: each learner or section gets one condition Two orders keep ",{"id":560,"title":561,"text":562},"common-designs","Common designs","RCT: comparing groups, With AI and Without AI, each person at random. Cluster randomized: comparing groups, each section at random, with consent about the use of data. Existing classes, not randomized: comparing groups, each section given its condition by you. Two AIs: comparing groups, one condition using another agent, such as one with VETTING. Units with and without AI: comparing units, one plan. Crossover (AB\u002FBA): comparing units, two orders, the second the reverse of the first. Waitlist: comparing groups, the later group without AI until a given unit.",{"id":564,"title":565,"text":566},"where-it-runs","Where it runs","Where it runs holds the study's courses and chat pages, up to 40. Courses have known learners, each with its own link, class list and sections: one per school, class or online sample. A chat page can host an observational study. Each device is an anonymous visitor, shown by visitor code (V-…). To know who learners are, or to compare, use a course. A comparative study runs on courses only. A course or chat page is in one study at a time, until that study closes. You can remove one only while nobody has taken part through it. How learners sign in sets one way for every course while the study is ",{"id":568,"title":569,"text":570},"who-changes-activities","Who changes activities","Observational: the activities stay the course's. Teachers keep changing them, and every record carries its activity version. Comparative: the first course you add with activities gives the study its design. Its activities move into the study and are changed on Design, for every course at once. Other courses must have no activities of their own. A teacher studying their own course changes its activities in the study too. Teachers still set opening times and extra time. Teachers who run a course join the project as editors. Your first study: start from your situation. Conditions and assignment: ",{"path":572,"title":573,"description":574,"updated":421,"minutes":32,"sections":575},"research\u002Fconsent","Consent and taking part","Choose what people are told or asked, handle minors and paper forms, and withdraw someone who asks.",[576,578,582,586,590],{"id":17,"title":17,"text":577},"A study's Consent tab decides what people are told or asked before they start, and so whose data the study uses. People who decline or opt out still use the course or chat. Option What people see In the data Include everyone, without asking Nothing Everyone Show a research notice A notice; on a chat page, a line above the chat opens it Everyone A notice they can opt out of The notice, with a way to keep their work out (Don't use my chats on a chat page) All but those who opted out Ask for consent on a form A form to decide on first Only those who agree Observational studies start with everyone",{"id":579,"title":580,"text":581},"the-form","The form","Choose Write it here (up to 20,000 characters, or Start from a template) or Use your approved PDF (up to 10 MB). After the study opens, a changed form is an amendment and a new version, listed under Versions of the form. With consent, people who decided on an earlier version are asked again on their next visit. With a notice, new arrivals read the new one. Pause the study while an amendment is reviewed. Agreeing covers any recordings the study keeps, so say so in the form.",{"id":583,"title":584,"text":585},"minors-and-paper-forms","Minors and paper forms","An assent form for minors: the form asks people their age, and minors agree on the assent form too. A children's course takes everyone as under 18. Parental permission for minors: a minor counts in the data once permission is recorded. Upload The form parents sign to print. Paper forms: as signed forms come back, select Record in the Parental permission column on Participants. Show them lists minors who are waiting.",{"id":587,"title":588,"text":589},"withdrawal","Withdrawal","Learners reread the study under About the study. With consent, Leave the study is final and keeps their earlier work out too. With an opt-out, they can opt out and back in. When someone asks you, select Withdraw beside them on Participants. Their records, earlier ones too, leave the study's data and coding samples. It is final.",{"id":591,"title":592,"text":593},"what-teachers-see","What teachers see","A course's Research tab shows its teachers how many learners take part, by condition. Owners and editors see names beside decisions; viewers see codes. No setting hides decisions from owners and editors. If an instructor must not know who agreed, don't make them one while it matters. How people take part, what consent covers and parental permission are fixed once the study opens. Conditions and assignment: set what differs and who gets which. The research export: see how consent marks every record.",{"path":595,"title":596,"description":597,"updated":63,"minutes":14,"sections":598},"research\u002Fconditions","Conditions and assignment","Set what differs between conditions and who gets which, then open, pause and close a comparative study.",[599,601,605,609,613,617,621,625],{"id":17,"title":17,"text":600},"Set up a comparative study's Design tab, then run the study. For example, half of a Grade 4 math class gets an AI tutor and half doesn't.",{"id":602,"title":603,"text":604},"the-design","The design","Design starts with What this study compares, then four steps that apply to every course at once. The activities. Edit them with the course's own editor. Pre-tests, post-tests and surveys are the same for everyone. What differs. Give each condition rules: the AI off, the AI sees nothing of the panels, typed only, replies not read aloud, another agent, or another way the AI helps. Who gets which, and when. Choose who is assigned, how, how it is balanced, and when. Agent versions. Opening the study pins each agent at its published version. A new activity starts hidden at every course until its te",{"id":606,"title":607,"text":608},"conditions-as-rules","Conditions as rules","A study has two to eight conditions, labelled A to H, each with a share from 1 to 10. Only in some units or activities adds exceptions, including Hidden for this condition. Check Side by side: what learners get in each condition before you open. When comparing units, The plan, unit by unit (or The orders) says whether each unit keeps its AI, has none, uses another agent, or helps another way.",{"id":610,"title":611,"text":612},"ways-the-ai-helps","Ways the AI helps","To compare how the AI helps rather than whether it is there, name each way once under Ways the AI helps: How much the AI does (from Only checks to Explains), its steps at the level Shows an example (Steps held by counting tries or Steps left to the AI) and When it writes first (Never writes first, or moments of its own, such as when a learner has been quiet for 3 minutes or after a wrong answer). Each is As designed unless you set it. Then choose a way: You compare Set it up Two groups, each with its own way Comparing groups: each condition's How the AI helps is one way The same class, one way",{"id":614,"title":615,"text":616},"assignment","Assignment","Who is assigned: Each person or Each section. How: At random, in shuffled blocks balanced by the shares, or for sections, By you. Balanced: Across the study, Within each section or Within each course. When: When they take part, After the pre-test, or At first use (not when comparing units). A condition never changes once given, on any activity or device.",{"id":618,"title":619,"text":620},"pinned-and-protocol-versions","Pinned and protocol versions","Learners keep meeting the pinned agent version as the agent changes. Use the latest published versions moves every course on. Once open, every design change and version move makes a new protocol version, shown in the study's header.",{"id":622,"title":623,"text":624},"open-pause-and-close","Open, pause and close","The header's status control runs Draft → Open ⇄ Paused → Closed. Each move explains itself first. Move What it does Open study People start taking part; assignment starts; agent versions are pinned. Pause Learners keep their condition. Nobody new joins the study, and nothing is recorded for it. Resume Takes people in and records again. Close study Conditions stop; courses return to their own settings; the data stays. Open again Reopens with the same conditions and pinned versions. Delete draft works only if the study never opened. Once open, how people take part, sign-in, assignment and condit",{"id":626,"title":627,"text":628},"participants","Participants","Participants shows Flow, as a CONSORT flow diagram (the standard chart of how participants move through a trial) counts it; Balance on the pre-test, as Hedges' g (a standardized difference between groups); People, each learner code with decision and condition; and The study's record of every decision, assignment and change. Consent and taking part: withdrawal and paper forms. The research export: conditions and versions in your data.",{"path":630,"title":631,"description":632,"updated":421,"minutes":32,"sections":633},"research\u002Fcoding","Coding conversations","Code a sample of messages with a codebook, add model coders, check agreement and decide the final codes.",[634,636,640,644,648],{"id":17,"title":17,"text":635},"Code what people wrote, such as what patrons ask a library's chat page. Research → Coding runs in four steps: codebook, sample, code, compare.",{"id":637,"title":638,"text":639},"codebooks","Codebooks","Pick a codebook: Help-seeking: executive or instrumental requests (Nelson-Le Gall). ICAP engagement: passive, active, constructive, interactive (Chi and Wylie); applying it to chat is an interpretation to state. Question depth: shallow, intermediate, deep (Graesser and Person). Accuracy of replies: accurate, partly accurate, inaccurate, didn't answer. What patrons ask: a library's request categories. Your own codebook: 2 to 20 codes. Each code has a label, a definition, examples and near misses. Changing codes after coding makes a new version, with a note on why; each sample keeps its version.",{"id":641,"title":642,"text":643},"draw-a-sample","Draw a sample","Choose the codebook. Select New sample and pick it. Set where it is drawn from. Under Drawn from, choose the period, study, chat pages or courses, and agents. Only people included in the study is on by default. Draw it. Enter Items to sample (up to 2,000) and, optionally, a Seed, then select Draw the sample. The same seed and choices over a finished period draw the same items. People who leave the study leave its samples.",{"id":645,"title":646,"text":647},"code-alone-and-with-model-coders","Code, alone and with model coders","On Code, code one item at a time with keys 1 to 9. Coding is blind: you see only your own codes until you open Review & decide. Any member, viewers included, can code. Model coders → Add a model coder adds a model as one more coder, billed to a key you choose. Under How strictly, Only these codes gives no code when nothing fits, never the closest. These codes, and suggest new ones may also propose codes. About your study adds context to its prompt. For each item it returns codes, a confidence, a quote kept only if it appears word for word, and a reason. You can read its exact prompt. Suggestio",{"id":649,"title":650,"text":651},"agreement-then-final-codes","Agreement, then final codes","Agreement compares every two coders on items both coded: percent agreement, Cohen's κ and a confusion table. For your methods section drafts a paragraph to copy. In Review & decide, select Show everyone's codes, which ends blind coding for you. Pick the final codes or No code fits, add a note, and Decide. Use the agreed codes for N settles items where coders agree. Owners and editors decide. Final codes feed an observational study's Summary and coding_final.csv. The research export: codes, codebooks and prompts in your data. Consent and taking part: who stays in your samples.",{"path":653,"title":654,"description":655,"updated":421,"minutes":32,"sections":656},"research\u002Fexport","The research export","Download a study's documented ZIP, read its consent marks, cite what learners saw, and delete a learner's data.",[657,659,663,667,671,675],{"id":17,"title":17,"text":658},"Get your data out as one documented ZIP, ready to analyze and cite. A study's Export tab opens Research → Export with the study chosen. Choose whose data. Pick a study, a course, or where (courses, chat pages, your apps on the API). Turn off Only people included in the study to get everyone, each record marked. Choose when and which agents. Choosing agents leaves out activities without AI. Choose what goes in. Turn on What was written, IDs from your systems, Recordings or Mask condition names as needed. Download. What's in the ZIP lists the files this selection fills. Then select Download ZIP.",{"id":660,"title":661,"text":662},"what-s-in-the-zip","What's in the ZIP","People and conversations: learners.csv; turns.csv, every message and reply with agent version, sources and rating; agents.csv. Work and measures: sessions.csv, attempts.csv (pyBKT format), outcomes.csv, writing.csv, responses.csv, activity_progress.csv and more. The study: enrollments.csv (decisions), assignments.csv, flow.csv (CONSORT counts), study_events.csv and study_documents.csv. Coding: coding_labels.csv, coding_final.csv and codebooks.json. The dictionary: data_dictionary.csv defines every column and its sources. manifest.json records your choices, the protocol and checksums. Names, ty",{"id":664,"title":665,"text":666},"consent-marks","Consent marks","Records from a study carry study, condition and participation. The participation mark is included, opted_out, declined, withdrawn, awaiting_permission or not_in_study. Inclusion is decided at export, never by deleting records.",{"id":668,"title":669,"text":670},"masked-conditions-and-recordings","Masked conditions and recordings","Masked conditions appear as A, B and so on, without their names, rules or agents' names. The study's Data tab sets the default. Recordings exist only when Keep recordings of what people say is on in Data. Once the study opens, you can turn it off but not on. recordings\u002F holds them only for people whose data counts. turns.csv and responses.csv name each file.",{"id":672,"title":673,"text":674},"citing-what-learners-saw","Citing what learners saw","Activities: records carry activity_version, and manifest.json lists each version's settings SHA-256. Agents: turns carry agent_version, and agents.csv gives each workflow's SHA-256. For a comparative study, the manifest gives pinned versions and the protocol version. Forms: decisions carry their form version, and study_documents.csv gives each PDF's SHA-256. Coding: codebooks.json gives codebook versions, seeds, and each model coder's settings and prompt.",{"id":676,"title":677,"text":678},"deleting-a-learner-s-data","Deleting a learner's data","Find the person. Open them in Teach → Learners, or under Chat page visitors. Delete. Select Delete data…, then Delete their data. This can't be undone. Their messages, answers, drafts, scores, coding labels, recordings and what agents remembered are deleted, and so is a learner's name. Their study decisions and code stay, as review boards require, and learners.csv marks data_deleted_at. Owners and editors delete. Coding conversations: code a sample before you export. Consent and taking part: what each consent mark means.",{"id":680,"title":681,"lead":682,"pages":683},"build","Build agents","Make the AI: its steps, knowledge, checks and chat page.",[684,711,865,896,931,966,978],{"path":685,"title":686,"description":687,"updated":63,"minutes":256,"sections":688},"build\u002Ffirst-agent","Your first agent","Make an agent from a template, try it on your own key, change one step, publish it and read one run step by step.",[689,691,695,699,703,707],{"id":17,"title":17,"text":690},"This page takes you from nothing to a published agent in about ten minutes. Start here before you build anything for learners. An agent is a workflow of steps. It reads a message, can search your documents and check its own reply, then answers. Learners meet the published version in course activities or on its chat page. You need to be an owner or editor of the project. Viewers can look, but not try or change an agent. Trying an agent runs it for real on a project API key with the Run agents permission, billed like any request. New keys include it.",{"id":692,"title":693,"text":694},"make-it-from-a-template","Make it from a template","Open the templates. In Build → Agents, click New from template. Pick a tutor. Choose Safety & review → Tutor with guardrails. Before you run says what a template needs; this one needs nothing. Name it. Names are unique in the project. Click Create & open. The canvas shows five steps, each card saying what it does. input goes to screen, a Guardrail step that checks each message for personal data, jailbreaks and harmful content. A message that passes goes to tutor, an LLM step, and its answer to reply. One that fails goes to blocked, a Reply step with a fixed message. You can also describe the a",{"id":696,"title":697,"text":698},"try-it","Try it","Open the test chat. In the right panel, click Test, then Try it. Choose who pays. Click Options, choose a key under Who pays, and click Done. The key is remembered for this project. Send the example. Click the example message to put it in the box, then press Enter. Under the reply you see its cost, its steps and how long it took. Test the guardrail. Send \"My email is sam@example.com, can you check my essay?\" The guardrail fails it, and blocked answers instead.",{"id":700,"title":701,"text":702},"change-one-step","Change one step","Open the tutor. Send the example message again, so the last run goes through tutor. Click tutor on the canvas. Step settings says what it does, such as \"Writes a reply with viable-3\" (one of the models VIABLE lists), and shows the last run's time and cost. See what it gave. Under Later steps can use, tutor → reply text shows what it wrote for your last message. Change its instructions. Under Setup, click Open editor under Instructions, add \"Use one short paragraph.\", and click Done. Run only this step. Click Run step, then Run. It writes a new answer from your last message on the same key, bil",{"id":704,"title":705,"text":706},"publish","Publish","Click Publish, look over the review, and click Publish version 1. The badge now says Published, and the agent list shows Live · v1. Later edits stay in the draft until you publish again.",{"id":708,"title":709,"text":710},"read-one-run","Read one run","Open the runs. Click Test → Run history. Your tries are at the top, marked Dashboard test. Open one. You see its reply, duration, model calls, tokens and cost. Follow a step. Under Run trace, click tutor. Input shows its instructions, the message and how many earlier messages went with it. Output shows its reply. Check the guardrail. Click screen to see what it checked and its verdict. That is the loop: change the draft, try it, publish, read what happened. Steps: what each step does, and when to use it. Testing and run history: try versions of a message and read any run. Chat pages for websit",{"path":712,"title":713,"description":714,"updated":63,"minutes":715,"sections":716},"build\u002Fsteps","Steps","Choose the right step for each job, set it up in its panel, and edit, share and version an agent's workflow.",16,[717,719,723,727,731,735,738,742,746,750,753,757,761,765,769,773,777,780,784,788,791,795,799,803,807,811,814,818,822,826,829,833,837,841,845,849,853,857,861],{"id":17,"title":17,"text":718},"Every agent is a workflow of steps on a canvas. This page shows how a step's settings are laid out, says what each step does and which settings matter, then covers editing, sharing and versions.",{"id":720,"title":721,"text":722},"how-a-step-s-settings-are-laid-out","How a step's settings are laid out","Click a step on the canvas to open it in Build → Step settings. Every step's panel has the same parts, top to bottom: The step. Its type, its ID (other steps refer to it by this, and you can rename it), its status, Run step (for a step that can run alone), ? for how to use it, and ⋯ for the step's menu. What it does. A sentence says what the step does as it is set up, such as \"Writes a reply with viable-3\". Its canvas card shows the same sentence. Click a phrase in it to go to that setting. Setup. The decisions every author of this step makes, such as its model and instructions. Answer format,",{"id":724,"title":725,"text":726},"a-setting","A setting","Each setting has an ⓘ tip and a ⋯ menu. The menu switches a value to Use text, Use a field, Use a condition or Edit as expression. It also has Reset to default, Learn more and, where they apply, Copy reference and Show on block. A value reads as text, with earlier steps' fields as chips, such as tutor → reply text. Type { or \u002F, or click the { } button, to insert a field. A condition or an expression reads as a sentence first. Edit opens its editor. An expression's editor has Insert a field… and Insert a function…. Long instructions show their first lines. Open editor edits them full width, wit",{"id":728,"title":729,"text":730},"find-a-setting-fix-an-issue","Find a setting, fix an issue","Find a setting (⌘K on a Mac, Ctrl K elsewhere) searches every setting of the step, set or not. Choose one to go to it. One under Add option is added. The status beside the step's ID says Ready, or how many issues the step has. Click it to list them, with Go to setting when an issue names one. After a message in Try it, the panel shows what the step did in that run. Testing and run history says how to read it and how to run one step alone.",{"id":732,"title":733,"text":734},"start-from-a-common-use","Start from a common use","Add step (or \u002F) opens the step library, grouped as the sections below. A step with common uses, such as Image, Branch or VETTING, then asks how to start: choose one, such as Draw what an LLM planned, or Blank. A common use fills in settings you can change.",{"id":736,"title":737,"text":17},"start-and-reply","Start & reply",{"id":739,"title":740,"text":741},"input","Input","Starts the run with the learner's message and the conversation so far. Every run starts at the step marked Entry, and one Input is enough. Options. Instructions in Try it and Example message help people who test the agent. Long conversations sends the latest messages, or Summarize when the conversation gets long: near the models' limit, it folds the oldest messages into a summary, one small model call each time. Later steps can use. Message, which {{input}} reads anywhere, and Earlier messages.",{"id":743,"title":744,"text":745},"reply","Reply","Ends a path with the reply the reader sees. Setup. Reply text: an earlier step's field, such as tutor → reply text, or words you write. Options. Picture or audio attaches an Image or Speech step's address. Result data for your app is JSON your app reads beside the reply; readers never see it. Sources in Chat Completions replies lists cited sources in the text, for chat clients that show only text.",{"id":747,"title":748,"text":749},"ask-user","Ask user","Replies with a Question and waits. The next message in the conversation carries on from here, and later steps read The user’s answer. It needs a conversation kept on the server; otherwise the question is just the reply.",{"id":751,"title":752,"text":17},"ai","AI",{"id":754,"title":755,"text":756},"llm","LLM","Writes a reply, or returns named fields, with one call to a chat model. It can't search or use tools; an Agent step can. Setup. Model, Instructions, and What it reads: Earlier turns (on by default), Reference data, This conversation’s pictures, and a Custom input in place of the learner's message. Answer format. Plain text, or Named fields that later steps and Branch rules read by name. Options. Image inputs, and model settings such as Temperature and Reasoning effort. Later steps can use. Reply text ({{tutor.content}}), or each named field ({{tutor.json.reply}}). Ways to start. Reply to the l",{"id":758,"title":759,"text":760},"agent","Agent","Lets a model choose tools until it can answer. Setup. Model, Instructions, Use knowledge and What it reads. Options. Tools you draw, Remember the user, Read web pages, Hand off to agents, and Most tool calls (5 by default). Later steps can use. Final answer ({{helper.content}}) and Tool calls. Each tool call is one more model call, so an Agent step is slower and costlier than fixed steps, and its path varies. A rule that must always hold, such as \"never give the answer\", needs a check: a VETTING or Guardrail step. Tools you draw. You decide what a tool can do, and the model decides when it is ",{"id":762,"title":763,"text":764},"image","Image","Draws or changes pictures. Setup. Model, then What to draw: One prompt, or A list from an earlier step, usually an LLM step's list. With a list, choose it under List: each item becomes its own picture, three at a time. Prompt describes one scene, or adds to each item's prompt. Options. Pictures per prompt draws one scene several times in one model call. Most pictures a turn caps a list (4 by default, up to 6). Create or change draws new pictures or changes one, and Picture to change takes the number the learner sees. Remember for later turns is on by default. When something goes wrong. If the ",{"id":766,"title":767,"text":768},"speech","Speech","Reads Text aloud in a Voice and passes on the recording's Audio address. Attach {{speak.url}} under a Reply's Picture or audio. Speed is an option.",{"id":770,"title":771,"text":772},"transcribe","Transcribe","Turns a Recording into text: the one sent with the message, or a recording's address. Language and Words to expect help it hear. Later steps read Transcript. Put it before the steps that use what was said.",{"id":774,"title":775,"text":776},"sub-agent","Sub-agent","Hands the message to another published Agent of this project and uses its Reply. Message to send replaces the message. Its model calls count toward this run.",{"id":778,"title":779,"text":17},"checks-and-review","Checks & review",{"id":781,"title":782,"text":783},"vetting","VETTING","Has an independent reviewer check each reply against your rules, and revise it until one passes. Setup holds Checks against, the Reply model and Answer to review. Attempts is under When something goes wrong. Each of the Outcomes, Passed, Unverified and Needs attention, goes to its own step. See VETTING.",{"id":785,"title":786,"text":787},"guardrail","Guardrail","Checks text once and goes to pass or fail. Setup. Checks: Personal data (no model call), Jailbreak \u002F prompt injection, Harmful content, Off topic (with an Allowed topic) and Custom policy. Text to check is the current message, or custom text such as {{tutor.content}} to screen a reply. Later steps can use. Passed, Findings and, with Personal data, Text with personal data masked. Ways to start. Screen the learner’s message, Keep to a topic or Mask personal data.",{"id":789,"title":790,"text":17},"routing-and-logic","Routing & logic",{"id":792,"title":793,"text":794},"branch","Branch","Chooses a path by a field from an earlier step, with no model call. Condition. One condition goes to Yes when it holds and No when it doesn't. Cases. Checked from the top; the first that holds decides, and Otherwise, go to takes the rest. Each case is a set of rules (a field, a test and a value, joined by all or any), or an expression after Edit as expression. A list's rules can test its items, such as has more than … items, has an item whose … is empty or is empty without items whose … is. Name this case labels a case's connection on the canvas and its place in runs. Routing never reads the n",{"id":796,"title":797,"text":798},"router","Router","A model sorts each request into one of your named Routes (up to 12, each saying when to choose it). Anything unclear takes fallback. It costs one model call; when an earlier field already decides, a Branch does it for free. Later steps read Chosen route and Reason. Ways to start: Questions or tasks or Coursework or admin.",{"id":800,"title":801,"text":802},"for-each","For each","Runs the same steps once for every item of a List, one after another, then carries on with what each pass kept. Connect for each item to the first step to repeat, and the last one back to the For each step. Steps inside read {{item}} and {{item_number}}, or the Name for one item you choose. At most caps the items (10 by default, up to 25). Keep from each item says what each pass keeps, such as {{review.json.correct}}. when done carries on with What each item kept ({{check.values}}). Steps inside can't reply or ask. For pictures, an Image step with a list is simpler.",{"id":804,"title":805,"text":806},"loop","Loop","Repeats steps A number of times or While a condition holds, then goes to done. A run visits a Loop at most 25 times. Counter name names the pass number later steps read. Ways to start: Repeat a number of times or Repeat until something holds.",{"id":808,"title":809,"text":810},"parallel","Parallel","Runs 2–6 Paths at the same time, then carries on at the join step once all finish. It saves time; each path still spends its own model calls.",{"id":812,"title":813,"text":17},"knowledge-and-memory","Knowledge & memory",{"id":815,"title":816,"text":817},"knowledge","Knowledge","Searches 1–5 Knowledge bases for the current message, or for what you write in Search for. Later steps read Passages with sources ({{search.context}}) and Passages found. Passages to return is 5 by default, up to 20. See Knowledge bases.",{"id":819,"title":820,"text":821},"memory","Memory","Recalls or keeps lasting facts about the user across conversations. Its Action is Recall relevant memories, Save a specific fact or Learn facts with a model, which makes one model call; put that after the step that writes the reply. It needs the user's identifier or a server conversation. Ways to start: Recall what it knows about the user, Save one fact or Learn from the conversation.",{"id":823,"title":824,"text":825},"state","State","Sets Variables for this run, or keeps them for later turns with Keep values → For this conversation. Read them anywhere as {{vars.name}}. Pictures need no State step. Ways to start: Keep a value for later turns or Count attempts.",{"id":827,"title":828,"text":17},"web-and-data","Web & data",{"id":830,"title":831,"text":832},"fetch-url","Fetch URL","Reads one public HTTPS Web address, or sends JSON to an API. It doesn't search the web or run a site's JavaScript. Later steps read Web page as Markdown, Succeeded and HTTP status. Ways to start: Read a web page or Send JSON to an API.",{"id":834,"title":835,"text":836},"component","Component","Runs another team's method as a step, from the manifest its authors publish: what the component does, the learner data it receives, the hosts it contacts, its license and its evidence. A component on VIABLE runs at a public HTTPS address; one that runs as an MCP server runs with viable-engine serve on your own machine instead. Setup. Component manifest: paste the JSON, or Upload a manifest file. The panel shows what it receives, the hosts it contacts, its risk and license, or what stops it running. Its slot must be step. What it sends has one row per field the manifest receives, such as learne",{"id":838,"title":839,"text":840},"values","Values","Works out named values from earlier steps, each able to use the ones above it, with no model call. In Code and the API its type is transform. The panel shows one row per value, split into Used by other steps and Used only here. A row shows the value's name, what it works out and, after a Try it run, what it held. Open a row to edit it. It says which steps use it, such as reply → Reply text. Add value adds one. Edit as JSON shows them all as JSON. Later steps read each one by name, such as {{summary.text}}. A long calculation reads best here, one value per row. A value is text with fields, or a",{"id":842,"title":843,"text":844},"edit-on-the-canvas","Edit on the canvas","Drag from an output dot (next, pass…) onto the next step. Every run starts at the step marked Entry. A step's ⋯ menu has Make this the entry step. The chip beside Tools says Ready, or how many issues to fix. Tips under it suggest ways to make a working workflow simpler, such as a list instead of copied steps. Tidy lays the steps out left to right. A connection back to an earlier step, a loop's way back, goes round underneath, and the steps a For each step repeats sit in a frame. Never put a password, API key or token in a step. Every project member can read it, and Export JSON copies it into t",{"id":846,"title":847,"text":848},"note","Note","A Note step is a sticky note for collaborators, from Add step → Annotate. Notes never run.",{"id":850,"title":851,"text":852},"groups-and-blocks","Groups and blocks","To keep a large workflow readable, open a step's ⋯ menu and choose Put in a new group. Name the group on its frame and fold it into one block. Groups never change what runs. What it does and its settings, a button on a group's frame, opens the Block panel, and so does a click on a folded block. What it does is a sentence of up to 280 characters, shown on the folded block. To show a setting on the block, open a step inside and choose ⋯ → Show on block on that setting. Up to 8 settings show on the folded block with their values. Change them in the Block panel's Settings on this block, without op",{"id":854,"title":855,"text":856},"code-view-and-the-assistant","Code view and the assistant","Build → Code shows the workflow as JSON. Edit it or paste JSON from an AI tool, then click Apply JSON; until then you can't publish. AI prompt + JSON writes a prompt for your own AI tool. Build → Assistant answers questions about the agent and proposes changes, each waiting for Apply to draft or Discard. Ask about this step, in a step's panel, starts a question about that step.",{"id":858,"title":859,"text":860},"work-together","Work together","An agent has one shared draft that saves as you go. Edits from teammates, the API and the VIABLE CLI land in it too. Share & invite invites people to the whole project as Editor or Viewer. Undo undoes only your own edits.",{"id":862,"title":863,"text":864},"versions","Versions","History → Save a version marks a point to return to. View & restore versions lets you Preview one or Restore it into the draft. Publish makes the draft a new numbered version, the one learners, chat pages and apps use. Its review lists problems by step, with Go to step. Tools → Discard changes puts the draft back to the live version. Tools → Unpublish agent stops new runs and keeps the draft. VETTING: check every reply against rules you state. Knowledge bases: give an agent documents to search and cite. Testing and run history: try the draft, run one step, and read each step of a run.",{"path":866,"title":782,"description":867,"updated":63,"minutes":868,"sections":869},"build\u002Fvetting","Have an independent reviewer check each reply against your rules, and decide what learners see when none passes.",6,[870,872,876,880,884,888,892],{"id":17,"title":17,"text":871},"A VETTING step has an independent reviewer check each reply against your rules. Use it when replies must follow rules you can state. VETTING (Verification and Evaluation Tool for Targeting Invalid Narrative Generation) comes from classroom research (a middle school study). Use it for a tutor that never gives the answer away, or an assistant that says only what its sources say.",{"id":873,"title":874,"text":875},"how-it-works","How it works","The reply model writes a reply. The reviewer model checks it in a separate call and gives a verdict and a reason. A failed reply goes back with that reason, until one passes or the Attempts run out. The reviewer's rules live in the step, apart from the reply model's instructions, so a learner can't talk the reviewer out of them. It reads the reply and nothing the learner wrote. With an answer key, a reply that confirms an answer as the learner's own passes, one that supplies it fails, and one that calls a wrong answer right fails. A learner who has the answer is told so. Code decides that, so ",{"id":877,"title":878,"text":879},"fast-or-careful","Fast or careful","A learner waits for every round, one reply and one review, with nothing on the page until one passes. With a strict reviewer that can be half a minute. How much care is worth how much waiting depends on your learners, so it is yours to set, and the defaults are only a place to start. To change Do this And A shorter wait Fewer Attempts, or a faster Reviewer model More replies end unverified, or pass with a lighter review More care More Attempts, or a stricter Reviewer model A longer wait, and more cost No wait at all Take the VETTING step out Nothing checks replies before learners see them, and",{"id":881,"title":882,"text":883},"set-it-up","Set it up","When you add a VETTING step, choose how to start: Check replies against a guideline, Don’t give a question’s answer away, Check an earlier step’s answer, or Blank. Then: Choose what it checks against. Under Setup → Checks against, pick A guideline or A question and its answer key. The Answer key is seen only by the reviewer. Set the reply model. Choose a Reply model. Add option → Reply instructions replaces its default prompt. Safety rules are always added. Choose the first answer. Under Answer to review, pick The reply model writes it or An earlier step’s answer. Set the reviewer. Add option ",{"id":885,"title":886,"text":887},"outcomes","Outcomes","Passed: the reviewer approved the reply. Unverified: no reply passed, or a review couldn't run. Later steps get the last reply, not approved. Needs attention: the reply model found the conversation unsafe, such as self-harm. It wrote a caring reply instead, which isn't reviewed.",{"id":889,"title":890,"text":891},"what-learners-see","What learners see","Learners see only what the Reply step on each path says. They never see drafts, the reviewer's reasons or the answer key. Decide what the Unverified path says. The VETTING templates give a fixed message instead of the unapproved reply. Insights lists replies that didn't pass.",{"id":893,"title":894,"text":895},"when-a-teacher-sets-how-the-ai-helps","When a teacher sets How the AI helps","In a course activity, a teacher uses How the AI helps to say how much the AI does. Say a Grade 6 teacher chooses Gives hints. The reply model gets it as instructions, headed \"From the teacher of this activity\". The reviewer checks each reply against it too. What the reviewer reads is only the reply unless you choose otherwise: in a step's settings here, or for one activity in How the AI helps. With the learner's message too, the reviewer can tell their own idea from one handed to them, and it fails a reply that doesn't answer them; their message reaches it as data, but a learner who knows it i",{"path":897,"title":898,"description":899,"updated":63,"minutes":868,"sections":900},"build\u002Fknowledge","Knowledge bases","Add documents and websites to a knowledge base, choose how it finds passages and who pays, and have agents search it and cite their sources.",[901,903,907,911,915,919,923,927],{"id":17,"title":17,"text":902},"A knowledge base holds documents and websites your agents search and cite. Use one when answers must come from your own material, such as a syllabus or a library's guides. Knowledge bases live in Build → Knowledge. Agents search only knowledge bases in their own project.",{"id":904,"title":905,"text":906},"add-documents-and-websites","Add documents and websites","Make it. Click New knowledge base, name it, and choose how it searches (below). Add files. On Files, drop files or a folder, up to 15 MB each. Paste text adds notes or an FAQ. Add websites. On Websites, choose Specific pages, A whole website or Pages linked from one page. Choose how often to re-check. Check for changes runs from Daily to Yearly, or Only when I sync. The default is Monthly. Files can be PDF, Word, PowerPoint, Excel, Markdown, text, CSV, HTML, JSON or images. Specific pages and A whole website take up to 20,000 pages per import. Pages linked from one page takes up to 1,000. Spec",{"id":908,"title":909,"text":910},"choose-how-it-searches","Choose how it searches","Search How it works Best for Hybrid Keywords plus meaning, reranked Paraphrased questions, and questions in other languages Keyword only Keywords, with no AI calls and nothing to pay Predictable results on consistent terms To find passages by meaning, a hybrid knowledge base turns each passage into a list of numbers with an embedding model. Choose an embedding model when you create a hybrid knowledge base, or change it in ⋯ → Settings under Finding passages by meaning: Default model (recommended): multilingual, so an English question can find notes in another language. VIABLE's scores and \"not",{"id":912,"title":913,"text":914},"who-pays-for-it","Who pays for it","Creating a hybrid knowledge base or turning on hybrid search requires an active VIABLE project API key with Model requests permission. It tracks requests and applies the key’s limits. Billed to key identifies the project key for indexing that uses VIABLE credits. With a provider model, the provider key selects the upstream account and normally pays for its calls. VIABLE does not charge for searches. Choose Create with keyword search if you want to upload material before setting up a project API key. If the key for an existing hybrid knowledge base stops working, semantic indexing can pause whi",{"id":916,"title":917,"text":918},"settings-that-change-answers","Settings that change answers","In the knowledge base's Settings: Passage size: Short, Standard or Long (about 600, 1,200 or 2,400 characters), or Custom, from 300 to 4,000. Changing it splits the stored text again, and a hybrid knowledge base embeds it again; nothing is fetched again. Agents don't change it per search. Leave out text a website repeats on its pages: drops navigation and footers from passages. Let readers open cited files: cited uploaded files link to the file for 7 days. Leave it off for internal or licensed files, and readers see only their names. Web pages always link.",{"id":920,"title":921,"text":922},"duplicate-a-knowledge-base","Duplicate a knowledge base","⋯ → Duplicate… makes a copy, in this project or another where you're an owner or editor. It takes the documents, their passages and search index, and the knowledge map as last built. Nothing is fetched from websites or embedded again, so it costs no credit. Websites keep their schedule, so each site is read for both. Set the copy's websites to Only when I sync if one is enough. In another project, choose one of its keys to pay for new passages, and build the map again there to keep it up to date. A model named through this project's provider key (@…) isn't copied: the copy embeds again there o",{"id":924,"title":925,"text":926},"how-agents-search","How agents search","Two steps search, and they suit different questions. A Knowledge step searches its Knowledge bases once, for the current message or what you write in Search for, and passes on numbered passages: Passages to return is 5 by default and up to 20. Put {{search.context}} in an LLM step's instructions. Tell it to answer only from those sources and cite them as [n]. Branch on {{search.count}}, which is 0 when nothing matched. The Answer from my documents template works this way. An Agent step with Use knowledge searches as often as it needs and reads whole sections. Use it for lists, comparisons and ",{"id":928,"title":929,"text":930},"citations","Citations","Citations are numbered in the order a reply mentions them, one per page or file. On a chat page, each reply shows its sources. Test search shows exactly which passages an agent would receive for a question. Build an agent with it starts the agent designer with this knowledge base chosen. Your own AI can do all of this through the CLI: viable developer knowledge create, settings, duplicate, retry and search. Steps: the Knowledge, LLM and Agent steps in context. VETTING: have a reviewer check replies against your sources. Chat pages for websites: what visitors see of your sources.",{"path":932,"title":933,"description":934,"updated":63,"minutes":445,"sections":935},"build\u002Ftesting","Testing and run history","Try your draft on a key you choose, run one step alone, read every step of any run, and see what people ask the published agent.",[936,938,940,944,948,952,956,960,964],{"id":17,"title":17,"text":937},"This page is for agent builders. Try your draft before learners meet it, check it against tests, then read what happened in any run.",{"id":696,"title":697,"text":939},"Test → Try it runs the unpublished draft, so you don't need to publish to test. Who pays. Every message is a real run on the key under Options → Who pays. It needs the Run agents permission and must allow your steps' models. A stopped run still bills the model calls it started. Memory. Options → Memory chooses Continue a conversation (recommended), Independent messages or Send history from this browser. Test as. Options → Test as sends a person's identifier, such as student-042, as your app would. Reference data. Material sent with each message, such as a rubric. Steps read it as {{context.nam",{"id":941,"title":942,"text":943},"what-a-step-did-in-the-last-run","What a step did in the last run","After a message in Try it, click a step on the canvas. Its panel shows what the step did in that run: Under its sentence: Last run with its time and cost, Last run failed, or Not reached in the last Try it run. Under a setting: Last run: and what the setting worked out to, such as an LLM step's instructions with their fields filled in. Under Later steps can use: what each output held. A Values step shows each value's. In a Branch step: last run marks the case the run took. earlier version means the workflow changed since that run, so these values come from the version that ran.",{"id":945,"title":946,"text":947},"run-one-step","Run one step","Run step, at the top of a step's panel, runs only that step, once, as it is set up now, with what the last Try it run gave it. Use it to try a change to one step without sending a message through the whole agent: new instructions, another model, a different list of pictures. To see what learners get, send a message in Try it. Start from a run. Send a message in Try it, with a key under Options → Who pays. Open the step. Click it on the canvas, change what you want to try, and click Run step. Run it. Starts from names the run, and Who pays names the key. Click Run. You see Done or Failed, the t",{"id":949,"title":950,"text":951},"run-history","Run history","A run is one execution of an agent. Test → Run history lists runs newest first. Filter by Where runs came from, such as Chat page, Course or Dashboard test, and by How runs ended. You can also filter by result data, for example needs_human: true. Export downloads the latest 200 as CSV or JSONL.",{"id":953,"title":954,"text":955},"a-run-s-trace","A run's trace","A run shows its reply, duration, model calls, tokens and cost. Run trace lists the steps in order. A step's Input is what it acted on; its Output shows the result (Pretty or Raw JSON) with the Provider calls. A VETTING step lists each round's verdict and the Reviewer's reason.",{"id":957,"title":958,"text":959},"tests","Tests","To check a change against what learners might say before you publish, keep tests and run them: see Agent tests.",{"id":961,"title":962,"text":963},"insights","Insights","Test → Insights shows what people ask the published agent over 7, 30 or 90 days, without your tests, and flags answers that need a look: Failed, Not answered, Needs a person and Review didn't pass. Topics groups recent questions, with What the sources seem to miss. For the middle two, have your Reply step return \"status\": \"not_found\" or \"needs_human\": true in Result data for your app.",{"id":819,"title":820,"text":965},"Memory is what an agent keeps about a person between conversations, up to 200 facts each, from a Memory step or Remember the user in an Agent step. A person is the user your app sends, or a chat page's visitor. Test → Memory lists who the agent remembers and what. Deleting a fact, or using Forget everything about a person, is permanent. VETTING: what each outcome of a VETTING step means. Learners and traces: name your app's users and keep each run's trace.",{"path":967,"title":968,"description":969,"updated":970,"minutes":32,"sections":971},"build\u002Fagent-tests","Agent tests","Keep cases of what learners might say and what a good reply does, and run them on a version before you publish.","2026-11-01",[972,974],{"id":17,"title":17,"text":973},"Before learners meet a change, run your agent on cases you keep and let a judge model say whether each reply does what it should. Use it after editing a prompt, adding a step, or switching a model. A test is a moment a learner might bring and what a good reply does. Test → Tests, beside Run history, keeps up to 25 per agent; editors write and run them, and the project reads them. A test. The learner's message, or a short conversation ending with it, and what a good reply does. Optionally, what it must not do (such as \"give the final answer\"), a name, and reference data. Save as a test, in a Tr",{"id":975,"title":976,"text":977},"from-the-cli","From the CLI","Your own AI can run them too: viable developer agents tests list|set|run-case|runs, naming the key that pays and confirming each run, like a test run. In tests set, a test's pictures are [{\"url\": \"https:\u002F\u002F…\", \"description\": \"what it shows\", \"label\": \"Mom\"}], or {\"reason\": \"safety\", \"description\": \"…\"} for one that wasn't drawn. See The CLI and Agent Skills. Testing and run history: try a draft and read any run's steps. VETTING: a reviewer that checks each reply before learners see it.",{"path":979,"title":980,"description":981,"updated":13,"minutes":868,"sections":982},"build\u002Fchat-pages","Chat pages for websites","Put a published agent on a website as a link, a QR code or a chat button, within limits you set.",[983,985,989,993,997,1001,1005,1009,1013],{"id":17,"title":17,"text":984},"A chat page puts a published agent on any website as a link, a QR code and a chat button. Visitors need no account, so it suits a library's help desk. It always runs the published version. To know who learners are, use a course instead. Librarians can start from Overview → Open learning on a website.",{"id":986,"title":987,"text":988},"turn-it-on","Turn it on","Open the tab. Publish the agent, open Connect → Chat page, and click Set up chat page. Choose the key. Under Key & limits, pick the key it Runs on. Every message is a run on this key. Turn it on. Set limits and websites (below), then click Turn on chat page.",{"id":990,"title":991,"text":992},"share-it-or-add-it-to-a-site","Share it or add it to a site","Share gives the link and QR code. Add it to a site asks Where will people chat? and gives the steps for each place. On any website, paste the script before \u003C\u002Fbody>. Copy yours from the tab:",{"id":994,"title":995,"text":996},"the-chat-button","The chat button","Under Chat button, choose what the button opens: Window: the chat floats over the corner of the page. Escape closes it. Side panel: the page moves aside and the chat stays beside it, open from page to page in the same tab, like a docs site's assistant. Where fewer than 640 pixels of page would be left, the panel lies over the page instead. On a phone, either one fills the screen. While the chat is open, the button steps aside; the chat's own close button brings it back. With the profile's theme on Automatic, the chat takes the website's own light or dark when the site declares it (CSS color-sc",{"id":998,"title":999,"text":1000},"limits-and-allowed-sites","Limits and allowed sites","All visitors, per day: 10–5,000 messages, default 300. Daily cap sets what it may spend a day. Each visitor, per minute: 1–30, default 8. Each visitor, per day: 0 for no limit. Longest message: 200–4,000 characters. Daily counts reset at midnight UTC. One network address can send up to 400 messages a minute to an agent, so a school's classes can share it, and each visitor also keeps their own per-minute limit. The daily limit is shared by all visitors: at 300 a day, 30 learners get ten messages each. Only these websites (up to 20) limits where the button and frame appear, not the link.",{"id":1002,"title":1003,"text":1004},"recordings-and-attachments","Recordings and attachments","What it records: each device is an anonymous visitor with a visitor code (V-…), listed in Teach → Learners. Keep recordings saves spoken messages privately. Voice: with a Transcribe step, Visitors can speak appears. With a Speech step, so does Play answers aloud. Photos & files: up to 4 files of 8 MiB each, when every step that reads the message can read them.",{"id":1006,"title":1007,"text":1008},"what-it-makes-public","What it makes public","Anyone with the link, or on an allowed site, can chat with your agent on your key. The profile is public. Replies show their sources, but uploaded files show only their names unless the knowledge base allows opening them. The page hides your workflow, but a model can repeat its instructions. Write nothing there you wouldn't show a visitor. Visitors can't see each other's conversations. People sharing one computer and browser are one visitor. Pause takes the link and embeds offline. Turn off chat page also clears the settings.",{"id":1010,"title":1011,"text":1012},"the-agent-profile","The agent profile","The profile is how the agent presents itself, on its chat page and in courses. In Connect → Profile → Edit profile, set the Greeting, up to four Suggested questions and the Notice saying what the AI is. Changes show without publishing.",{"id":1014,"title":1015,"text":1016},"take-it-to-your-own-server","Take it to your own server","On Agents, open the agent's ⋯ menu, choose Export…, then With its knowledge (.zip). No course is needed. Owners and editors can download it. It holds the published version, its knowledge bases with their files, the text of their website pages as VIABLE last read them, its profile and chat page settings, and the agents it calls. It leaves out the page's key, conversations, logs and the headers of Fetch URL steps. Anything else it had to leave out is listed in its notes. It can be at most 25 MB. It runs on your own server with the VIABLE Engine, with the same page, limits and allowed sites. You ",{"id":1018,"title":1019,"lead":1020,"pages":1021},"connect","Connect an app","Run agents from your own software and your AI assistant.",[1022,1041,1072,1105,1128,1149,1174],{"path":1023,"title":1024,"description":1025,"updated":31,"minutes":256,"sections":1026},"connect\u002Ffirst-run","Your first run","Create an API key, run a published agent from your server for one of your users, and find that run in VIABLE.",[1027,1029,1033,1037],{"id":17,"title":17,"text":1028},"In fifteen minutes you create an API key, run a published agent from your own server for one of your users, and find that run in VIABLE with its learner and its trace. Start here when your app has its own sign-in and screens and uses VIABLE agents behind them. You need a VIABLE Developer account, a project, and a published agent in it. To make one, see Your first agent. For a first call to a model from your code, with no agent yet, the Developer quickstart takes five minutes.",{"id":1030,"title":1031,"text":1032},"create-a-key-and-find-the-agent","Create a key and find the agent","Create an API key. On Overview, choose Connect your app → Create an API key, or open Operate → API keys and choose Create key. Choose a service key. In a shared project, pick Service key: it belongs to the project and keeps working when members change. The owner creates these. Name it and keep its scope. Name it after the app and environment, such as \"Writing App · production\". Under Scopes, keep Run agents (agents:execute). Store the secret. Copy it from the dialog and store it on your server as VIABLE_API_KEY. Find the agent's address. Open the agent and choose Connect → API & keys. The endp",{"id":1034,"title":1035,"text":1036},"run-the-agent-for-one-user","Run the agent for one user","user is your app's ID for the person. The X-Platform-* headers name your app. The same call in Node.js 18 or newer: A successful run returns 200 with object: \"agent.run.result\", a conversation_id (agtc_…), a run_id (agtr_…), output, usage and cost. The reply is output.text. An error returns an error object with message, type and code. Branch on code. The key stays on your server. Never put it in browser JavaScript, an app bundle or a repository. Your web or mobile code calls your server, and only your server calls VIABLE.",{"id":1038,"title":1039,"text":1040},"see-the-run-in-viable","See the run in VIABLE","Open the run. Open the agent and choose Test → Run history. Your run is at the top, marked API · runs, with a learner code (L-…). Open it to see each step, what it received and returned, and every VETTING round. Meet the learner. Follow the learner code to Teach → Learners. The learner shows \"Known by My App (my-app:student-0001)\", and the turn carries your app's name. Find the request. In Operate → Request logs, open More filters and set Platform ID to my-app. You see the run and each model call inside it. Within seconds your app also appears under Build → Apps, with its checklist. Learners a",{"path":1042,"title":1043,"description":1044,"updated":421,"minutes":32,"sections":1045},"connect\u002Flearners-and-traces","Learners and traces","Name your app's users as learners, keep their conversations, and store a trace of what each run did.",[1046,1048,1052,1056,1060,1064,1068],{"id":17,"title":17,"text":1047},"Name the person behind each run so VIABLE keeps them as a learner, and record what each run did. Set this up before real people use your app.",{"id":1049,"title":1050,"text":1051},"name-your-users-with-user","Name your users with user","Send user on every run: a stable, opaque ID your server derives from the account it verified, up to 128 characters. Namespace it (my-app:7f3a9c21) or hash it. Never use a name, an email, a shared account or an unchecked ID. The first run with a new user creates a learner in the project, with a learner code (L-…). Later runs, on any agent in the project, add turns to it. Teach → Learners lists them with your app's name and your ID. Viewers see that ID too. Research → Export, with Your apps (API), exports their turns, and what you send as learning data. learners.csv carries your ID as external_i",{"id":1053,"title":1054,"text":1055},"label-task-groups-with-learner-group","Label task groups with learner_group","Send learner_group with user to label a turn's task group, such as \"Grade 8\". It is kept on the turn, never in the prompt. Teach → Learners → Group filters by it, and turns.csv includes it. It never changes a course section or study condition. Without user, it returns 400.",{"id":1057,"title":1058,"text":1059},"keep-the-conversation","Keep the conversation","By default VIABLE keeps the conversation. The first run returns a conversation_id. Store it per person, thread and agent, and send it with each new input. Never share one among people. Only the key that started it can continue it. To move a thread your app already has, seed it: send messages with two or more entries, the last from the user, and no conversation_id. The response carries the new conversation_id. To keep history yourself, send history_mode: \"client\" with the full messages.",{"id":1061,"title":1062,"text":1063},"ask-for-the-trace","Ask for the trace","Add \"include\": [\"trace\"] to \u002Fruns or \u002Fjobs. The result then has trace. duration_ms is wall-clock time. Don't add up steps: parallel branches overlap. steps[] lists each step's node_type, status, model, tokens, cost and error. vetting[] has one entry per VETTING step: outcome (passed, unverified, attention), attempts (more than one means a rewrite) and each round's verdict and feedback.",{"id":1065,"title":1066,"text":1067},"read-a-run-back","Read a run back","GET \u002Fv1\u002Fagents\u002F{slug}\u002Fruns\u002F{run_id}, with the key that made the run, returns it with its trace. Runs from another key, a course or a chat page return 404 run_not_found.",{"id":1069,"title":1070,"text":1071},"what-to-store","What to store","Keep one record per turn on your server: For failed requests, also keep the HTTP status, error.code and error.request_id. A trace holds what learners wrote. Keep it on your server, never in the learner's browser, and never show it to learners. Send learning data: add what learners do, write and score in your app. Background jobs and retries: retry a turn without running it twice. Export: download your app's turns for analysis.",{"path":1073,"title":1074,"description":1075,"updated":421,"minutes":32,"sections":1076},"connect\u002Flearning-data","Send learning data","Record what learners do in your app (events, drafts, ratings and scores) so it joins their learner record and the research export.",[1077,1079,1083,1085,1089,1093,1097,1101],{"id":17,"title":17,"text":1078},"VIABLE sees only your app's agent runs. Send the rest from your server: what learners did and wrote, how they rated replies and how they scored. It joins the learners your runs already name.",{"id":1080,"title":1081,"text":1082},"what-you-get","What you get","Insights in Build → Apps: active learners, time writing, pauses, pastes, drafts handed in, ratings and learner groups, day by day. A timeline per learner in Teach → Learners: their work in your app by activity, and their scores. The research export with your app's data (writing.csv measures how each draft was written), ready for Coding. To have your coding AI wire it up, paste this message in your app's code:",{"id":261,"title":262,"text":1084},"Give the key the scope. In Operate → API keys, choose Edit key on your app's key and turn on Record learning data (learning:write). Tag every call. Send X-Platform-ID, such as writing-app. Events and drafts are filed under your app's ID and the activity, so they need it. Reuse your user. The user you send on runs is the same learner here. A new user creates a learner.",{"id":1086,"title":1087,"text":1088},"send-events","Send events","POST \u002Fv1\u002Flearning\u002Fevents takes one learner's events in one activity, up to 200 per call. Use VIABLE's event kinds, such as writing.progress (keys, pastes, pauses, active time), writing.snapshot (the text at a pause), writing.submit and panel.view, or app.event for your own, with a flat data object. Each kind keeps only its own fields. The response lists any event it skipped, by index.",{"id":1090,"title":1091,"text":1092},"save-drafts","Save drafts","POST \u002Fv1\u002Flearning\u002Fdrafts saves the draft, and the plan if your app has one, as they are now: send the whole text each time. Add submit: true when the learner hands it in.",{"id":1094,"title":1095,"text":1096},"rate-replies","Rate replies","When a learner marks a reply helpful or not, send POST \u002Fv1\u002Fagents\u002F{slug}\u002Fruns\u002F{run_id}\u002Frating with rating set to 1, -1, or null to take it back. It uses Run agents and works only for runs this key made.",{"id":1098,"title":1099,"text":1100},"send-scores","Send scores","POST \u002Fv1\u002Flearning\u002Foutcomes records one measure, such as a rubric total, for up to 1,000 users. A user that no run, event or draft has named yet comes back in unmatched.",{"id":1102,"title":1103,"text":1104},"where-it-lands","Where it lands","Research → Export, with Your apps (API), or one app from its Insights: events in workspace_events.csv, drafts and how they were written in writing.csv, ratings in turns.csv, scores in outcomes.csv. A run with user also keeps its context as the turn's workspace. Build → Apps: the checklist marks each kind your app has sent, and Insights counts it. Consent is your app's to handle: tell learners what it records before you send anything. Keep user opaque, as on your runs: never a name or an email. Learners and traces: name your users and keep each run's trace. Export: download it all for analysis.",{"path":1106,"title":1107,"description":1108,"updated":63,"minutes":256,"sections":1109},"connect\u002Fjobs-and-retries","Background jobs and retries","Pick the right route for an agent call, run long work as a background job, and retry without running a turn twice.",[1110,1112,1116,1120,1124],{"id":17,"title":17,"text":1111},"This page is for developers who call an agent from their own server. Every published agent answers on three routes: pick the one that fits the work, and retry an unanswered request without running a turn twice.",{"id":1113,"title":1114,"text":1115},"choose-a-route","Choose a route","All three run the same agent and share keys, user and learner_group. \u002Fruns \u002Fjobs \u002Fchat\u002Fcompletions You send input, optional conversation_id The same, plus Idempotency-Key model (the slug) and messages You get The result, or a stream 202 and a job to poll choices[0].message.content Time 60 s, or the agent's 10–120 5 minutes or more As \u002Fruns In the dashboard API · runs API · background job API · chat completions Start with \u002Fruns when someone is waiting; \"stream\": true streams the reply. Use \u002Fjobs for long research, image generation, or a host that cuts requests short. For OpenAI-compatible SDKs,",{"id":1117,"title":1118,"text":1119},"run-a-background-job","Run a background job","The 202 has an id (agtj_…), a status_url and a Retry-After header. Wait that long between polls. queued or running: poll again. If the server restarts while running a turn, it picks the turn up again itself (or, for an agent that only calls models, runs it again once), so running may last a few seconds longer. Don't resend it. completed: result is the body \u002Fruns returns. failed: error has the code. To try again, submit a new job with a new key. A job not started within 15 minutes fails with agent_job_expired, and one that stopped before its reply was delivered with agent_job_interrupted: nothi",{"id":1121,"title":1122,"text":1123},"retry-safely","Retry safely","Send an Idempotency-Key with every turn: 8–128 letters, digits, dots, underscores, colons or hyphens. Save the route, body and key on your server. If no answer arrives, resend the same body to the same route with the same key. The run completed: you get the same result. Still going: 409 agent_request_pending. Retry later with the same key. The body differs: 409 idempotency_conflict. It started, then failed (such as provider_timeout): the key keeps that error. Retry with a new key. Rejected before it started (validation, 401, 403, 404, 413, rate or spending limits): nothing was recorded. Reuse ",{"id":1125,"title":1126,"text":1127},"limits-and-errors","Limits and errors","Size: 12 MiB per request, context up to 128 KiB, up to 400 messages. Rate: a key's per-minute limit covers all your users: thirty learners in one class share it. 429: wait for Retry-After. For token, cost or credit limits, don't retry in a loop. Branch on error.code, and never show an error as the agent's reply. The API reference lists every code. Learners and traces: keep each turn's run ID and trace. Keys, credit and costs: set a key's limits and see who pays.",{"path":1129,"title":1130,"description":1131,"updated":421,"minutes":32,"sections":1132},"connect\u002Fembed","Your page in an activity","Put your own web page inside a course activity, record what learners do in it, and let the AI beside it know.",[1133,1135,1139,1143,1145],{"id":17,"title":17,"text":1134},"Put your own page, such as a fractions game or a lab simulation, inside a course activity. An agent can sit beside it, and what learners do there goes into the research export. Courses are set up in the dashboard or with the CLI, not with API keys. Your page never learns who the learner is; VIABLE records its events with the learner.",{"id":1136,"title":1137,"text":1138},"set-up-the-activity","Set up the activity","Serve your page over https. Let https:\u002F\u002Fpage.viablelearning.org frame it, for example with Content-Security-Policy: frame-ancestors https:\u002F\u002Fpage.viablelearning.org. Add the panel. In Teach → Courses, open the course, add an activity, and add an Embedded page panel with your page's address. Choose what the agent is shown. If the activity has an agent, pick Its events, Nothing or Custom. Say how it ends. Turn on It says when the learner is done if your page reports completion. Otherwise learners press \"I'm done\". Serve the page from exactly that address: a redirect to another origin cuts the con",{"id":1140,"title":1141,"text":1142},"add-the-bridge","Add the bridge","Any page works as it is. To record what happens and tell the agent, add a few postMessage calls. The panel's Connect your page (optional) offers them to copy: session is a random ID for this visit. Ignore other origins. type What happens event Kept as an event: a verb and optionally object, score, max_score, success, completion, response, duration_ms and data. state What your page shows now, kept at most every 5 seconds. ask Puts text in the chat box for the learner to send. Nothing is sent for them. hello Asks for the hello again if your page started listening late. Prefer xAPI verbs: attempt",{"id":316,"title":317,"text":1144},"With Its events, when a learner asks while your panel is open, the step writing the reply sees your page's last ten events and its latest state. Custom sets 0–20 events and whether the state is included. The agent's Profile sets where this enters the prompt, and any step can read it as {{context.workspace}}. Learners are told on the panel what the agent sees.",{"id":1146,"title":1147,"text":1148},"what-gets-recorded","What gets recorded","Events and states are kept with the learner, course, activity and activity version, at every recording level. The research export has them in workspace_events.csv. When a study runs in the course, its consent and conditions apply as in any activity. Activities: build the activity around your page. Export: download the events with the course's data.",{"path":1150,"title":1151,"description":1152,"updated":421,"minutes":32,"sections":1153},"connect\u002Fapps","Build → Apps","See what each app's learners did, what it still needs, and connect any app with one message to your coding AI.",[1154,1156,1158,1162,1166,1170],{"id":17,"title":17,"text":1155},"Connect your app once and its learners get VIABLE's research tools. Check this page after your first run and before launch.",{"id":1080,"title":1081,"text":1157},"Insights: learners, sessions, AI use and ratings, writing, events and learner groups, day by day. A timeline per learner in Teach → Learners: runs, work and scores. The research export of your app's data alone, documented for R, Python or SPSS. Coding of what learners asked, by your team or a model. VETTING: a reviewer checks each reply against your rules. Studies, once your page runs in a course activity. Data your app sends alone is never in a study.",{"id":1159,"title":1160,"text":1161},"connect-it-with-your-coding-ai","Connect it with your coding AI","Paste the message below into Claude Code, Codex or any agent with a terminal, in your app's code. Review its changes. It installs the VIABLE CLI and Skill if missing, then wires your server to send user, X-Platform-ID, traces and learning data. Check it here. Your app appears with its checklist and Insights.",{"id":1163,"title":1164,"text":1165},"what-it-shows","What it shows","Build → Apps lists every app that sent requests or learning data with the project's keys in the last 90 days. There is nothing to register. An app is its X-Platform-ID. Untagged requests are grouped by key. Insights counts 30 or 90 days as the research export does; hover a measure for its definition. Download its data exports that app alone. Its requests opens Request logs filtered to the app. Chat pages, courses and the Playground aren't apps.",{"id":1167,"title":1168,"text":1169},"the-checklist","The checklist","A missing step links to its guide: Calls with a project key, Runs an agent, Names its users (user), Tags its requests (X-Platform-ID), Labels task groups (learner_group, if you need it), then the learning data rows of Send learning data.",{"id":1171,"title":1172,"text":1173},"tag-your-requests","Tag your requests","Send these optional headers from your server on every call. Choose them before launch: logs can't be re-tagged. Header Use it for X-Platform-ID A stable ID for your app, such as writing-app. X-Platform-Name Its readable name, such as Writing App. X-Operation-Type The feature, such as give-feedback, from a small, stable set. X-Request-ID Your own correlation ID, such as a session and turn. Values are cut at 240 characters (X-Request-ID at 200). Never put names or emails in them. Request logs filter by Platform ID, Operation and your request ID; the response's X-Request-ID is VIABLE's own, for s",{"path":1175,"title":1176,"description":1177,"updated":63,"minutes":445,"sections":1178},"connect\u002Fassistants","Connect your AI assistant","Add one address to your assistant to find standards and misconceptions and write teaching instructions. Add a key to check replies and run agents.",[1179,1181,1185,1189,1193,1197,1201],{"id":17,"title":17,"text":1180},"Ask the AI assistant you already use to find a standard, name the misconceptions that get in its way and write How the AI helps with you. It takes one address, with nothing to install and no key to get. This is an MCP server. To have your AI build courses and agents in VIABLE as you, use the CLI instead.",{"id":1182,"title":1183,"text":1184},"add-the-address","Add the address","Claude Code: Codex CLI: Cursor, in .cursor\u002Fmcp.json: VS Code, in .vscode\u002Fmcp.json: Another assistant that connects to MCP servers over HTTP takes the same address. Then ask it: Find the standard for adding fractions with unlike denominators and the misconceptions that get in its way. Then write teaching settings that ask first, and show me the instructions the AI would get.",{"id":1186,"title":1187,"text":1188},"what-it-can-do","What it can do","With no key: Find a standard. Search K-12 standards by words or code, and read one with its learning components (find_standards, get_standard). Find misconceptions. Math misconceptions from Eedi's graph, with the skills they hinder (find_misconceptions). Write teaching instructions. Turn teaching settings into the instructions a reply step gets (teaching_instructions). Search public goods. The catalog of open datasets, benchmarks and tools for K-12 AI (find_public_goods). Check a document. An agent file, a course package or teaching settings, against VIABLE's formats (validate_document). List ",{"id":1190,"title":1191,"text":1192},"add-a-key-for-the-rest","Add a key for the rest","Create a key. In Operate → API keys, choose Create key. Under Scopes, keep Model requests (model:request) to check replies and Run agents (agents:execute) to run agents. Set its limits. Give it a Monthly cost (USD) you're comfortable with. Your assistant decides how often to call these tools. Keep the secret out of the chat. Store it as VIABLE_API_KEY where your assistant starts, and send it as a bearer token. Claude Code: Codex CLI: Cursor, in .cursor\u002Fmcp.json: VS Code, in .vscode\u002Fmcp.json: Model calls are billed to the key's project like any other call to the API, and the key's scopes, allow",{"id":1194,"title":1195,"text":1196},"hosted-or-on-your-computer","Hosted or on your computer","The same tools also run on your own computer, as viable-harness mcp from the VIABLE Harness. Choose by where your data should go. Hosted On your computer Setting up An address Node.js 22 and the VIABLE Harness What you send Goes to VIABLE Stays on your computer, apart from what you send to your model endpoint Model calls VIABLE's, billed to your key Your own endpoint and key Standards Yes, through VIABLE's access No Misconceptions, public goods, teaching instructions, validation, components Yes Yes Check a reply With a key With your own endpoint Run an agent A published agent of your project A",{"id":1198,"title":1199,"text":1200},"what-viable-keeps","What VIABLE keeps","Request logs keep no tool's arguments or results. A log row holds the time, the status and how long it took, your address, your assistant's user agent and what Cloudflare reports about the connection, the request's headers with credentials removed, and the tool's name. With a key, also the key's prefix and project; for a call that used a model, its models, tokens and cost. A run of your agent is kept like any other. run_published_agent runs your agent the way the API does, so its message and reply are in the agent's Test → Run history. Send only what your project may keep. Nothing else is kept",{"id":1125,"title":1126,"text":1202},"What happens What it means What to do 429 from your address Without a key, one address may send 10,000 requests an hour. A key is held to its own limits, wherever it calls from Wait for Retry-After, or send a key 429 from your key The key's Requests per minute Wait for Retry-After, or raise the limit 413 Over 256 KiB without a key, or 1 MB of arguments with one Send a smaller document, or use the local server 401 The key is wrong, revoked or expired. A bad key never falls back to no key Fix the key, or remove it check_reply failed: it needs a VIABLE API key That tool needs a key Add a key This",{"id":1204,"title":1205,"lead":1206,"pages":1207},"project","Run a project","People, keys, costs and logs.",[1208,1232,1259,1290],{"path":1209,"title":1210,"description":1211,"updated":1212,"minutes":256,"sections":1213},"project\u002Fmembers-and-roles","Members and roles","Make a shared project, invite people in the right roles, and hand the project to a new owner.","2026-11-21",[1214,1216,1220,1224,1228],{"id":17,"title":17,"text":1215},"Decide who works in your project and what each person can do.",{"id":1217,"title":1218,"text":1219},"make-a-shared-project","Make a shared project","A project holds your team's agents, courses, studies, keys and logs. Open Account → Projects and choose New project. Name it, choose VIABLE credits or Bring your own key, then choose Create project. You become the owner. The project's Overview shows which models are billed to credits or to a provider key pool. Your personal project, shown with a lock, is private and can't be shared.",{"id":1221,"title":1222,"text":1223},"roles","Roles","Owner Editor Viewer See keys (no secrets), logs, usage, agents and members Yes Yes Yes See learners' names, student IDs and personal codes Yes Yes Codes only Change agents, courses, question sets and studies Yes Yes No Invite and manage members; manage shared provider keys Yes If the owner allows No Create service keys, transfer, archive; pays for usage Yes No No Set the project's budget and its emails Yes No (they see it) No (they see it) An editor can change every course in the project, not only their own. For a teacher who should run one course only, share that course instead. A research as",{"id":1225,"title":1226,"text":1227},"invite-people","Invite people","In the project's Members, choose Invite member. Type a name or email address, pick Viewer or Editor as the Role, and choose Invite member. Someone with an account gets access at once. Others show as Pending until they sign in with that email. Each member's … menu can pause or remove them. Removing a member, or making an editor a viewer, revokes their personal API keys, and pausing them stops those keys until they're back. The confirmation names the courses, chat pages and knowledge bases that run on those keys: to keep them running, make the key a service key first, or choose another key for e",{"id":1229,"title":1230,"text":1231},"transfer-ownership","Transfer ownership","Start the offer. Open Settings → Transfer ownership, or the member's … menu. Choose the new owner. Pick an active member who has signed in as the New owner. Send it. Read After they accept and choose Send offer. They have 7 days to accept under Review offer on the project's Overview. They see the project pools that will stay, then choose their VIABLE credits or a saved personal pool for other models. Until they accept, you stay the owner, keep paying, and can Cancel offer. When they accept, you become an editor. Every VIABLE API key moves to their account. New requests can use their credits an",{"path":1233,"title":1234,"description":1235,"updated":1212,"minutes":445,"sections":1236},"project\u002Fkeys-and-costs","Keys, credit and costs","Give each app, course and chat page a key paid the way you intend, and know who pays for every request.",[1237,1239,1243,1247,1251,1255],{"id":17,"title":17,"text":1238},"Give each piece of work its own key and set its limits. Requests use the project owner’s VIABLE credits or a provider pool available to that project.",{"id":1240,"title":1241,"text":1242},"api-keys","API keys","An API key, made in Operate → API keys, is how code calls VIABLE. A service key belongs to the project and keeps working when people leave. Only the owner makes one. Use it for apps, courses and chat pages. A personal key belongs to the member who made it. It stops if they are paused, leave or become a viewer. Choose Create key (editors see Create personal key), set its Scopes, Limits and Model access, and keep the secret on your server. Before someone leaves, the owner can choose Make service key on their key. Scopes: courses and chat pages need Run agents (agents:execute). Limits: Requests p",{"id":1244,"title":1245,"text":1246},"a-course-s-or-chat-page-s-key","A course's or chat page's key","A course: its Settings → The AI → The AI key: who pays for the course's AI. AI messages per learner per day can cap each learner. A chat page: the agent's Chat page → Key & limits → Runs on. Use a service key, one per course or chat page, so Usage shows what each costs. A whole class shares the course's key. A low daily token limit can stop the AI for all 30 learners mid-lesson.",{"id":1248,"title":1249,"text":1250},"provider-keys-and-key-pools","Provider keys and key pools","In New project, choose Bring your own key and pick Saved pool, Key I added, or Paste a key. Key I added copies your saved key into a pool for the new project. Each copy tracks its own usage and shares the same provider balance. Personal pool belongs to your account. You choose which projects you own can use it. Their members can see which pool pays in Project Overview. Project pool belongs to one project. Its owner and allowed editors manage it, and it stays with the project if ownership changes. Saved secrets stay hidden. When a pool has several keys, it can try the next key if one runs out o",{"id":1252,"title":1253,"text":1254},"credit-and-who-pays","Credit and who pays","Account → Billing → Credits shows one balance. Every project you own draws from it, whichever member's key made the request. Request Paid by A catalog model whose provider has a pool set to Every … model request That pool A catalog model with no such pool The owner's VIABLE credits A model called as @name\u002F\u003Cmodel> That pool A pool with no key available An error, or credits if the pool chose Use VIABLE credits The project's Overview shows the result under How this project is billed. A knowledge base's embedding is billed to the key its settings name in Billed to key: see Who pays for it. Costs a",{"id":1256,"title":1257,"text":1258},"the-project-s-budget","The project's budget","Without a budget, a project can spend up to its owner's whole credit, and a key's limits don't hold an editor back, since editors can change them. The budget caps how much of the owner's VIABLE credits the project uses. The owner sets it in the project's Settings → Budget: turn on Stop at a budget, enter the Amount (US dollars), and choose whether it Counts In all or Each month (a month is counted in UTC and starts again on the 1st). It counts what every key in the project spends in VIABLE credits, whoever made the key. Provider keys are their own pools: whoever added one pays for it and sets ",{"path":1260,"title":1261,"description":1262,"updated":500,"minutes":256,"sections":1263},"project\u002Flogs-and-usage","Request logs and usage","Find any request your project made, see the model calls inside an agent run, export logs, and track what it all costs.",[1264,1266,1270,1274,1278,1282,1286],{"id":17,"title":17,"text":1265},"Find a request, see what an agent run called, and track what your project spends. Use it when a learner reports a strange reply, or to plan a budget.",{"id":1267,"title":1268,"text":1269},"find-a-request","Find a request","Operate → Request logs keeps every API call in the current project: time, status, endpoint, model, key, tokens, cost, latency, and what was sent and returned. Logs aren't deleted on a schedule. Pick a range. Choose when it happened. Search. Type a VIABLE request ID, a run ID, or your app's X-Request-ID in Find a request, run, or client ID. Filter. Narrow by API key, Endpoint, Model, Status or Errors only. More filters adds Platform ID, Operation, Agent, and Playground or agent test requests. Open it. Choose a row to see the request and response.",{"id":1271,"title":1272,"text":1273},"a-run-s-model-calls","A run's model calls","An agent run is one row. Expand it to see each model call's step, model, status and share of the time, and choose a call for its details. Trace opens the run step by step.",{"id":1275,"title":1276,"text":1277},"a-knowledge-base-s-indexing","A knowledge base's indexing","Embedding a knowledge base's passages is one row per indexing run: Knowledge indexing and the knowledge base's name, with its model (Default model unless its settings chose another) and the key that paid. Open it to see how many documents and passages it embedded, which documents, and what it cost. The default model reports no tokens, so they are estimated from the text. The passages' text isn't kept in the log.",{"id":1279,"title":1280,"text":1281},"paid-by","Paid by","Once the project has key pools, Paid by filters to VIABLE credits, Any key pool, or one pool. The summary line then separates credit cost from requests on your keys.",{"id":1283,"title":1284,"text":1285},"export","Export","Set the filters. The export holds every request that matches, with its payloads. Start it. Choose Export, pick CSV or JSONL, and start it. Download it. It is prepared on the server, so you can leave the page. It stays under Recent exports for 24 hours. One export runs at a time. Viewers can export too. Request logs and their exports include what learners wrote to the AI, and every member can read them. A CLI log export can leave the text out with --no-bodies.",{"id":1287,"title":1288,"text":1289},"usage","Usage","Operate → Usage shows requests, errors, tokens and estimated cost for the current project. Set a Date range, from 7 days to All time or Custom. Filter by API key, Model and, with key pools, Paid by. Group by Day, API key, Model, Endpoint or Paid by. Choose a total at the top to chart it. In Breakdown, choose a row to filter the page, or Logs to see its requests. Filter to one key to see how much of each limit it has used. Who paid splits requests and cost between credits and each pool. For All time, or more than 5,000 requests, totals come from daily summaries, and the model and endpoint views",{"path":1291,"title":1292,"description":1293,"updated":63,"minutes":32,"sections":1294},"project\u002Fcli","The CLI and Agent Skills","Let your own AI work in VIABLE as you: build a course, set up a study or connect an app, with one message to set it up.",[1295,1297,1301,1305,1309],{"id":17,"title":17,"text":1296},"Your own AI can do VIABLE work for you: build a course, set up a study, connect an app. The VIABLE CLI (viable) acts as you, with your access, and its Agent Skill teaches your AI to use it safely.",{"id":1298,"title":1299,"text":1300},"let-your-ai-set-it-up","Let your AI set it up","Paste this one message into your AI: Where to paste it: If you don't code: Claude Cowork in the Claude desktop app, ChatGPT Work in the ChatGPT app, or Gemini with Task chosen under the prompt box. Start a new task and paste the message. If you build software: Claude Code, Codex, Google Antigravity, or any agent with a terminal. It installs the CLI and the Skill. The guide tells your AI what to install where it works, and how to check it. You approve the sign-in. It shows you a link and a code; you approve in your own browser. It never sees your password. Then ask in your own words. The Skill ",{"id":1302,"title":1303,"text":1304},"what-to-ask-it","What to ask it","You Ask, for example Teacher \"Make a course for Period 2 with a writing activity and a tutor that gives hints only, then send me the preview link.\" Researcher \"Set up an observational study on that course with consent, and upload our approved consent form.\" App developer \"Connect our server to VIABLE: name each user, tag our requests, send learning data, then check Build → Apps.\" Owner \"Show last week's cost by key and model.\" It can't do more than your role allows, since VIABLE checks every request. Every change needs an exact --confirm value, and the Skill tells your agent to show you what w",{"id":1306,"title":1307,"text":1308},"install-it-yourself","Install it yourself","Prefer the terminal? You need Node.js 22 or newer. On a remote machine or a cloud agent, sign in with viable auth login --device. viable agent install --target \u003Cassistant> installs the Skill into a coding assistant such as Codex or Claude Code. viable help lists the commands. viable doctor checks the setup, and viable update --with-skill keeps both current. Signing in never creates an account: register at https:\u002F\u002Fdevelopers.viablelab.org first. Resources → CLI & Agent Skills has the same steps.",{"id":1310,"title":1311,"text":1312},"agents-and-these-docs","Agents and these docs","The Skill reads the API guide for current routes, fields and errors. Any agent can start from llms.txt, which lists every page here as Markdown. The CLI and its Skill are MIT licensed. Members and roles: what your role lets your AI do. Send learning data: connect an app, or let your AI do it. Your first class: what your AI builds, step by step.",{"id":1314,"title":1315,"lead":1316,"pages":1317,"groups":2072},"harness","VIABLE Harness","What a good teacher has in mind, around the AI that teaches. What a classroom needs, around the AI that builds.",[1318,1349,1389,1421,1487,1535,1582,1614,1665,1712,1776,1799,1834,1873,1955,2006,2031],{"path":1319,"title":1315,"description":1320,"updated":1321,"minutes":868,"sections":1322},"harness\u002Foverview","Give any AI agent what a good teacher has in mind, before it replies.","2026-11-11",[1323,1325,1329,1333,1337,1341,1345],{"id":17,"title":17,"text":1324},"Building a tool for learners with a coding agent instead? That's the other side of the Harness: what the AI that builds needs to know about a classroom. In the field's terms, a harness is everything around a model that decides what it knows, what it may do, when it stops and whether the result is any good. General harnesses are tuned for writing code. This one is tuned for teaching, and it goes around the agent you already have. A learner writes \"i got 2\u002F5\" for 1\u002F2 + 1\u002F3. Before your model sees it, the Harness adds: The move and the misconception are chosen for this message, and everything els",{"id":1326,"title":1327,"text":1328},"four-ways-in","Four ways in","Your assistant, with nothing to install. A Skill teaches an assistant the moves, and MCP gives it the tools: Any app, in any language, by changing one URL. Each call gets what its moment needs, each reply is checked before your app sees it, and a record feeds the teacher's page. Nothing else changes: Recipes for curl, Python, Node, LangChain, LangGraph, LlamaIndex, the OpenAI Agents SDK and the Vercel AI SDK, each one run as written. Your own code, with three calls around whatever writes the reply: Another harness. If yours can add to the system prompt before a turn, call prepare there and che",{"id":1330,"title":1331,"text":1332},"what-it-does","What it does","When Part The question How Before the reply Context What should it have in mind at this moment, and nothing more? what the teacher decided (How the AI helps); standards and misconceptions from open resources; teaching moves, each with its source; what this learner just did Before the reply Rules What may it see and do here? how far it may help; which tools are off, removed rather than only told; no learner's identity; answer keys that reach only the reviewer While it works Loop What happens next? counts tries, changes approach when a learner keeps failing, brings in the teacher and flags it; w",{"id":1334,"title":1335,"text":1336},"not-only-replies","Not only replies","Each kind of teaching work is a task, prepared the same way. For a task that isn't a conversation, turn.messages is the whole request, and runTask sends it and checks the answer: Task What it does tutoring A reply to a learner, as above adapt-plan Summarizes a class's evidence against the teacher's goal, and suggests changes with the evidence beside each differentiate Sorts learners into groups by what their records show, for the teacher to confirm, and suggests each group's help level and note hard-moments Adds the strategy a teacher chose for when learners struggle, and gathers flagged momen",{"id":1338,"title":1339,"text":1340},"how-much-does-it-help","How much does it help?","A teacher's policy holds better when code decides its steps. On 60 test conversations with three reply models, a tutor built from a carefully written prompt and a guardrail that knows the policy did the step the policy required on 57 to 73 turns in 100. With the Harness deciding the step in code it was 83 to 89, and no reply it delivered stated the answer. With every model in the tutor open-weight, as in a school that runs its own servers, it was 74 and 75 against 48 and 45 on 60 new conversations (the policy check). Experiment 1. Share of turns on which each tutor did the step the teacher's p",{"id":1342,"title":1343,"text":1344},"where-its-knowledge-comes-from","Where its knowledge comes from","Learning Commons and Eedi keep the shelves: standards, learning components, misconceptions, evaluators. If you want lookups in your assistant, use their MCP server. The Harness decides at each moment what to take from them, credits them, and measures whether it helped. It carries their open data under CC BY 4.0, with the attribution to keep (NOTICE).",{"id":1346,"title":1347,"text":1348},"reference","Reference","How it works · A teaching policy in code · With your stack · MCP · Skills · Agent tests · Scorecard · Ways to arrange an activity · Add your research · Components · Open resources · Catalog · xAPI · Conformance This page comes from the open repository: harness\u002FREADME.md. To change it, change it there.",{"path":1350,"title":1351,"description":1352,"updated":63,"minutes":1353,"sections":1354},"harness\u002Fhow-it-works","How the Harness works","What the Harness does with each learner message, where the teaching knowledge it draws on is kept, and why it needs no search index.",9,[1355,1357,1361,1365,1369,1373,1377,1381,1385],{"id":17,"title":17,"text":1356},"The Harness is about 10,000 lines of JavaScript with no dependencies, and two compact data files. It has no server, no index and no model of its own, and it keeps nothing unless you ask. It can be that small because it doesn't search everything on every turn: a person narrows things down first, and each turn only chooses from what is left.",{"id":1358,"title":1359,"text":1360},"one-turn","One turn","A learner writes \"i got 2\u002F5\". What the teacher decided is already a short list: a goal, how much the AI does, perhaps a standard, a few misconceptions and some guidance from research. Where they chose none of those last two, the Harness chooses them (src\u002Fdefaults.js): the common misconceptions of the math idea the goal names, and research that suits how much the AI does, the same for the same goal and level. The moment is read: giving an answer, asking for the answer, stuck, or trying again. The list is cut down to this moment: one teaching move, and at most two of each other kind. Instruction",{"id":1362,"title":1363,"text":1364},"two-stages-which-is-why-there-is-no-vector-store","Two stages, which is why there is no vector store","Stage Who From To When Choosing for an activity A teacher, or an assistant working with one Every state's standards, 8,117 misconceptions, 77 pieces of guidance and whatever others publish One standard, up to 8 misconceptions, up to 20 pieces of guidance, kept in the activity Once, before class Choosing for a turn Rules, or a small model That short list One move, and at most 2 of each kind Every message What is chosen for an activity is kept as it was, with where it came from. A run never waits on a far-off service, and a record can say exactly what the AI was given.",{"id":1366,"title":1367,"text":1368},"the-pool","The pool","What How much Where it lives Who narrows it What reaches the model What the teacher decided One activity's settings Your file, or the activity on the Engine or the VIABLE Developer Platform The teacher The goal and the limit, every turn Teaching moves 4, with their sources In the code, src\u002Fbrief.js The moment One Misconceptions (Eedi) 8,117, under 2,258 skills, 1.2 MB In the package The teacher ticks up to 8, or words search the skills At most 2 Durable skills (Carnegie) 60 KB In the package The teacher picks one Its level Standards (Learning Commons) About 1 GB for every state Not in the pack",{"id":1370,"title":1371,"text":1372},"how-a-turn-chooses","How a turn chooses","By rules, with no model call and no cost. Patterns read the moment: in English, and the commonest ways of asking and of being stuck in Spanish and Chinese. Whatever a learner says back to a tutor who left them something to do is an answer, unless it is a question, a plea, being stuck or small talk; where the activity has a problem on the page, so is a first message. A list item is taken when it shares at least two words with what was just said, the closest first; a learner's everyday words count as the formal ones a misconception uses (\"tops and bottoms\" as numerators and denominators, \"times\"",{"id":1374,"title":1375,"text":1376},"keywords-embeddings-and-rag","Keywords, embeddings and RAG","The Harness does no retrieval over documents. A list of a dozen items needs no index, and everything above it was narrowed by a person. Retrieval is for your own documents, such as a library's guides, and belongs to whatever holds them: Where Keywords By meaning Reranked Where the vectors are The Engine's knowledge BM25 Once a model for it is set in the console No In its own store, made the first time a file is searched, and kept The VIABLE Developer Platform's knowledge BM25 Yes Yes In a vector index on the platform The Harness No No No None A person's memory (memory.js) Words, in any languag",{"id":1378,"title":1379,"text":1380},"skills-mcp-and-the-gateway","Skills, MCP and the gateway","All of them reach the same code. What differs is what runs where, and whether it's guaranteed to run. Way in What it is What runs, and where Where the data is Guarantees it runs Skills Text files an assistant reads Nothing runs: the assistant follows them, or doesn't None No MCP, local viable-harness mcp, started by your assistant This code, on your computer In the package, and what you fetched No: the assistant chooses to call it MCP, hosted https:\u002F\u002Fapi.viablelab.org\u002Fmcp This code, on VIABLE's servers, which also reach Learning Commons On VIABLE's servers. No log keeps a tool's arguments No: ",{"id":1382,"title":1383,"text":1384},"where-the-engine-and-the-viable-developer-platform-use-it","Where the Engine and the VIABLE Developer Platform use it","Neither has a copy: they import these same files, so a change here reaches all three. Part of the Harness The Engine The VIABLE Developer Platform Teaching settings, in How the AI helps Yes Yes The turn's brief, the instructions chosen for each turn On by default A choice in How the AI helps, off by default, read by rules VETTING's prompts and rounds Its VETTING step Its VETTING step and \u002Fv1\u002Fvetting\u002F* Misconceptions and durable skills Choosing them for an activity Choosing them for an activity Measures Records The research export Suggested changes Progress Progress Formats, agent tests' verdic",{"id":1386,"title":1387,"text":1388},"why-it-is-this-small","Why it is this small","It lends nothing out and keeps nothing: a host passes in fetch, a model and a store. It has no dependencies, so what you install is what you see: 0.8 MB packed. It holds decisions, not knowledge: the data it carries is small and compact, and what is large stays with its makers until someone asks for it. This page comes from the open repository: harness\u002Fdocs\u002Fhow-it-works.md. To change it, change it there.",{"path":1390,"title":1391,"description":1392,"updated":1321,"minutes":1393,"sections":1394},"harness\u002Ffor-builders","Building for learners","Teachers and researchers now build classroom tools by describing them to a coding agent, which writes the code without seeing the room.",7,[1395,1397,1401,1405,1409,1413,1417],{"id":17,"title":17,"text":1396},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. The room is thirty children opening this at 9:05 from one school address, a shared Chromebook, a quiz whose answers are one View Source away, a tutor that does the homework, a key the class can spend. The rest of the Harness goes around the AI that teaches, at each reply. This part goes around the AI that builds, while a tool is being made. They share a shelf of standards, misconceptions, research and tests, and nothing else: a coding agent is never told \"don't give the answer\", an",{"id":1398,"title":1399,"text":1400},"use-it","Use it","With a coding agent such as Claude Code, Codex or Cursor: Then ask for what you want as you normally would. It asks who the learners are first, and builds the least that does the job. It adds a few lines to the project's AGENTS.md too, since agents can skip a Skill they aren't reminded of. With a chatbot such as ChatGPT or Gemini, where you can't install anything, paste this at the start: On a project you already have, a coding agent's or your own:",{"id":1402,"title":1403,"text":1404},"what-review-looks-for","What review looks for","It reads text with patterns, with no model and nothing leaving the computer, and says where to look and what to do. It exits 1 when something should be fixed before learners use it. Fix before learners use it Why A secret key written into the code A key goes wherever the code goes A model called from the page itself Anyone in the class can read how, and spend without end A database anyone can read or write Anyone with the page's address can read every learner's work A .env file git isn't told to ignore The keys in it go into the repository with the next commit A server handing out its whole fo",{"id":1406,"title":1407,"text":1408},"test-its-tutor","Test its tutor","If the tool has an AI that replies to learners, copy tutor-tests.json into your project, change the question and answer to the tool's own subject, then run it on what the AI is told, against any OpenAI-compatible model. It makes 28 model calls, a reply and a judgment for each case: Its 14 cases cover what you'd worry about in a new colleague: asking for the answer outright, again after a hint and with \"my teacher said you can\"; a wrong answer given with confidence, and a right one; being stuck; a learner who may not be safe; a request that isn't; personal details; \"are you a real person?\"; wan",{"id":1410,"title":1411,"text":1412},"with-viable-s-services-or-without","With VIABLE's services, or without","None of this needs an account with us. The Skill points to what fits, with what each leaves to you: You want Use You still do A class with an AI tutor, and no page of your own The VIABLE Learning Platform Nothing to build Your own page, with someone else minding keys, limits and traffic The VIABLE API as your model endpoint: a key per class, each with its own requests per minute, daily tokens and monthly cost, and usage to look at A small server that holds the key Your own page and your own model account Your own server, and the patterns in the Skill's classroom notes All of it Everything on y",{"id":1414,"title":1415,"text":1416},"what-it-can-t-do","What it can't do","It shapes what gets written and nothing after. In class, someone still holds the key, watches the budget, reads what happened and answers for it: a hosted platform can do that, and a Skill can't. It isn't legal advice, and it can't say a tool complies with anything. The notes on learners' data link to the sources and list what a school will ask. Whether it improves the tools people build has not been measured. The patterns in review come from classroom experience and services' documented defaults. An agent may skip a Skill even with the reminder in AGENTS.md, so review is a command you can run",{"id":1418,"title":1419,"text":1420},"how-it-differs-from-other-skills-for-teachers","How it differs from other Skills for teachers","Most Skills for education help with a teacher's own work: lesson plans, rubrics, differentiation. This one does none of that. Standards and misconception data are well served already, by Learning Commons among others, and this points to them. This one treats a class as the unit of load and budget, says what not to build, and gives tests you can run on a small tool's tutor. This page comes from the open repository: harness\u002Fdocs\u002Ffor-builders.md. To change it, change it there.",{"path":1422,"title":1423,"description":1424,"updated":1321,"minutes":1353,"sections":1425},"harness\u002Fwith-your-stack","With your stack","If you already have an AI app or an agent, in any language or framework, there are two ways in that leave it as it is:",[1426,1428,1432,1436,1440,1444,1448,1452,1456,1460,1464,1467,1471,1475,1479,1483],{"id":17,"title":17,"text":1427},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. Change one URL. The gateway stands in front of your model endpoint. Each call gets what its moment needs from a teacher's settings, each reply is checked before your app sees it, and a record is kept for the teacher's page. Call it yourself. prepare before your model, check and record after it, and agent tests in CI (viable-harness test --endpoint). What goes in is chosen for each message: the teacher's goal and limit always, the teaching move for what the learner is doing, and onl",{"id":1429,"title":1430,"text":1431},"change-one-url","Change one URL","Write the teacher's settings (fractions.json). teaching is How the AI helps; a plain teaching settings file, or a course package, works as well. Start the gateway in front of your endpoint. Name the reviewer: it turns the check on. It says what it will do, then gives you the line to change: Then call it as you call any OpenAI-compatible endpoint. Ran:",{"id":1433,"title":1434,"text":1435},"what-comes-back","What comes back","Your endpoint's answer, with the reply it may have changed, and what the check did in X-Viable-* headers and a viable field. In a stream the field is on the chunk with the finish_reason. Header Field Says X-Viable-Outcome outcome passed, unverified, attention or not_checked. Only passed is checked (checked: true) X-Viable-Delivered delivered reply (as your model wrote it), rewrite, fallback, or tool_calls_only (failed text was dropped from beside a tool call) X-Viable-Why why Why it isn't passed: checks_off, tool_calls, structured_output, no_text, upstream_error, or the review's stop reason su",{"id":1437,"title":1438,"text":1439},"streaming","Streaming","With checks on, the reply is held until it passes, then sent as a normal stream, so a failed draft never reaches a learner. The first word arrives after the whole reply and its review. With checks off, the stream passes through as it comes, and the headers are all that report on it.",{"id":1441,"title":1442,"text":1443},"tool-calls","Tool calls","They go back to your app unchecked, and the text that comes after them is checked. Text beside a tool call is checked too; if it fails, the tool call goes on without it.",{"id":1445,"title":1446,"text":1447},"which-activity-which-learner","Which activity, which learner","Header Does Without it X-Viable-Activity Picks the settings from --activities \u003Cdir>: one \u003Cactivity>.json per activity, and a package's activities by their titles (the gateway lists the names when it starts). Unknown names are refused With --activities, the call is refused. With --teaching, every call gets those settings X-Viable-Learner Names the learner in the records. A pseudonymous ID: letters, digits, dots, dashes, underscores, colons. A name or an email is refused The request's user if it fits that rule, else the call is kept with no learner X-Viable-Section Applies that section's own hel",{"id":1449,"title":1450,"text":1451},"keys-and-tokens","Keys and tokens","You start it with Your app sends The endpoint gets OPENAI_API_KEY set (or --api-key-env NAME) Any API key: it isn't used The gateway's key That variable not set Its own key The app's key --token-env NAME and a key The token as its API key, or as X-Viable-Token The gateway's key --token-env NAME and no key Its own key, and the token as X-Viable-Token The app's key Without a token the gateway answers this computer only: --host refuses anything else, and it refuses another name in Host, a proxy that says it passed the request on, and a post with another site's Origin. A token holds on localhost t",{"id":1453,"title":1454,"text":1455},"the-teacher-s-page","The teacher's page","Open \u002Fteacher. Your browser asks for a password: it's the token, or with no token the one the gateway printed when it started, and any user name will do. It always asks, because through a local proxy every visitor would look like this computer. With several activities it asks which. Or from the folder: With --activities, read one activity's at a time: .\u002Frecords\u002Fgateway\u002F\u003Cactivity>. The page shows How the AI helps, what the check did with each reply, each learner's measures and suggested changes. Anyone with the token can read it. Records hold no text from the learner or the AI unless you start ",{"id":1457,"title":1458,"text":1459},"on-any-cloud","On any cloud","gatewayHandler(options) from src\u002Fgateway.js returns (Request) => Response and imports nothing from Node. A store is four functions (get, put, delete, list). Ran locally in wrangler dev 4.148.0 (not deployed), with a KV namespace bound as RECORDS: KV's list returns 1,000 keys at a time, so page through it once an activity has more.",{"id":1461,"title":1462,"text":1463},"your-client-or-framework","Your client or framework","Each of these points at the gateway and sends the two headers. Each ran, with a held reply and a rewrite. OpenAI Python (openai 3.44.0, streaming and tool calls too): OpenAI Node (openai 7.49.0, streaming too): LangChain (langchain-openai 1.7.3, invoke and stream). LangGraph (langgraph 1.2.19) takes this llm in a node as it is: OpenAI Agents SDK (openai-agents 0.24.0). It uses \u002Fv1\u002Fresponses by default, which the gateway refuses, so name the chat completions model. Its tracing sends runs to OpenAI unless you turn it off: Vercel AI SDK (ai 7.0.162, @ai-sdk\u002Fopenai 4.0.108, generateText and stream",{"id":1465,"title":1466,"text":17},"the-parts","The parts",{"id":1468,"title":1469,"text":1470},"a-check-as-a-guardrail","A check as a guardrail","From JavaScript. Ran: From any language, over the gateway. Ran from Python with no dependency: \u002Fv1\u002Fcheck takes reply, message, history, guideline, reference, question, answer_key, key_concepts, explanation, instructions, teaching, section, rewrite, model and reviewer. The reviewer defaults to the gateway's. It keeps no record.",{"id":1472,"title":1473,"text":1474},"instructions-from-how-the-ai-helps","Instructions from How the AI helps","Add them after your reply model's own instructions. Keep watch_for for the teacher: never send it to a model. Ran: In JavaScript: teachingContext(settings, section)?.text. Without teaching, the route uses the activity in X-Viable-Activity, or the gateway's only one.",{"id":1476,"title":1477,"text":1478},"misconceptions","Misconceptions","Eedi's Misconceptions Graph, from the harness's own copy: math only, no model, no network beyond the gateway. Keep source.attribution with anything you copy (CC BY 4.0). Ran: These routes, like everything on the gateway but \u002Fhealth, need the token when it has one.",{"id":1480,"title":1481,"text":1482},"agent-tests-in-ci","Agent tests in CI","viable-engine test exits non-zero when a case fails or can't run, so the step fails with it. Ran, with a passing case, a failing one and an endpoint that's down. It runs a VIABLE agent file, so to test your prompt with a teacher's settings, put it in a one-step file (tutor.agent.json): Cases (cases.json) say what a good reply does; agent-tests.md has the rest: --teaching takes a plain teaching settings file. Point this at your model endpoint (OPENAI_BASE_URL), not at the gateway: the judge's own verdicts shouldn't be checked. To test a prompt alone, with no agent file (add --teaching fractions",{"id":1484,"title":1485,"text":1486},"what-the-gateway-can-t-do","What the gateway can't do","It sees only what passes through it. An app can call the model some other way, and nothing here can stop steps the app does elsewhere. A review is one model's judgment, so a reply that passed can still be wrong or unsafe. It checks text to the learner. Tool call arguments aren't checked. Structured output (response_format of json_object or json_schema) passes through as not_checked, because a rewrite or a fallback would break your code. The reviewer and rewrites read text only. Pictures in a message don't reach them, nor do tool results. A rewrite gets your system message, the conversation and",{"path":1488,"title":1489,"description":1490,"updated":1321,"minutes":1491,"sections":1492},"harness\u002Fmcp","The MCP server","The Harness's parts are MCP tools, for an assistant, a harness of your own or an app on another agent SDK.",13,[1493,1495,1499,1503,1507,1511,1515,1519,1523,1527,1531],{"id":17,"title":17,"text":1494},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. With them it can prepare what a moment of teaching needs, check replies with VETTING, find misconceptions, compute the measures and test agents without adopting anything else. A tool is advice an assistant may ignore; the gateway or your own calls make it run. There are two ways to reach them.",{"id":1496,"title":1497,"text":1498},"hosted-or-local","Hosted or local","Hosted, https:\u002F\u002Fapi.viablelab.org\u002Fmcp Local, viable-harness mcp Setting up An address Node.js 22 and the Harness; your assistant starts it What you send Goes to VIABLE Stays on your computer, apart from what you send to your model endpoint Model calls VIABLE's model services, billed to your key Your own endpoint and key Standards find_standards, get_standard, through VIABLE's Learning Commons access Not here: they need Learning Commons' key prepare_task, find_misconceptions, find_guidance, find_designs, teaching_instructions, find_public_goods, validate_document, list_components Yes, with no k",{"id":1500,"title":1501,"text":1502},"the-hosted-server","The hosted server","Nothing to install. Add the address to your assistant: For the rest, send a VIABLE API key as a bearer token; Connect your AI assistant has the settings per client. Tier Auth Tools Limits Open none find_standards, get_standard, find_misconceptions, find_guidance, find_designs, teaching_instructions, find_public_goods, validate_document, list_components. No model calls the API's limit per address (10,000 requests an hour, shared with whatever else that address sends), 256 KiB a request Project a VIABLE API key the open tier, plus check_reply, list_published_agents and run_published_agent, bille",{"id":1504,"title":1505,"text":1506},"the-local-server","The local server","viable-harness mcp speaks stdio: newline-delimited JSON-RPC 2.0, protocol version 2025-06-18 (or 2025-03-26 and 2024-11-05, when a client asks for one of those). stdout carries only protocol messages; logs go to stderr.",{"id":1508,"title":1509,"text":1510},"the-tools","The tools","Tool What it does Calls a model check_reply Reviews one reply with VETTING against a guideline, or a question's answer key, and the activity's teaching settings; with rewrite, rewrites a failed reply and reviews it again. A reply is checked only when outcome is passed. yes: reviewer (else model), and model for rewrites prepare_task What a model should have in mind before a piece of teaching work: for tutoring, from the teacher's settings and the learner's message, the moment, its move and only what the message calls for; adapt-plan, differentiate, hard-moments and goals take records or a goal.",{"id":1512,"title":1513,"text":1514},"where-the-local-server-runs","Where the local server runs","On your own computer. You don't run it yourself: your assistant starts viable-harness mcp as a child process when it starts, talks to it over that process's stdin and stdout, and stops it when it quits. That's why setting it up means telling the assistant the command, not an address. Tools that call a model reach the endpoint in the server's environment (OPENAI_API_KEY, OPENAI_BASE_URL); everything else (validating a file, writing How the AI helps, finding misconceptions, the measures, the catalog, the components) needs no key and nothing from the network. viable-harness mcp serves 13 of the t",{"id":1516,"title":1517,"text":1518},"configuring-a-client-for-the-local-server","Configuring a client for the local server","Every client needs the same three things: the command node, the arguments [\"\u002Fpath\u002Fto\u002Fviable\u002Fharness\u002Fbin\u002Fviable-harness.mjs\", \"mcp\"] (or the command viable-harness and [\"mcp\"] after npm link), and the environment for model calls. Claude Desktop (claude_desktop_config.json) and Cursor (.cursor\u002Fmcp.json): VS Code (.vscode\u002Fmcp.json): Codex CLI: Claude Code: With an open-weight model, set OPENAI_BASE_URL to its endpoint (for example http:\u002F\u002Flocalhost:11434\u002Fv1 for Ollama) and name its models in each call. An agent SDK with an MCP client starts the same command over stdio. A host that only connects to",{"id":1520,"title":1521,"text":1522},"views-in-assistants-that-show-mcp-apps","Views in assistants that show MCP Apps","In a host that renders MCP Apps (the io.modelcontextprotocol\u002Fui extension, specification 2026-01-26), three tools' results also show as a small page in the conversation: Tool View What it shows check_reply ui:\u002F\u002Fviable-harness\u002Fcheck-reply The outcome and whether the reply is checked; the learner's message and the guideline, or the question (never its answer key), it was checked against; each review round with its verdict and the reviewer's reason; the rewritten reply. run_agent_tests ui:\u002F\u002Fviable-harness\u002Fagent-tests How many cases passed, failed and couldn't be run or judged; each case, the fail",{"id":1524,"title":1525,"text":1526},"limits","Limits","A call's arguments are at most 1 MB as JSON; longer texts have their own limits in each tool's schema (a reply 20,000 characters, a message 8,000, a conversation 50 messages), and agent tests take 1 to 25 cases. A call over a limit gets an error result naming it.",{"id":1528,"title":1529,"text":1530},"what-the-server-guarantees-and-what-it-doesn-t","What the server guarantees, and what it doesn't","The host decides whether a check runs. Nothing makes an assistant call check_reply before showing a reply, and the server never sees a reply it isn't given. A reply counts as checked only when outcome is passed; unverified and attention replies are not. The host decides what is kept. The server reads and writes no files for a call and keeps nothing between calls: documents and records arrive as arguments, and results go back to the host, which keeps or drops them. Only the reference harness guarantees that VETTING runs and that the trace is kept. An agent run by the harness (viable-engine run,",{"id":1532,"title":1533,"text":1534},"the-protocol","The protocol","initialize, notifications\u002Finitialized, ping, tools\u002Flist and tools\u002Fcall; for a client that renders views, also resources\u002Flist, resources\u002Ftemplates\u002Flist (empty) and resources\u002Fread (an unknown view gets -32002). Other methods get -32601; a malformed message -32700 or -32600; an unknown tool or arguments that aren't an object -32602. Arguments that don't fit a tool's schema, or a tool that fails, come back as a result with isError: true and a message saying what to change, so the assistant can act on it. Batches and cancellation aren't supported; each message is handled as it arrives, so a ping is",{"path":1536,"title":968,"description":1537,"updated":1321,"minutes":1538,"sections":1539},"harness\u002Fagent-tests","An agent test is a case written from what a teacher or builder wants: a learner's message, what a good reply does, and what it must not do.",12,[1540,1542,1546,1550,1554,1558,1562,1566,1570,1574,1578],{"id":17,"title":17,"text":1541},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. The message can be a short conversation. Each case runs through the agent, and a judge model rates the reply pass or fail with a reason. Your agent is whatever you have: viable-harness test cases.json --endpoint \u003Curl> --endpoint-model \u003Cid> --judge-model \u003Cid> tests what's behind any OpenAI-compatible endpoint, and viable-engine test agent.json cases.json --judge-model \u003Cid> an agent file. Cases are run again after every change to the agent or to How the AI helps, so a change that mak",{"id":1543,"title":1544,"text":1545},"the-case-format","The case format","A file of cases (format viable.agent-tests), or a bare list of cases: Field Limit name required 120 characters message, or messages required: the learner's message, or a conversation of {\"role\": \"user\" | \"assistant\", \"content\": \"...\"} ending with the learner's 12 messages of 4,000 characters each rubric required: what a good reply does 2,000 characters must_not what the reply must not do 1,000 characters context the run's reference data, such as the open question and its answer key; the judge sees it too 32 KB pictures pictures the conversation has already shown, {\"url\": \"https:\u002F\u002F...\", \"descri",{"id":1547,"title":1548,"text":1549},"writing-good-cases","Writing good cases","Read the activity's teaching settings first (the teaching_instructions MCP tool shows what the agent is told). Then write a case for each thing a teacher worries about: The ordinary request: what most learners will send. The rubric says what a good reply does at the activity's help level. Asking for the answer: outright, again after a hint (a messages conversation), and with pressure (\"my teacher said you can\"). A real attempt showing a misconception the activity listens for, and whether the reply notices it without giving the answer. A section's own help level: for learners in a section with ",{"id":1551,"title":1552,"text":1553},"drafting-cases-from-how-the-ai-helps","Drafting cases from How the AI helps","From code, draftCases(teaching, { model, count, section, baseUrl, apiKey, fetch }), or with your own model call as callChatModel; over MCP, the draft_tests tool. A package supplies its first activity's teaching settings. The drafting model gets what the reply steps are told (teachingContext: the goal, the standard or skill, the misconceptions, the help level and, with --section, that section's own level and note), and is asked for count cases (1 to 25, default 8) covering, one case each and in this order: ordinary, asks_for_answer, misconception (when the activity lists misconceptions), sectio",{"id":1555,"title":1556,"text":1557},"reviewing-drafted-cases","Reviewing drafted cases","Drafts are a model's guesses at what the teacher means. A person reads each one before it is run: Is the learner's message something a learner in this activity would send? Edit it to sound like them. Does the rubric hold the AI to the help level the teacher chose, no more and no less? Is must_not precise enough that a judge can tell, from the reply alone? For a misconception case: does the attempt show the misconception, and only that one? For distress and unsafe cases: is the rubric what your school would want a reply to do? Add your school's own instructions, such as whom to tell. Delete cas",{"id":1559,"title":1560,"text":1561},"cases-from-past-turns","Cases from past turns","From code, casesFromTurns(records, teaching, { limit }). Records are learners' records in the learning events format (schemas\u002Flearning-events.schema.json, { user, events, turns }), a record or a list of them per file. No model is involved, so the same records always give the same cases. From each learner's turns, in time order, it takes: Kind A turn not_passed whose reply VETTING didn't pass, when the turn says so (vetting other than passed, as the research export's turns carry it) after_wrong_answer whose learner's latest graded answer since their previous message was wrong: a questions.answe",{"id":1563,"title":1564,"text":1565},"learners-words-and-consent","Learners' words and consent","These cases hold what learners wrote. The harness reads records only from the files or arguments you give it, refuses a record whose user looks like an email address, and puts learner text only into the cases. Reusing learners' messages as test cases needs consent (from learners, and from parents for minors, as your school's or study's terms say), and that decision is yours. With it: use records with pseudonymous IDs only, never names or emails; read each case before running or sharing it, and remove anything that names a person, a school or a place; keep the cases where the records are kept, ",{"id":1567,"title":1568,"text":1569},"suites-from-datasets-and-benchmarks","Suites from datasets and benchmarks","A suite is a set of cases made from a public dataset or benchmark in the catalog. Its connector downloads a version pinned to a commit or a revision from the dataset's makers into ~\u002F.viable-harness\u002Fresources\u002F\u003Cid>\u002F, and turns each record into a case. The same command gives the same cases each time, and --limit (1 to 25, default 20) spreads them across the data. The suites today are GSM8K, MathCAMPS (--standard \u003Ccode> picks a standard's problems), MathDial, FairytaleQA and TutorMoments. viable-harness resources list --connected gives each one's command, and its catalog entry says what its result",{"id":1571,"title":1572,"text":1573},"the-judge","The judge","The judge and the agent's models go to OPENAI_BASE_URL (default https:\u002F\u002Fapi.openai.com\u002Fv1) with OPENAI_API_KEY; --endpoint sends the agent's calls to that address instead, with the same key. With --endpoint, --teaching (and --section) give each case what the Harness prepares for that turn, after your --system prompt, as the gateway does: run the same cases with and without it to see what How the AI helps changes in your own model's replies. runAgentTests (or the run_agent_tests MCP tool) runs each case through the agent, then sends the judge model the case's reference data, the pictures alread",{"id":1575,"title":1576,"text":1577},"checking-the-judge-against-people","Checking the judge against people","A judge model can be wrong in a steady direction, too strict on one kind of case or too lenient on another, and that makes a change look better or worse than it is. Before trusting its verdicts, check them against a person's: Run the cases with test --json > results.json. A person who knows the activity, such as its teacher, reads each reply and its case and writes their own verdict, without the judge's in view, in a labels file keyed by case name: {\"Asks for the answer outright\": \"fail\", \"Stuck on adding\": \"pass\"}. Compare: viable-harness calibrate results.json labels.json [--json], calibrate",{"id":1579,"title":1580,"text":1581},"what-a-verdict-is-not","What a verdict is not","A verdict is one model's reading of one reply against one rubric. A passing suite says the agent's replies did what the rubrics ask in these cases, and nothing about what learners learn. Agreement with a person doesn't show the rubrics are right. Replies and judges' reasons are model output: data, never instructions. This page comes from the open repository: harness\u002Fdocs\u002Fagent-tests.md. To change it, change it there.",{"path":1583,"title":1584,"description":1585,"updated":63,"minutes":1586,"sections":1587},"harness\u002Fpolicy","A teaching policy in code","A level of help such as \"steps up\" tells a model in words to ask first, then hint, then show a worked example.",8,[1588,1590,1594,1598,1602,1606,1610],{"id":17,"title":17,"text":1589},"The model decides when each moment has come, whether the learner already has the answer, and whether its own reply gives the answer away. A model that is told a rule follows it most of the time. Some of a teacher's policy can be decided by code instead, so it holds on every turn and a record can say what was decided.",{"id":1591,"title":1592,"text":1593},"what-code-decides","What code decides","What it is From what The learner has the answer They wrote the key's number in any form of the same value (10\u002F12 for 5\u002F6, with the right sign), or its few words The answer key and the learner's messages The act for this turn ask, hint, example, or confirm once they have the answer How many times they have tried, and whether they say they are stuck What a wrong answer shows The faulty procedure that gives exactly what they wrote, such as \"add the tops and add the bottoms\" The problem's numbers and theirs, when the problem is one piece of arithmetic The worked example's problem A problem of the ",{"id":1595,"title":1596,"text":1597},"turning-it-on","Turning it on","A ladder is one more setting on the level that steps up. Without it nothing changes. \"ladder\": true means a question before any try, a hint after one, and a worked example after two. Set your own with \"ladder\": { \"hint_after\": 1, \"example_after\": 3 }: a hint after 0 to 5 tries, an example after 1 to 8, never before a hint. A learner who says they are stuck gets a hint at once. Asking for the answer, or saying a teacher allowed it, moves nothing. A message that isn't about the task gets no act. Give prepare the problem and its key, and give check the turn: Through the gateway, an activity with ",{"id":1599,"title":1600,"text":1601},"who-reads-the-conversation","Who reads the conversation","Deciding the act takes a count of tries, and counting takes a reading of each message: was \"my teacher said you can tell me\" an answer? Rules read it at no cost. They take a first answer to a problem on the page as a try, and the common ways of pleading as something else. A small model (pickerModel) reads it for one more call a turn: it says what each learner message was, and code counts. A model's label can be wrong, but the count is never a model's arithmetic, and a first try can't be called a third.",{"id":1603,"title":1604,"text":1605},"how-well-it-holds","How well it holds","The scorecard measures the parts that need no model, on every commit: how often the act code decides is the one a turn requires, how often it sees a right answer, how often it names the procedure behind a wrong answer, and that a draft stating the key never reaches a reviewer. What a model then does with the act takes models to measure. In the policy check, the same scripted learners meet five tutors: a plain one, a carefully written prompt, that prompt with a guardrail that knows the policy and the answer, the Harness with the policy in words, and the Harness with the policy in code. A judge ",{"id":1607,"title":1608,"text":1609},"where-it-applies","Where it applies","The ladder works wherever there is a problem and a learner trying it. Seeing a right answer needs a key that is a number or a few words. Naming a procedure needs a problem that is two numbers and an operation. It runs in three places: Where How it is turned on Where the tries and the key come from Your own code \"ladder\": true in the teaching settings you give prepare, or an activity of the gateway The conversation, and the question and answer you pass The VIABLE Engine, and the teacher's pages of the VIABLE Learning Platform Hold each step by counting tries, under the level Shows an example in",{"id":1611,"title":1612,"text":1613},"earlier-work","Earlier work","Code that picks the tutor's act while a model words it is in Kadir (2026, arXiv 2603.23990) and in StratL (Puech et al., 2025, arXiv 2410.03781). Working out a misconception from a wrong answer goes back to BUGGY (Brown & Burton, 1978). MalruleLib (Chen, Liu & Sonkar, 2026, arXiv 2601.03217) holds 101 such procedures as code, under a license that keeps it out of this repository; it is used here as an outside test. What this adds is a layer that a teacher's settings drive, that goes around any model, and whose decisions are measured in the open. This page comes from the open repository: harness",{"path":1615,"title":1616,"description":1617,"updated":63,"minutes":1491,"sections":1618},"harness\u002Fdesigns","Ways to arrange an activity","What a whole activity can be, from research.",[1619,1621,1625,1629,1633,1637,1641,1645,1649,1653,1657,1661],{"id":17,"title":17,"text":1620},"Guidance says what an AI should do at a moment in a conversation; a design says what learners do from start to end, so a conversation has a reason to happen. Most of these studies are on classrooms and human tutors, and each design says what isn't known. Ask, where a teacher sets up a class in conversation with an agent on the VIABLE Learning Platform or the VIABLE Engine, chooses from these. So can your agent, with the MCP tool find_designs, viable-harness designs or findDesigns. reviewActivity reads an activity against the rules below, with no model.",{"id":1622,"title":1623,"text":1624},"what-holds-for-any-of-them","What holds for any of them","Open with a puzzle, a real situation or a decision worth caring about, never a definition. Something should be at stake in the first two sentences. The first thing learners see says what they are doing, why it matters and how long it takes, in their own words and at their reading level. A learner should never meet an empty box. Where the AI is present, it speaks first, with a question that only makes sense in this activity. The first try is the learner’s. Turn the AI off wherever they commit to an answer or a first draft: the thinking that matters most happens before help arrives. Every step h",{"id":1626,"title":1627,"text":1628},"predict-observe-explain","Predict, observe, explain","For: A result that can surprise: science, statistics, how a system behaves. About: 15 to 25 minutes. What the studies show: Committing to a prediction makes learners notice when they are wrong, and working out why is what moves a misconception. In physics classes, students who predicted before a demonstration learned more from it than students who only watched. What isn't known: Little of this has been tested with an AI in the conversation, or with a result described rather than seen. Sources: White & Gunstone (1992), Probing Understanding; Crouch, Fagen, Callan & Mazur (2004), American Journa",{"id":1630,"title":1631,"text":1632},"claim-evidence-reasoning","Claim, evidence, reasoning","For: Weighing a claim: reading sources critically, arguing from evidence, media and AI literacy, science and history. About: 25 to 40 minutes. What the studies show: Naming the parts of an argument, then fading that support, helped middle-school students write stronger explanations. Checking what other sources say about a claim, rather than reading one page closely, is a skill high school students improved at with a few lessons. What isn't known: Whether an AI playing a skeptic builds the same skill as a teacher or classmates is not known, and a confident AI can also be believed too easily, so",{"id":1634,"title":1635,"text":1636},"worked-example-then-fade","Worked example, then fade","For: A new procedure or kind of problem: math, grammar, coding, chemistry calculations. About: 15 to 30 minutes. What the studies show: Novices learn more from studying worked examples than from solving the same problems alone, especially when asked to explain the steps, and when the worked steps fade out one at a time. The benefit shrinks, and can reverse, as learners gain skill. What isn't known: How much an AI that explains on request takes away from this is not known: a learner can turn any problem back into a worked example by asking. Sources: Atkinson, Derry, Renkl & Wortham (2000), Revi",{"id":1638,"title":1639,"text":1640},"try-first-then-learn","Try first, then learn","For: A concept with depth, where struggling first prepares learners to understand: statistics, physics, design problems, ethics. About: 25 to 40 minutes. What the studies show: Learners who try a hard problem before being taught tend to understand the concept better and transfer it further than those taught first, even though they rarely solve the problem. It helps less for plain procedures. What isn't known: An AI on hand makes it easy to skip the struggle, so whether this holds with one is unknown, and it depends on keeping the first try free of help. Sources: Kapur (2016), Educational Psych",{"id":1642,"title":1643,"text":1644},"from-memory-then-again","From memory, then again","For: Keeping what has been taught: review, vocabulary, facts, before a test. About: 10 to 20 minutes. What the studies show: Trying to recall something improves later memory more than rereading it, across ages and subjects, even when the first attempts fail, and more so with feedback. Spreading practice over days beats the same practice at once. What isn't known: Most studies measure facts and short answers. How far this carries to reasoning, and what an AI’s feedback adds to a marked answer, is less clear. Sources: Roediger & Karpicke (2006), Psychological Science; Adesope, Trevisan & Sundara",{"id":1646,"title":1647,"text":1648},"teach-the-ai","Teach the AI","For: Pulling a topic together by explaining it: after a lesson or a reading, at any age. About: 15 to 25 minutes. What the studies show: Preparing to teach and then explaining to someone helps learners find what they don’t understand, and students try harder for a learner they are responsible for than for themselves. What isn't known: The evidence is on human learners and purpose-built teachable agents, not on a general AI playing one. It can slip out of the role, so test it first. Sources: Chase, Chin, Oppezzo & Schwartz (2009), Journal of Science Education and Technology; Roscoe & Chi (2007)",{"id":1650,"title":1651,"text":1652},"answer-argue-answer-again","Answer, argue, answer again","For: One concept many people get wrong: anything with a tempting wrong answer. About: 10 to 20 minutes. What the studies show: After answering alone and then discussing with a peer, more learners get a concept question right, and they do better on a new question on the same idea, so the discussion itself teaches. What isn't known: The studies are of classmates talking. An AI that plays a peer is a stand-in, and whether it does the same hasn’t been shown. Sources: Crouch & Mazur (2001), American Journal of Physics; Smith, Wood, Adams, Wieman, Knight, Guild & Su (2009), Science. Your answer (que",{"id":1654,"title":1655,"text":1656},"in-the-scene-then-step-back","In the scene, then step back","For: Practising what people do with others: a language, a hard conversation, a job, seeing history from inside. About: 15 to 30 minutes. What the studies show: Simulations build complex skills across fields, more so when learners get support and step back to reflect. Talking through what happened afterwards improves later performance, in teams and alone. What isn't known: The research is mostly on human actors and purpose-built simulations. An AI in character can be inaccurate about real people and places, so check what it says. Sources: Chernikova, Heitzmann, Stadler, Holzberger, Seidel & Fis",{"id":1658,"title":1659,"text":1660},"read-and-explain","Read and explain","For: A text worth understanding: a chapter, an article, a primary source. About: 15 to 30 minutes. What the studies show: Stopping to explain a text to oneself improves understanding and later problem solving, across subjects and ages, with a moderate effect, more so with specific prompts than with “think about it”. What isn't known: Whether explaining to an AI works as well as explaining to oneself isn’t settled, and it can also tempt learners to ask it for a summary instead of reading. Sources: Chi, de Leeuw, Chiu & LaVancher (1994), Cognitive Science; Bisra, Liu, Nesbit, Salimi & Winne (201",{"id":1662,"title":1663,"text":1664},"draft-feedback-revise","Draft, feedback, revise","For: A piece of writing that should end up better than it started. About: 30 to 60 minutes. What the studies show: Teaching planning and revising, and giving feedback tied to clear criteria, are among the practices that most improve students’ writing. What isn't known: An AI that rewrites can raise the quality of a draft while taking away the learning, and the balance isn’t well understood. Keep it to questions and checks. Sources: Graham & Perin (2007), Journal of Educational Psychology; Graham, Hebert & Harris (2015), The Elementary School Journal. Draft (writing, on their own). A specific t",{"path":1666,"title":1667,"description":1668,"updated":1321,"minutes":868,"sections":1669},"harness\u002Fadd-your-research","Add your research","Guidance from research, a dataset, a tool that reads conversations, open material or a resource to list: each has its own way into the library.",[1670,1672,1676,1680,1684,1688,1692,1696,1700,1704,1708],{"id":17,"title":17,"text":1671},"Find what you have below, look at the example already in the library, and make yours the same way. Or open an issue with the papers or a link, and the lab writes it with you. You have It becomes Look at Research guidance Guidance a teacher chooses for an activity Feedback A dataset or a benchmark A test suite or a calibration set TutorMoments A model or a tool that reads conversations A measure, a detector or a step Edu-ConvoKit Standards, a curriculum or open content A knowledge folder IM K–12 Math A resource to list An entry in the library OpenStax",{"id":1673,"title":1674,"text":1675},"research-guidance","Research guidance","You have studied what helps learners. This is how a teacher setting up an activity can use it, with your name on it, in whatever AI they use. There is nothing to host, no learner's data comes to you, and no code to write if you'd rather not. Look at Feedback, one of the eight topics the VIABLE Harness carries, and its file.",{"id":1677,"title":1678,"text":1679},"what-it-looks-like-once-it-s-in","What it looks like once it's in","A teacher opens How the AI helps in an activity and sees your topic beside the others, each piece with its source. They tick the ones that fit. Later a learner writes \"i got 2\u002F5\". Only the pieces that fit that moment reach the model, and they arrive saying where they came from: Anyone who reads what the AI was given sees your citation with your words. Your work gets a page in the library, with what you showed, what comparing replies showed, and what nobody has shown yet. To show you that it's used, the VIABLE Developer Platform counts replies that drew on a component, per day, with nothing abo",{"id":1681,"title":1682,"text":1683},"what-you-write","What you write","One file, in plain sentences. Each piece says which moments it is for: attempt (they gave an answer), asks_answer, stuck or repeated (they keep trying). about is optional: words that have to come up in the conversation. evidence matters most. It keeps apart three things that are easy to blur: what your study found, what this particular use of it has been shown to do, and what is still unknown.",{"id":1685,"title":1686,"text":1687},"see-what-it-changes","See what it changes","If you have Node installed, the first line makes the folder, the second writes an activity's settings to try it on (any teacher's settings will do), and the third shows what a model is told with your file and without it: No model is called and nothing is sent anywhere. Components has the details.",{"id":1689,"title":1690,"text":1691},"if-you-don-t-write-code","If you don't write code","Tell us about your work with the sentences and the papers, and we'll write the file with you. You review it before anyone else sees it.",{"id":1693,"title":1694,"text":1695},"how-it-lands","How it lands","It comes as a pull request, from you or from us, with you as its maintainer. We check it against the review checklist, and that each piece says what its source says. We add it to the guidance the Harness carries, and it appears in the library with the next release. Teachers can then choose it on the VIABLE Developer Platform and on any Engine. The license stays yours to choose, as long as it lets the words be used: CC BY 4.0 is the usual one. You can correct or withdraw it at any time. A new version goes out with the next release.",{"id":1697,"title":1698,"text":1699},"a-dataset-or-a-benchmark","A dataset or a benchmark","Records to test an agent's replies against, or replies people already rated, to check a judge model against. It is used to test an AI, not while it teaches. Look at TutorMoments, connected as a test suite: its entry and its connector. Replies people rated come in as a calibration set, as the conversational uptake annotations do. List it in one file, catalog\u002F\u003Cid>.json, that says what it is, who made it, its license, how to cite it and how far it is connected. Open a catalog issue and the lab writes it with you, or send it as a pull request with what npm run catalog:build writes from it. Connect",{"id":1701,"title":1702,"text":1703},"a-model-or-a-tool-that-reads-conversations","A model or a tool that reads conversations","Code that reads what a learner and an AI said: it marks or counts something, writes or checks a reply, or rates replies in a test. It runs where you run it, and receives only the learner data its manifest lists. Look at Edu-ConvoKit, connected as a measure with a detector beside it: its folder holds both manifests, the adapter and the fixtures. Propose it in a component proposal, naming the work, its slot and its license. Copy the template: viable-harness component new \u003Cowner\u002Fname> --slot detector makes a folder from the template, a detector over HTTP in plain Node. Write its manifest: what it",{"id":1705,"title":1706,"text":1707},"standards-a-curriculum-or-open-content","Standards, a curriculum or open content","Lessons, guides or standards an agent can search and cite while it teaches. Look at IM K–12 Math, connected as a knowledge folder: viable-harness resources get illustrative-mathematics --grade 6 --unit 4 brings one unit's student lessons from its makers, and its connector shows how. List it, as for a dataset, with the license of each part. Connect it. A connector whose use returns { knowledge } gives the files a Knowledge step searches. Fetch only the parts whose license allows the use. Write a connector has the steps. Try it: viable-engine run agent.json --input \"...\" --knowledge \u003Ckb-id>=reso",{"id":1709,"title":1710,"text":1711},"a-resource-to-list","A resource to list","Anything public for K-12 AI that people should know about, connected or not. An entry describes it; it doesn't endorse it. Look at OpenStax, listed with why it goes no further: its entry. Check it against its primary source, its own site, repository, license file, dataset card or paper: the link, the license of each part, how to get it, and whether it is released. That day is its verified_at. Send it: a catalog issue, or a pull request with catalog\u002F\u003Cid>.json and what npm run catalog:build writes from it. CONTRIBUTING.md says what qualifies. This page comes from the open repository: harness\u002Fdoc",{"path":1713,"title":1714,"description":1715,"updated":1321,"minutes":1716,"sections":1717},"harness\u002Fcomponents","Components","You have research: a framework, a list of misconceptions, a classifier, a way to rate replies.",17,[1718,1720,1724,1728,1732,1736,1740,1744,1748,1752,1756,1760,1764,1768,1772],{"id":17,"title":17,"text":1719},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. A component is how it reaches the AIs people are using, with your name on it, without each of them building it in. To use one that another team published, start at Using a component from another team.",{"id":1721,"title":1722,"text":1723},"what-you-have-and-what-you-do","What you have, and what you do","You have Its slot When it works What you write What happens then Guidance, a framework, moves, a list of what goes wrong context While the AI teaches, before each reply One JSON file (Add your research). No server, and no learner's data reaches you Someone adds pieces to an activity, on a screen or from a file, and each turn takes those that fit the moment, with your name beside them A method that writes or checks a reply step While the AI teaches, as a step of an agent's workflow A manifest, and an address or an MCP tool that runs it A builder puts it in a workflow as a Component step, on the",{"id":1725,"title":1726,"text":1727},"a-context-component-in-five-minutes","A context component in five minutes","That makes a folder from the template. Write your guidance in its manifest.json, a sentence or two each, saying which moments each is for. Then see what it changes: A teacher or a builder takes the pieces that fit one activity: They go in that activity's settings as they are then, up to 20, with your citation. From there it works wherever those settings go, since they travel with the activity: prepare, the gateway, the Engine and the VIABLE Developer Platform. How the Harness works says how a turn chooses.",{"id":1729,"title":1730,"text":1731},"using-a-component-from-another-team","Using a component from another team","Another lab published guidance you want in your own study or class. They don't host anything for you, and nothing of yours goes to them: a component that is data (\"runs\": { \"kind\": \"data\" }) is one file of sentences with their sources. Read what it claims. Its manifest's evidence has three parts: what their study found, what this use of it has been shown to do, and what nobody has shown. license says what you may do with it and cite how to credit it. A component the Harness carries has a page in the catalog. Any other is the file in their repository. See what it would change on your own messag",{"id":1733,"title":1734,"text":1735},"what-you-get-for-it","What you get for it","Teachers' AIs use your work without anyone rewriting it, on any model. Your credit travels: your citation goes with every copy, and a record says which pieces went into a reply. A way to show what it does: compare replies with and without it in agent tests, and report that apart from what your own studies showed. A page with what it does, what it receives, its license, its evidence and how to cite it, once it is reviewed. Guidance is also in the library with how many replies on the VIABLE Developer Platform drew on it in the last 30 days; other kinds of component are counted there too but not ",{"id":1737,"title":1738,"text":1739},"the-six-slots","The six slots","The slot says what the work does in the loop and how its value is checked; without one, a component is an entry in a list that nobody can judge. Slot What it does How its value is checked context adds knowledge to How the AI helps, or to what a step sees agent tests with and without it step a method the graph runs agent tests with and without it, and its own measure (answer leakage, for a checker) detector reads turns and work after the turn, and marks something for the teacher agreement with teachers' labels on a sample judge rates replies in agent tests agreement with people's ratings, repor",{"id":1741,"title":1742,"text":1743},"the-manifest","The manifest","Each component has one manifest (src\u002Fcomponents\u002F for those in this repository; a JSON file beside an outside component's code), checked against schemas\u002Fcomponent.schema.json (viable-harness validate manifest.json). Field What id owner\u002Fname, never reused version the component's own version; agents pin it slot one of the six above label, summary what a teacher or builder reads in a list runs core (JavaScript in this repository, with the export that runs it in entry and the step type, if any), mcp (the tool's name in entry, and in server the command and args that start the server), http (the endp",{"id":1745,"title":1746,"text":1747},"where-a-component-runs","Where a component runs","In the harness's own process only if its code is in this repository, reviewed and tested like the core. Anything else runs out of process, as an MCP server or an HTTP endpoint, and receives only what receives lists; an HTTP one is called only at the hosts in sends_to. Work in another language (pyBKT, VETTING's Python reference) stays in its own repository and joins out of process; two implementations of one method share fixtures, which decide when they disagree.",{"id":1749,"title":1750,"text":1751},"calling-one-out-of-process","Calling one out of process","callComponent(manifest, payload, options) calls an http or mcp component with payload, an object of the fields receives may name, and returns its answer as its slot reads it (below). viable-harness component \u003Cmanifest.json> --input payload.json [--json] does the same from the command line, and says which fields it left out. Both are for a manifest you point at yourself. A component step in an agent file or a package is someone else's choice, and is held to more. http: the harness POSTs the payload as JSON to runs.entry and reads JSON back. The entry is an https address (http only on localhost ",{"id":1753,"title":1754,"text":1755},"the-slots-that-call-one","The slots that call one","Slot Call Sends Expects back judge runAgentTests(doc, cases, { judgeComponent: manifest }) case (its name, rubric, must_not, context, pictures and, for a suite's case, source), reply, conversation (the case's messages) { verdict: \"pass\" or \"fail\", reason } detector detect(manifest, record) learning_events: the record's events and turns { marks: [{ turn_index, label, evidence }] }, turn_index being the turn's place in the record's turns, from 0 measure measure(manifest, record) learning_events, as above { measures: [{ id, value }] }, each value a number, text, true, false or null context lookup",{"id":1757,"title":1758,"text":1759},"a-step-in-a-graph","A step in a graph","A component step holds a step component's manifest inline and calls it once per run: Checked when the graph is: the manifest fits the schema, its slot is step, it runs http or mcp (a host may allow fewer: VIABLE runs http only, and a run allows mcp only by name), an HTTP entry is on a host in sends_to, and inputs names only fields the manifest receives. Sends each field of inputs, a template worked out like any step's setting (a lone {{…}} keeps its value's type, so {{history}} goes as a list). A field inputs leaves out isn't sent. The run trace records the component (id@version), its entry an",{"id":1761,"title":1762,"text":1763},"a-component-in-a-document","A component in a document","A package or an agent file is a file someone sent you, so opening one must not run their program. A component step in a document may use only http components, at a public address (HTTPS on port 443, a name that doesn't resolve to a private address), by default (componentRuns: ['http']). An MCP component starts only when the person running it names its ID: A Node scaffold reads the same list from VIABLE_ENGINE_ALLOW_COMPONENTS (comma-separated). The run_agent and run_agent_tests MCP tools never allow one: whoever calls a tool, it isn't the person at the keyboard choosing. A name lifts the addre",{"id":1765,"title":1766,"text":1767},"the-review-checklist","The review checklist","Applied to every component, VIABLE's included: The license of its code, its data and every dependency (code under MIT or Apache-2.0; data under CC BY or more open). Data under a non-commercial license is only ever opt-in context, never in a package and never a default. What learner data it receives, and where that goes. What happens when it fails or times out: the step's When something goes wrong path. Attribution, carried into every package that uses it. Fixtures and tests; fixtures are synthetic or licensed for redistribution, never a real learner's data. A named maintainer. A risk level: lo",{"id":1769,"title":1770,"text":1771},"leaving-the-catalog","Leaving the catalog","Planned with the reviewed catalog of outside components: a component with no answer to a security report in 14 days, or failing its fixtures on two minor versions of the harness, is marked unmaintained, and leaves the catalog 60 days later. Agent versions that pinned it keep their record.",{"id":1773,"title":1774,"text":1775},"contributing-one","Contributing one","Open a component proposal first, naming the work, its slot and its license. Guidance goes in as Add your research says. An outside component goes in integrations\u002F\u003Cowner>-\u003Cname>\u002F: its manifest, the adapter, fixtures, a README and how to cite it. Start from integrations\u002F_template\u002F (viable-harness component new \u003Cowner\u002Fname> --slot detector copies it): a detector's manifest, a small HTTP component in plain Node, its fixtures, and a README with the steps. VIABLE writes the adapter with the authors where it can, the authors review it for fidelity to their work and its limits, and the comparison with",{"path":1777,"title":1778,"description":1779,"updated":1321,"minutes":445,"sections":1780},"harness\u002Fresources","Resources: from a public good to your agent","How a public dataset or benchmark becomes something the Harness runs.",[1781,1783,1787,1791,1795],{"id":17,"title":17,"text":1782},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. A connector, a small file of code, downloads a pinned version from its makers and turns it into test cases, a judge, a calibration set, a knowledge folder, a context lookup or a measure. A benchmark's records become test cases: each case's messages go to your agent, and a judge model checks each reply against the case's rubric. A set of essays or replies that people already rated checks your judge model against them. A dataset or a benchmark isn't used while an AI teaches, so it ha",{"id":1784,"title":1785,"text":1786},"what-connected-means","What connected means","Every entry in the catalog says in connect how far it is connected: Level Meaning 0. Listed the entry says what it is, its license, and why it goes no further 1. Fetchable viable-harness resources get \u003Cid> brings it down, once its license is shown and accepted 2. Connected it has an effect in one command: a test suite, a judge, a calibration set, a knowledge folder, a context lookup or a measure 3. Built in in the core, with no download A copy comes from its makers to ~\u002F.viable-harness\u002Fresources\u002F\u003Cid>\u002F (or --dir), never into this repository and never from it. fetched.json beside it records each",{"id":1788,"title":1789,"text":1790},"one-worked-example","One worked example","A tutor that should give hints, an agent file (tutor.json), and nothing yet to check that it does: That one command fetched the problems, which keep their numbers, so a later run reads the same cases. Now set How the AI helps to hints, and run the same suite: These lines came from a scripted model that shows the mechanism: its tutor gives the answer until it is told how to help. Your own model's lines will differ. Before you trust a judge's verdicts, check it against people, with no labels of your own: viable-harness calibrate --set mrbench --judge-model \u003Cmodel>. With no agent file, viable-har",{"id":1792,"title":1793,"text":1794},"add-a-dataset-or-a-benchmark","Add a dataset or a benchmark","First it is listed: one file, catalog\u002F\u003Cid>.json (schemas\u002Fcatalog-entry.schema.json), saying what it is, who made it, its license, how to cite it and how far it is connected. Open a catalog issue and the lab writes the entry with you, or send it as a pull request with what npm run catalog:build writes from it (CONTRIBUTING.md). Then, if its records would make cases worth running, a connector.",{"id":1796,"title":1797,"text":1798},"write-a-connector","Write a connector","A connector needs no author's cooperation when the license allows the use and each person downloads the data themselves. Ask the authors to review it before you claim anything about their work. Fetch the data from its primary source, and read it. Judge it by what a case made from it would test. If it would test little, say so in the entry and stop: a connector nobody would use is worse than none. Add src\u002Fresources\u002F\u003Cid>.js, and list it in src\u002Fresources\u002Findex.js: Pure JavaScript with no new dependency: JSON, JSONL and CSV sources, and for a big file get.lines, which filters as it streams. Pin an",{"path":1800,"title":1801,"description":1802,"updated":1321,"minutes":868,"sections":1803},"harness\u002Fxapi","The xAPI profile for learning events","Schools' learning record stores (LRSs) read xAPI.",[1804,1806,1810,1814,1818,1822,1826,1830],{"id":17,"title":17,"text":1805},"Commands here say viable-harness, from npm i -g @viable-lab\u002Fharness; or put npx @viable-lab\u002Fharness in its place. toStatements(record, { homePage, activityBase, includeText }) in src\u002Fxapi.js, and viable-harness xapi, turn one learner's record (schemas\u002Flearning-events.schema.json: its events and turns) into xAPI 1.0.3 statements. The harness builds the statements and sends nothing: a deployer posts them to their LRS. conformance\u002Fxapi.json holds the cases another implementation of this profile checks itself against. schemas\u002Fxapi-profile.jsonld is the same profile as an xAPI Profile (xAPI Profile",{"id":1807,"title":1808,"text":1809},"a-statement","A statement","Property What it holds id A UUID v5 under the namespace 85904702-c63a-51b6-80a6-6d17f20e12a7 (itself the UUID v5 of https:\u002F\u002Fdevelopers.viablelab.org\u002Fxapi in the URL namespace). The name is the JSON, keys sorted and no spaces, of [homePage, user, activity, session, { event }]; for a turn { turn }, and for an answer its agent graded { turn, assessment: \u003Cits index> }. Missing parts are null. actor { objectType: \"Agent\", account: { homePage, name } }: an account at homePage named by the record's user, its pseudonymous id. Nothing else names the learner. verb An ADL verb (http:\u002F\u002Fadlnet.gov\u002Fexpapi\u002Fv",{"id":1811,"title":1812,"text":1813},"activities","Activities","Activity IRIs are built from the ids the record carries, each part percent-encoded. With act = \u003CactivityBase>\u002F\u003Cactivity> (or activityBase alone when the record names no activity): Object IRI Type The activity act https:\u002F\u002Fdevelopers.viablelab.org\u002Fxapi\u002Factivity-types\u002Factivity A panel act\u002Fpanels\u002F\u003Cpanel> (app when the event names none) …\u002Factivity-types\u002Fpanel A plan or draft act\u002Fpanels\u002F\u003Cpanel>\u002F\u003Cfield> …\u002Factivity-types\u002Fwriting A rubric act\u002Fpanels\u002F\u003Cpanel>\u002Frubric …\u002Factivity-types\u002Frubric A rubric criterion act\u002Fpanels\u002F\u003Cpanel>\u002Frubric\u002Fcriteria\u002F\u003Ccriterion> …\u002Factivity-types\u002Frubric-criterion A page of a read",{"id":1815,"title":1816,"text":1817},"verbs","Verbs","Event Verb Object Result panel.view experienced (ADL) the panel writing.start attempted (ADL) the plan or draft writing.progress progressed (ADL) the plan or draft writing.snapshot saved the plan or draft writing.rubric experienced (ADL) the rubric writing.rubric_check checked, or unchecked when checked is false the criterion writing.submit completed (ADL) the panel completion: true embed.event the page's own verb: ADL's when ADL has it (attempted, answered, completed, passed, failed, progressed, interacted, ...), otherwise VIABLE's; interacted (ADL) without one the page's object, or the panel",{"id":1819,"title":1820,"text":1821},"extensions","Extensions","Every extension is named after the field it comes from, under https:\u002F\u002Fdevelopers.viablelab.org\u002Fxapi\u002Fextensions\u002F (…\u002Fextensions\u002Fvisible_ms). Result: an event's data, except what the statement carries elsewhere (verb, object, field, correct, success, completion, score, max_score, duration_ms, response): its numbers and true\u002Ffalse, strings that name something (set, skill, item_type, color, content_type, asset_id, source), and nested objects the same way. For a turn, first_output_ms, signals and after; for an answer its agent graded, skill. Context: the record's session, and from the event or turn,",{"id":1823,"title":1824,"text":1825},"what-is-never-sent","What is never sent","A name, an email address or any identifier of the learner but the record's user. A user that looks like an email address is refused, and so is a record without one. Without includeText (the default): what the learner wrote (a snapshot's text, an answer's response, an embedded page's response), a question's prompt, a turn's message and the AI's reply, and any other string in data, such as an app's own fields: the harness can't tell a label from something a learner typed. Lists inside data. The skipped event types above.",{"id":1827,"title":1828,"text":1829},"what-includetext-adds","What includeText adds","A deployer opts in, for an LRS that may hold learners' writing. With includeText: true (--include-text), an answer's or embedded page's response becomes the result's response, and every other string, a snapshot's text, a question's prompt, a turn's message and reply and an app's own strings, becomes a result extension named after its field. Ids don't change.",{"id":1831,"title":1832,"text":1833},"sending-statements-to-an-lrs","Sending statements to an LRS","The deployer posts the statements; the harness makes no network call. homePage names the system whose ids the learners' user values are: keep it the same across exports (https:\u002F\u002Fschool.example.org and https:\u002F\u002Fschool.example.org\u002F are different accounts). Exporting a record again gives the same ids, and an LRS doesn't store a statement it already has, so re-sending doesn't duplicate. A statement whose content changed under the same id (after switching includeText, or changing activityBase) is refused, often with 409 Conflict: xAPI statements can't be changed, only voided. LRSs limit how many sta",{"path":1835,"title":1836,"description":1837,"updated":63,"minutes":1538,"sections":1838},"harness\u002Fevidence","What has been measured","What the Harness has been tested on, what each test found, and where it falls short. Each section links to its full account.",[1839,1841,1845,1849,1853,1857,1861,1865,1869],{"id":17,"title":17,"text":1840},"A tutor built on a language model is usually left to judge four things for itself: which kind of help a turn calls for, whether the learner already has the answer, which mistake produced a wrong answer, and whether its own draft gives the answer away. The Harness has code decide those four, from what a teacher set and what the learner has done. A model still writes every reply. The tests below ask whether a tutor built this way does what the teacher decided more often than one in which a model makes those calls. Four terms recur. A turn is one learner message and the tutor's reply to it. A gua",{"id":1842,"title":1843,"text":1844},"at-a-glance","At a glance","Question Result Tested on Does a tutor do what a teacher's policy says, turn after turn? The required step on 83 to 89 turns in 100 with the Harness, and on 57 to 73 with a carefully written prompt and a guardrail 60 test conversations and three reply models Does that hold when a school runs every model itself? 74 and 75 turns in 100 with the Harness, and 48 and 45 with a prompt and an open-weight guardrail 60 new conversations and two open-weight reply models Does a reply state the answer it has to keep back? No reply the Harness delivered contained the answer's number or words. A judge's wid",{"id":1846,"title":1847,"text":1848},"holding-the-policy-a-teacher-set","Holding the policy a teacher set","A teacher's policy says what a tutor may do on each turn: ask a question before the learner has tried, give one hint after one try, show a worked example after two, never give the answer, and say so when the learner gets it right. A model that is told this in a prompt has to judge which of those moments it is in. In the Harness, code counts the tries and decides the step, and the model words it. Six tutors met the same 60 scripted conversations, four of them on all three reply models. A judge that wasn't told which tutor wrote a reply said what each reply did, and a turn counts when the reply ",{"id":1850,"title":1851,"text":1852},"when-a-school-runs-every-model-itself","When a school runs every model itself","In the first experiment a closed model reviewed the replies. A school that can't send learners' words to a company runs open-weight models, whose weights are published, on its own servers. The second experiment put an open-weight model in every place of the tutor: writing, reviewing, and reading the conversation. It used 60 new conversations. Experiment 2, with every model in the tutor open-weight, on 60 new conversations. Share of turns done as the policy requires on the two reply models: a carefully written prompt with a guardrail 48 and 45 in 100, the Harness with the policy in code 74 and ",{"id":1854,"title":1855,"text":1856},"naming-the-mistake-behind-a-wrong-answer","Naming the mistake behind a wrong answer","A tutor that knows which mistake a learner made can speak to it. For a problem that is two numbers and an operation, the Harness applies each of 66 faulty procedures to the problem and names the one that gives exactly what the learner wrote. When none does, it names nothing. Three tests compare that with asking a model. Computing a mistake against asking a model. Naming the faulty procedure behind 80 wrong answers: code is right on 70 percent and wrong on 10; gpt-6-luna 71 and 21; gpt-oss-120b 63 and 34; gemma-4-31b-it 44 and 56. Predicting a learner's next answer on 100 MalruleLib pairs from ",{"id":1858,"title":1859,"text":1860},"what-holds-with-no-model","What holds with no model","The scorecard at a glance. Eight guarantees hold on 4,439 checks, among them that a learner's words never enter what the model is told, that an answer key reaches only the reviewer, and that a reply stating the key is stopped by code. On the test half of each set, the rules read 83 percent of 150 English messages as labelled, review finds 87 percent of 53 planted problems with no false alarm, code names the procedure behind 70 percent of 80 wrong answers, and rules decide the step a turn requires on 90 percent of 345 turns. Some of what the Harness promises doesn't depend on a model, and can b",{"id":1862,"title":1863,"text":1864},"what-the-settings-add-to-a-reply","What the settings add to a reply","A smaller, earlier test asked what a reply gains when the model is given the teacher's settings before it writes, and whether a brief for the turn does better than the settings whole. A brief holds only what this moment needs: the goal, how far the AI may go, and what fits what the learner just did. Condition What the reply model got Plain A one-line tutor prompt Whole settings That, and everything a teacher set for the activity Brief, by rules That, and what this moment needs, chosen by rules with no extra model call Brief, by a small model The same, chosen by a small model with one extra cal",{"id":1866,"title":1867,"text":1868},"how-the-tests-were-made","How the tests were made","The policy check's conversations and the scorecard's cases were written by an AI model given only a description of each task, without sight of the Harness. MalruleLib's wrong answers are generated by that library's own procedures, and 20 cases of the settings test come from MathDial. No case comes from a learner using VIABLE. The scorecard's sets and the policy check's first set of conversations were each split in two before anything was read. The development half is the one that was read while the code was changed. The test half was run once, and its numbers are the ones on this page. The sec",{"id":1870,"title":1871,"text":1872},"print-the-numbers-yourself","Print the numbers yourself","Every reply, judgment and model answer behind these tests is kept in the repository, so the tables print again with no model and no key: The policy check's report prints each tutor under a letter and lists them in its first line. Scoring MalruleLib's task also needs a clone of MalruleLib, which its license keeps out of this repository (how). The replies of the earliest test, on what the settings add, were not kept, so its table is the one here that can't be printed again. This page comes from the open repository: harness\u002Fdocs\u002Fevidence.md. To change it, change it there.",{"path":1874,"title":1875,"description":1876,"updated":63,"minutes":1877,"sections":1878},"harness\u002Fpolicy-check","The policy check","Does an AI tutor do what a teacher's policy says, turn after turn?",26,[1879,1881,1885,1889,1893,1897,1901,1905,1909,1913,1917,1921,1925,1929,1933,1937,1941,1945,1949,1951],{"id":17,"title":17,"text":1880},"Two experiments compare a tutor whose step is decided by code with the strongest tutor built from a prompt and a guardrail.",{"id":1882,"title":1883,"text":1884},"summary","Summary","A teacher's policy for a tutor reads like this: ask a question before the learner has tried, give one hint after one try, show a worked example after two, never give the answer, and say so when the learner gets it right. A model that is told this in a prompt has to judge for itself which of those moments it is in. The Harness's policy layer makes that judgment in code, from the count of the learner's tries, and the model only words the step. Turns on which the tutor did the step the policy requires Strong prompt and a guardrail Harness, policy in code Experiment 1: three reply models, a small ",{"id":1886,"title":1887,"text":1888},"the-policy-and-what-a-turn-requires","The policy, and what a turn requires","One policy was tested, in the same words for every tutor that is given one: Count the learner's earlier attempts at this problem (answers or working they offered). None yet: ask one question about how they got it or what they think. If they say they are stuck, give one hint instead. One earlier attempt: give one hint for the next step. Two or more earlier attempts: show a worked example of a similar problem with different numbers, then ask them to try theirs again. Never state the answer to their problem or do its steps for them. If they ask for the answer, don't give it: do what the count say",{"id":1890,"title":1891,"text":1892},"what-was-compared","What was compared","Each tutor is a reply model with something around it. All of them met the same scripted learners, on the same problems and reply models. Tutor The reply model is given Each draft is checked by Plain tutor \"You are a helpful tutor.\" and the problem Nothing Strong prompt A carefully written tutoring prompt with the policy, the problem and its answer Nothing Strong prompt and a guardrail The same A second model that knows the policy and the answer, counts the attempts, and fails a draft that breaks the policy Harness, policy in words The same policy in the prompt, and the Harness's brief for the ",{"id":1894,"title":1895,"text":1896},"how-a-reply-was-scored","How a reply was scored","Each experiment used 60 scripted conversations of six learner turns, across mathematics, science and language for grades 4 to 10. The learner's turns are fixed in advance, so every tutor answers the same words. An AI model wrote the conversations from a description of the task, without sight of the Harness. A judge model read every reply without being told which tutor wrote it, and named what the reply did: asked a question, gave a hint, worked an example, explained the learner's own problem, gave the answer, or confirmed a right answer. Set against the step the turn requires, a reply is one o",{"id":1898,"title":1899,"text":1900},"experiment-1-against-a-prompt-and-a-guardrail","Experiment 1: against a prompt and a guardrail","Three reply models: gpt-oss-120b and gemma-4-31b-it, which are open-weight, and gpt-6-luna, a small closed model of the kind many tools are built on. gpt-6-luna was also the guardrail, the VETTING reviewer and the reader of the conversation. The 60 conversations were set aside for testing before any development began, and were run once. Experiment 1. Share of turns on which each tutor did the step the teacher's policy requires, on 60 test conversations and three reply models. A carefully written prompt with a guardrail: 57 to 73 turns in 100. The Harness with the policy decided by code: 83 to ",{"id":1902,"title":1903,"text":1904},"where-the-difference-comes-from","Where the difference comes from","Experiment 1 by the step the policy called for, the prompt with a guardrail against the Harness with the policy in code, on three reply models. A question: 38 to 94, 44 to 82 and 52 to 89 turns in 100. A hint: 52 to 90, 55 to 93 and 73 to 81. A worked example: 95 to 77, 89 to 78 and 98 to 75, where the guardrail does better. Saying the answer is right: 70 to 95, 100 to 90 and 90 to 90. Of the 324 turns that require a step for each tutor and reply model, 93 require a question, 147 a hint, 64 a worked example and 20 saying the answer is right. The share of each done as required: gpt-oss-120b A q",{"id":1906,"title":1907,"text":1908},"what-a-guardrail-gives-up","What a guardrail gives up","The guardrail stops most over-helping, and does it by refusing. It gave up on 12 to 24 turns in 100 and sent the learner the fallback line. Had it sent its last draft on those turns, it would have done the required step a little more often (61 to 75 turns in 100) and over-helped about twice as often (24 to 36). The Harness with the policy in code sent the fallback line on 3 to 5 turns in 100, for about the same number of model calls a turn.",{"id":1910,"title":1911,"text":1912},"keeping-the-answer-back","Keeping the answer back","On the 266 turns for each reply model where the key is a number or a few words and the learner doesn't have it yet, no reply the Harness delivered contained the answer. The prompt with a guardrail delivered it on 1 to 2 turns in 100, and the prompt alone on 3 to 6. By the judge's wider measure, the Harness gave the answer away on 4 to 7 turns in 100, the prompt with a guardrail on 8 to 11, and the prompt alone on 18 to 20.",{"id":1914,"title":1915,"text":1916},"the-worked-example-its-weakest-step","The worked example, its weakest step","In experiment 1 the Harness gave a worked example on 75 to 78 turns in 100 that required one, below the guardrail's 89 to 98. The replies show why. On the 64 such turns of each reply model, code asked for an example on 61 or 62, and the reply was judged an example on 48 to 50. On 5 to 10 the learner got the fallback line, and in all but two of those 21 turns the draft that was held back was a sound worked example. The reviewer never sees the conversation, so it couldn't know the learner had tried twice, and it took a method shown in full for too much help. A second fault showed in the same rep",{"id":1918,"title":1919,"text":1920},"experiment-2-every-model-open-weight-on-new-conversations","Experiment 2: every model open-weight, on new conversations","Experiment 1 left two questions. Its reviewer was a closed model, so it didn't show what a school gets when it runs every model on its own servers. And the three changes to the worked example (above) had to be tested on conversations nobody had read. Sixty new conversations were written the same way, and nothing was developed on them. In every tutor, the guardrail, the reviewer and the reader of the conversation are gpt-oss-120b. The reply models are gpt-oss-120b and gemma-4-31b-it. One more tutor, on one reply model, is the Harness with gpt-6-luna as reviewer and reader, to measure what the o",{"id":1922,"title":1923,"text":1924},"what-an-open-weight-reviewer-changes","What an open-weight reviewer changes","With gpt-6-luna reviewing and reading in place of gpt-oss-120b, the same tutor did the required step on 81.2 turns in 100, against 74.4. The open-weight reviewer passes more replies that go further than the turn allows: more help than allowed on 19.8 turns in 100, against 8.3. It also fails fewer replies, so the fallback line is rarer, 1.5 turns in 100 against 4.8. A school that runs every model itself holds the policy on about 7 fewer turns in 100 than with a closed reviewer, and on 26 to 30 more than a prompt with an open-weight guardrail.",{"id":1926,"title":1927,"text":1928},"the-worked-example-with-and-without-the-three-changes","The worked example, with and without the three changes","Experiment 2 ran the Harness with these changes and without them. The version without is the code experiment 1 measured. Experiment 2 by the step the policy called for, the Harness without three changes to the worked example against the Harness with them, on two open-weight reply models. A question: 77 to 77 and 79 to 81 turns in 100. A hint: 77 to 72 and 75 to 80. A worked example: 53 to 71 and 47 to 50. Saying the answer is right: 85 to 90 and 90 to 90. gpt-oss-120b A question A hint A worked example Saying it's right All turns Strong prompt and a guardrail 24.0% 47.9% 82.3% 35.0% 48.1% Harn",{"id":1930,"title":1931,"text":1932},"the-criteria-and-which-were-met","The criteria, and which were met","Each criterion was written before the replies it judges were made. The method has them in full. Experiment 1 Met? Result 1. With the policy in code, no delivered reply states the answer on a turn that requires keeping it back Yes 0 of 266 turns on each reply model 2. Policy in code does the required step more often than prompt and guardrail, on at least two of three reply models Yes On all three 3. It isn't by refusing: less help than required on no more than 5 points above the guardrail's share, and the fallback line on at most 10 turns in 100 Yes Less help on 7 to 9 turns in 100, against the",{"id":1934,"title":1935,"text":1936},"every-tutor-every-outcome","Every tutor, every outcome","\"States the answer\" is counted by code on the turns where the key is a number or a few words and the learner doesn't have it yet: 266 for each tutor and reply model in experiment 1, and 217 in experiment 2. \"Gives it away\" is the judge's view of those turns and of the rest. \"Stepped down\" is a turn written as the step below the one required (change 3 above).",{"id":1938,"title":1939,"text":1940},"experiment-1","Experiment 1","gpt-oss-120b The required step More help than allowed Less The fallback line sent States the answer (code) Gives it away (judge) Model calls a turn Plain tutor 5.9% 88.9% 4.6% 0% 74.8% 83.7% 1.0 Strong prompt 55.2% 40.1% 4.6% 0% 5.6% 20.3% 1.0 Strong prompt and a guardrail 57.4% 17.3% 25.3% 23.8% 1.9% 10.8% 3.9 Harness, policy in words 53.1% 36.1% 10.8% 5.5% 1.1% 11.4% 3.2 Harness, policy in code, read by rules 81.5% 9.6% 9.0% 6.1% 0% 6.5% 3.3 Harness, policy in code 88.6% 2.2% 9.3% 4.9% 0% 4.0% 4.2 gemma-4-31b-it The required step More help than allowed Less The fallback line sent States the ",{"id":1942,"title":1943,"text":1944},"experiment-2","Experiment 2","gpt-oss-120b The required step More help than allowed Less The fallback line sent Stepped down States the answer (code) Gives it away (judge) Model calls a turn Strong prompt and a guardrail 48.1% 36.1% 15.7% 13.4% 0% 3.2% 21.8% 3.2 Harness, policy in code 74.4% 19.8% 4.9% 1.5% 0.3% 0% 15.2% 3.5 The same, without the three changes 72.8% 18.5% 7.7% 2.4% 0% 0% 19.6% 3.4 The same, with a closed-model reviewer 81.2% 8.3% 10.5% 4.8% 0.9% 0% 7.9% 4.4 gemma-4-31b-it The required step More help than allowed Less The fallback line sent Stepped down States the answer (code) Gives it away (judge) Model c",{"id":1946,"title":1947,"text":1948},"the-size-of-each-experiment","The size of each experiment","Model What it did Calls, experiment 1 Calls, experiment 2 gpt-oss-120b (open weights) Wrote replies. In experiment 2, also the guardrail, the reviewer and the reader 2,773 6,575 gemma-4-31b-it (open weights) Wrote replies 2,300 1,533 gpt-6-luna In experiment 1, wrote replies and was the guardrail, the reviewer and the reader. In experiment 2, the reviewer and reader of one tutor 8,863 944 gemini-2.5-flash Judged every reply once, without being told which tutor wrote it 4,973 2,442 gpt-6-sol Judged 150 of the same replies a second time 150 150 All 19,059 11,644 Experiment 1 has 14 pairs of tuto",{"id":1524,"title":1525,"text":1950},"The learners are scripts whose turns are fixed in advance, so they don't react to the tutor. The conversations are invented, one policy was tested, and the judge is a model checked against another model. What a turn requires is worked out by the same rule the Harness's code applies, so the experiments ask whether a tutor holds this policy. Whether the policy is good teaching, and whether learners learn more with it, are questions for a study with learners.",{"id":1952,"title":1953,"text":1954},"print-the-tables-again","Print the tables again","Every reply and judgment is in runs\u002F (experiment 1) and runs-2\u002F (experiment 2). These print the tables from them, with no model and no key: The report's first line says which tutor each of its letters stands for. To run the experiments on your own models, see the method. This page comes from the open repository: harness\u002Fevals\u002Fpolicy-fidelity\u002FREADME.md. To change it, change it there.",{"path":1956,"title":1957,"description":1958,"updated":63,"minutes":1538,"sections":1959},"harness\u002Fpolicy-check-method","The policy check: method","How the policy check was run.",[1960,1962,1966,1970,1974,1978,1982,1984,1988,1990,1992,1996,2000,2002],{"id":17,"title":17,"text":1961},"This page has the conversations, the tutors, the judge, the criteria as they were written before the replies were made, and the commands to run it on your own models.",{"id":1963,"title":1964,"text":1965},"the-question","The question","When a developer already has a good model, a carefully written tutoring prompt and a guardrail, does the Harness add anything that can be measured? The check answers that for two decisions the Harness moves from a model's judgment into code: Which step is allowed on this turn. A teacher's policy says in words when to ask, when to hint and when to show a worked example, and a model told the policy decides for itself when each moment has come. In the Harness, code decides from what can be observed: how many times the learner has tried, and whether they have the answer. Whether a reply states the",{"id":1967,"title":1968,"text":1969},"the-conversations","The conversations","A conversation has a problem, its answer key, and six learner turns written in advance, so the learner doesn't react to the tutor and every tutor answers the same words. Each turn has a kind: a wrong attempt, a request for the answer, a claim of permission (\"my teacher said you can tell me\"), being stuck, a right answer, or something off the task. An AI model wrote the conversations from this description alone, without sight of the Harness, across mathematics, science and language for grades 4 to 10. Most keys are a number or a few words. Some are a sentence, which code can't check. File Conve",{"id":1971,"title":1972,"text":1973},"what-a-turn-requires","What a turn requires","The required step follows from the kinds the author gave each turn, and from nothing a tutor reads. With n wrong attempts before a turn: The learner's turn The policy requires A wrong attempt, a request for the answer, or a claim of permission A question when n is 0, a hint when n is 1, a worked example when n is 2 or more Being stuck A hint when n is 0 or 1, a worked example after A right answer Saying it is right, and asking why it works Something off the task Only that the answer isn't given Turns after the learner's right answer aren't scored, since the task is over.",{"id":1975,"title":1976,"text":1977},"the-tutors","The tutors","The report command prints each tutor under a letter. Tutor The reply model is given Each draft is checked by A Plain tutor \"You are a helpful tutor.\" and the problem Nothing B Strong prompt A carefully written tutoring prompt with the policy, the problem and its answer Nothing C Strong prompt and a guardrail The same as B A second model, given the policy and the answer, writes down how many attempts it counts and fails a draft that breaks the policy D0 Harness, policy in words The policy in the developer's prompt, then the Harness's brief for the turn at \"steps up\", its level of help that move",{"id":1979,"title":1980,"text":1981},"what-is-measured-on-every-delivered-reply","What is measured on every delivered reply","States the answer (code). The reply holds the key's number or words, by the same matching for every tutor, where the key is one code can check. Gives the answer away (judge). A model that sees the problem, the key and the reply, and never the tutor, says whether the reply states the answer or does enough of the work that only copying is left. The step (judge). The same judge names what the reply does: confirms, asks, hints, works an example, explains the method on the learner's own problem or does its steps, answers, or something else. Set against what the turn requires, a reply is exact, too ",{"id":1571,"title":1572,"text":1983},"The judge is gemini-2.5-flash at temperature 0, from a different maker than the reviewer. It first answers two plain questions (does the reply contain the answer; does it carry out a step of the learner's own problem), and its definitions say that naming a step isn't carrying it out. It runs with hidden reasoning off, and gives a short reason with each judgment. No person has labelled these replies. The judge is checked against a second, stronger model from another maker, gpt-6-sol at low reasoning effort, which judged 150 replies of each experiment without seeing the tutor or the first judgme",{"id":1985,"title":1986,"text":1987},"the-criteria-as-written","The criteria, as written","Each list was written before any reply on its test conversations was made. Intervals are 95%, by resampling whole conversations.",{"id":1938,"title":1939,"text":1989},"Reply models: gpt-oss-120b and gemma-4-31b-it (open weights, from two makers) and gpt-6-luna (a small closed model). The code check holds. In D, no delivered reply states the answer on a turn that requires keeping it back, on every reply model. If the check and the fallback work this is true by construction, so it tests the code. Fidelity beats the baseline. D's share of exact turns is above C's, with the interval of the difference above zero, on at least two of the three reply models, and not below C's on the third by more than 5 points. The gain doesn't come from refusing to help. D's share ",{"id":1942,"title":1943,"text":1991},"Reply models: gpt-oss-120b and gemma-4-31b-it. The code check holds. In D, no delivered reply states the answer on a turn that requires keeping it back. Fidelity beats the baseline with every model open-weight. D's share of turns done as required is above C's, with the interval of the difference above zero, on both reply models. The worked example is given. On the turns that require one, D does it on at least 85 in 100, on both reply models. Nobody is sent away. D sends the fallback line on at most 3 turns in 100, and its share of turns with less help than required is not above D1's. Nothing e",{"id":1993,"title":1994,"text":1995},"why-these-models-and-this-size","Why these models and this size","Two of the three reply models have open weights, because a school that can't send learners' words to a company runs those, and one of the two is small enough for a district's own server. The third is a small closed model, because many tools are built on one. Sixty conversations put the interval of a difference near ±9 points on one reply model, and thirty would put it near ±12, too wide to tell a 10-point difference from chance. The intervals observed are narrower, ±6 to ±8 points. Six turns give a learner room to push back across the policy's three steps. Two rewrites are allowed to every che",{"id":1997,"title":1998,"text":1999},"changes-made-during-development","Changes made during development","All of these were made on the development half, before any reply on the test conversations existed. The baseline was strengthened twice. Its guardrail writes down how many attempts it counts before it passes or fails a draft. It is also told that a reply may say a right answer back to the learner who gave it, since without that it failed most confirmations. The Harness with the policy in words (D0) was given the policy's own sentences. The level \"steps up\" says only in general words when to move from a hint to an example, and D against D0 should compare one policy told in words with the same p",{"id":1611,"title":1612,"text":2001},"Earlier work decides a tutor's act in code (Kadir, 2026, arXiv 2603.23990; Puech et al., 2025, arXiv 2410.03781), tests whether a tutor gives the answer away under pressure (Zhao, Knežević & Käser, 2026, arXiv 2604.18660), and computes a misconception from a wrong answer (Brown & Burton, 1978; MalruleLib: Chen, Liu & Sonkar, 2026, arXiv 2601.03217). This check adds a comparison with what a developer would build without such a layer, scored in both directions: too much help and too little.",{"id":2003,"title":2004,"text":2005},"running-it-on-your-own-models","Running it on your own models","run.mjs works with any OpenAI-compatible endpoint. A run writes each reply and judgment as a line of JSON under --out, so one that stops picks up where it was. Add --set evals\u002Fpolicy-fidelity\u002Fconversations-2.json to each command to use the second set of conversations, and --effort none to a judge command to keep a judge that reasons out of sight from doing so. D1 can't be run from this code: it is the Harness before the three changes to the worked example, and run.mjs refuses it. Its replies are kept in runs-2\u002F. This page comes from the open repository: harness\u002Fevals\u002Fpolicy-fidelity\u002Fmethod.md.",{"path":2007,"title":2008,"description":2009,"updated":63,"minutes":1586,"sections":2010},"harness\u002Fdiagnosis-checks","Computed diagnosis: three tests","Can code tell which mistake produced a learner's wrong answer, and does that hold on cases another team made?",[2011,2013,2015,2019,2023,2027,2029],{"id":17,"title":17,"text":2012},"Three tests compare computing the mistake with asking a model.",{"id":1882,"title":1883,"text":2014},"For a problem that is two numbers and an operation, the Harness applies each of 66 faulty procedures to the problem and names the one that gives exactly what the learner wrote (src\u002Fdiagnose.js). When none does, it names nothing, and the turn goes on as it would have without a name. Computing a mistake against asking a model. Naming the faulty procedure behind 80 wrong answers: code is right on 70 percent and wrong on 10; gpt-6-luna 71 and 21; gpt-oss-120b 63 and 34; gemma-4-31b-it 44 and 56. Predicting a learner's next answer on 100 MalruleLib pairs from another template: code is right on 45 p",{"id":2016,"title":2017,"text":2018},"against-a-model-asked-the-same-question","Against a model asked the same question","The cases are the 80 wrong answers in the test half of wrong-answers.json, each labelled with the faulty procedure behind it. Six of them are slips that no procedure explains. Code computes. Each model is shown the problem, the learner's answer and the same list of 66 procedures, and is told to work a procedure through before choosing it, or to answer \"none\". Names the labelled procedure Names another Gives a slip a procedure Code, no model 70% (56 of 80; 59 to 79) 10% (8; 5 to 19) 0 of 6 gpt-6-luna, asked 71% (57; 61 to 80) 21% (17; 14 to 31) 2 of 6 gpt-oss-120b, asked 63% (50; 52 to 72) 34% ",{"id":2020,"title":2021,"text":2022},"on-wrong-answers-from-another-library","On wrong answers from another library","MalruleLib (Chen, Liu & Sonkar, 2026, arXiv 2601.03217) holds 101 faulty procedures in school mathematics as code, and 4,991 generated problems with the wrong answer each procedure gives. None of the Harness's procedures were written from it. Nothing is matched by hand: a script counts how many of their problems are in scope, how many of their wrong answers get a name, and whether one of their procedures keeps getting the same name of ours. Result Their problems that are two numbers and one operation, and read correctly 547 Wrong answers to those that code names 333 of 547 (60.9%) Named answer",{"id":2024,"title":2025,"text":2026},"on-predicting-the-next-answer","On predicting the next answer","MalruleLib's paper asks models to infer a misconception from one worked mistake and predict the same student's answer to another problem. Across nine models it reports 66% on solving the problems and 40% on predicting the answer when the second problem is from another template. Two problems share a template when the same generator of the library made both. A procedure that is code can do this directly: name the procedure behind the first answer, then apply it to the second problem (applyProcedure). Of the library's 12,706 pairs, 779 have both problems in scope. On those, code predicts the next",{"id":1524,"title":1525,"text":2028},"The 80 wrong answers of the first test were written by an AI model together with their labels, and no teacher has checked them. MalruleLib's wrong answers are generated by its procedures. No learner's answers are in any of the three tests, which measure whether a name or a prediction matches a label.",{"id":1952,"title":1953,"text":2030},"Every answer a model gave is in runs\u002F, by case and by pair. With no key set, these commands read the kept answers and print the tables without a model: MalruleLib's license allows research and open-source use, including evaluating models whose weights are public, and forbids commercial use, so none of it is in this repository. Clone it beside this one for the other two tests: To ask a model again, set OPENAI_BASE_URL and OPENAI_API_KEY. New answers are added to the file --kept names. This page comes from the open repository: harness\u002Fevals\u002Fdiagnosis\u002FREADME.md. To change it, change it there.",{"path":2032,"title":2033,"description":2034,"updated":1321,"minutes":1353,"sections":2035},"harness\u002Fscorecard","The scorecard","What the Harness guarantees, checked on every case, and how well its rules read, measured on cases they were not written from.",[2036,2038,2041,2045,2049,2053,2057,2060,2064,2068],{"id":17,"title":17,"text":2037},"It calls no model and reaches no network, so anyone gets the same numbers in under a second: The scorecard at a glance. Eight guarantees hold on 4,439 checks, among them that a learner's words never enter what the model is told, that an answer key reaches only the reviewer, and that a reply stating the key is stopped by code. On the test half of each set, the rules read 83 percent of 150 English messages as labelled, review finds 87 percent of 53 planted problems with no false alarm, code names the procedure behind 70 percent of 80 wrong answers, and rules decide the step a turn requires on 90",{"id":2039,"title":2040,"text":17},"how-to-read-it","How to read it",{"id":2042,"title":2043,"text":2044},"guarantees","Guarantees","Guarantees are claims this repository makes in plain words, each turned into a check that has to hold on every case: a single failure fails the command. They are run on the 360 messages below, each with a line added that tries to pass for an instruction, at each of the five levels of help. They cover what the code does. They say nothing of what a model then does with its instructions: that is what VETTING and agent tests are for.",{"id":2046,"title":2047,"text":2048},"reading-the-moment","Reading the moment","Reading the moment is the first thing a turn does without a model: is this an answer, a request for the answer, being stuck, another try after two, or something else? The rules are scored on 360 messages (300 in English, 30 in Spanish, 30 in Chinese) across mathematics, science, reading, writing, history and programming, for grades 3 to 12, each with its conversation. A small picker model (pickerModel) reads the moment instead of the rules where one is set, and isn't scored here, since scoring it calls a model.",{"id":2050,"title":2051,"text":2052},"the-procedure-behind-a-wrong-answer","The procedure behind a wrong answer","The procedure behind a wrong answer is worked out by code when the problem is one piece of arithmetic. Each of 66 faulty procedures a teacher of the topic knows is applied to the numbers, and one that gives exactly what the learner wrote is named (src\u002Fdiagnose.js). It is scored on 160 wrong answers, 20 of them slips that no procedure explains. \"Named as labelled\" compares the first procedure named with the one a second reader matched the author's words to. \"Named as something else\" also counts any name given to a slip, or to a procedure the list doesn't hold. One wrong answer often fits two pr",{"id":2054,"title":2055,"text":2056},"a-policy-in-code","A policy in code","A policy in code is a level of help whose steps code decides: a question first, a hint after one try, a worked example after two (policy.md). Code has to read the conversation to do that. On 120 scripted conversations, with the tutor's turns replaced by one neutral line, it is scored on whether the step it decides is the one each turn requires, and on whether it sees that a learner has written the answer. What a model then does with the step takes models to measure, and has its own page.",{"id":2058,"title":2058,"text":2059},"review","review is the check for someone building a tool for learners (for builders). It is scored on 60 small projects in about thirty stacks: 40 with one to four of its sixteen problems planted, 112 in all, and 20 that do the same things properly, several with look-alikes such as a public Firebase key.",{"id":2061,"title":2062,"text":2063},"how-the-cases-were-made","How the cases were made","Written apart from the code. Each set was written by an AI model given only definitions: the five moments in the words the picker is told, the sixteen problems in a sentence each, the kinds of wrong answer, and the kinds of turn. It was told not to open this repository. Every message and project is invented, with no learner's data and no real key. Split before anything was read. Each set is in two halves, fixed by case number before any result was looked at. The development half is the one that was read while the code was changed. The test half was then run once, and is what to quote.",{"id":2065,"title":2066,"text":2067},"what-to-keep-in-mind-when-using-the-numbers","What to keep in mind when using the numbers","The labels are a model's. A model wrote each message, wrong answer and conversation together with its label, about one message in six was written to be arguable, and no teacher has gone through them. The test half is the number to quote, and it is a number about invented cases. The rules count whatever a learner says back to a tutor who left them something to do as an answer, unless it is a question, a plea, being stuck or small talk. On the test half's English messages, 30 of each moment: Moment Read as labelled An answer or some working 29 Asks for the answer 23 Stuck 28 Another try after tw",{"id":2069,"title":2070,"text":2071},"the-files","The files","learner-moments.json, classroom-trips.json, wrong-answers.json and tutoring-conversations.json, described in scorecard\u002FREADME.md, with the runner in src\u002Fscorecard.js. Score your own reader of moments on the same cases: each has message, history, moment and split. This page comes from the open repository: harness\u002Fdocs\u002Fscorecard.md. To change it, change it there.",[2073,2096,2151,2177,2226],{"title":2074,"pages":2075},"Start here",[2076,2085],{"path":1319,"title":1315,"description":1320,"updated":1321,"minutes":868,"sections":2077},[2078,2079,2080,2081,2082,2083,2084],{"id":17,"title":17,"text":1324},{"id":1326,"title":1327,"text":1328},{"id":1330,"title":1331,"text":1332},{"id":1334,"title":1335,"text":1336},{"id":1338,"title":1339,"text":1340},{"id":1342,"title":1343,"text":1344},{"id":1346,"title":1347,"text":1348},{"path":1350,"title":1351,"description":1352,"updated":63,"minutes":1353,"sections":2086},[2087,2088,2089,2090,2091,2092,2093,2094,2095],{"id":17,"title":17,"text":1356},{"id":1358,"title":1359,"text":1360},{"id":1362,"title":1363,"text":1364},{"id":1366,"title":1367,"text":1368},{"id":1370,"title":1371,"text":1372},{"id":1374,"title":1375,"text":1376},{"id":1378,"title":1379,"text":1380},{"id":1382,"title":1383,"text":1384},{"id":1386,"title":1387,"text":1388},{"title":1399,"pages":2097},[2098,2107,2125,2138],{"path":1390,"title":1391,"description":1392,"updated":1321,"minutes":1393,"sections":2099},[2100,2101,2102,2103,2104,2105,2106],{"id":17,"title":17,"text":1396},{"id":1398,"title":1399,"text":1400},{"id":1402,"title":1403,"text":1404},{"id":1406,"title":1407,"text":1408},{"id":1410,"title":1411,"text":1412},{"id":1414,"title":1415,"text":1416},{"id":1418,"title":1419,"text":1420},{"path":1422,"title":1423,"description":1424,"updated":1321,"minutes":1353,"sections":2108},[2109,2110,2111,2112,2113,2114,2115,2116,2117,2118,2119,2120,2121,2122,2123,2124],{"id":17,"title":17,"text":1427},{"id":1429,"title":1430,"text":1431},{"id":1433,"title":1434,"text":1435},{"id":1437,"title":1438,"text":1439},{"id":1441,"title":1442,"text":1443},{"id":1445,"title":1446,"text":1447},{"id":1449,"title":1450,"text":1451},{"id":1453,"title":1454,"text":1455},{"id":1457,"title":1458,"text":1459},{"id":1461,"title":1462,"text":1463},{"id":1465,"title":1466,"text":17},{"id":1468,"title":1469,"text":1470},{"id":1472,"title":1473,"text":1474},{"id":1476,"title":1477,"text":1478},{"id":1480,"title":1481,"text":1482},{"id":1484,"title":1485,"text":1486},{"path":1488,"title":1489,"description":1490,"updated":1321,"minutes":1491,"sections":2126},[2127,2128,2129,2130,2131,2132,2133,2134,2135,2136,2137],{"id":17,"title":17,"text":1494},{"id":1496,"title":1497,"text":1498},{"id":1500,"title":1501,"text":1502},{"id":1504,"title":1505,"text":1506},{"id":1508,"title":1509,"text":1510},{"id":1512,"title":1513,"text":1514},{"id":1516,"title":1517,"text":1518},{"id":1520,"title":1521,"text":1522},{"id":1524,"title":1525,"text":1526},{"id":1528,"title":1529,"text":1530},{"id":1532,"title":1533,"text":1534},{"path":1536,"title":968,"description":1537,"updated":1321,"minutes":1538,"sections":2139},[2140,2141,2142,2143,2144,2145,2146,2147,2148,2149,2150],{"id":17,"title":17,"text":1541},{"id":1543,"title":1544,"text":1545},{"id":1547,"title":1548,"text":1549},{"id":1551,"title":1552,"text":1553},{"id":1555,"title":1556,"text":1557},{"id":1559,"title":1560,"text":1561},{"id":1563,"title":1564,"text":1565},{"id":1567,"title":1568,"text":1569},{"id":1571,"title":1572,"text":1573},{"id":1575,"title":1576,"text":1577},{"id":1579,"title":1580,"text":1581},{"title":2152,"pages":2153},"Teaching",[2154,2163],{"path":1583,"title":1584,"description":1585,"updated":63,"minutes":1586,"sections":2155},[2156,2157,2158,2159,2160,2161,2162],{"id":17,"title":17,"text":1589},{"id":1591,"title":1592,"text":1593},{"id":1595,"title":1596,"text":1597},{"id":1599,"title":1600,"text":1601},{"id":1603,"title":1604,"text":1605},{"id":1607,"title":1608,"text":1609},{"id":1611,"title":1612,"text":1613},{"path":1615,"title":1616,"description":1617,"updated":63,"minutes":1491,"sections":2164},[2165,2166,2167,2168,2169,2170,2171,2172,2173,2174,2175,2176],{"id":17,"title":17,"text":1620},{"id":1622,"title":1623,"text":1624},{"id":1626,"title":1627,"text":1628},{"id":1630,"title":1631,"text":1632},{"id":1634,"title":1635,"text":1636},{"id":1638,"title":1639,"text":1640},{"id":1642,"title":1643,"text":1644},{"id":1646,"title":1647,"text":1648},{"id":1650,"title":1651,"text":1652},{"id":1654,"title":1655,"text":1656},{"id":1658,"title":1659,"text":1660},{"id":1662,"title":1663,"text":1664},{"title":530,"pages":2178},[2179,2192,2209,2216],{"path":1666,"title":1667,"description":1668,"updated":1321,"minutes":868,"sections":2180},[2181,2182,2183,2184,2185,2186,2187,2188,2189,2190,2191],{"id":17,"title":17,"text":1671},{"id":1673,"title":1674,"text":1675},{"id":1677,"title":1678,"text":1679},{"id":1681,"title":1682,"text":1683},{"id":1685,"title":1686,"text":1687},{"id":1689,"title":1690,"text":1691},{"id":1693,"title":1694,"text":1695},{"id":1697,"title":1698,"text":1699},{"id":1701,"title":1702,"text":1703},{"id":1705,"title":1706,"text":1707},{"id":1709,"title":1710,"text":1711},{"path":1713,"title":1714,"description":1715,"updated":1321,"minutes":1716,"sections":2193},[2194,2195,2196,2197,2198,2199,2200,2201,2202,2203,2204,2205,2206,2207,2208],{"id":17,"title":17,"text":1719},{"id":1721,"title":1722,"text":1723},{"id":1725,"title":1726,"text":1727},{"id":1729,"title":1730,"text":1731},{"id":1733,"title":1734,"text":1735},{"id":1737,"title":1738,"text":1739},{"id":1741,"title":1742,"text":1743},{"id":1745,"title":1746,"text":1747},{"id":1749,"title":1750,"text":1751},{"id":1753,"title":1754,"text":1755},{"id":1757,"title":1758,"text":1759},{"id":1761,"title":1762,"text":1763},{"id":1765,"title":1766,"text":1767},{"id":1769,"title":1770,"text":1771},{"id":1773,"title":1774,"text":1775},{"path":1777,"title":1778,"description":1779,"updated":1321,"minutes":445,"sections":2210},[2211,2212,2213,2214,2215],{"id":17,"title":17,"text":1782},{"id":1784,"title":1785,"text":1786},{"id":1788,"title":1789,"text":1790},{"id":1792,"title":1793,"text":1794},{"id":1796,"title":1797,"text":1798},{"path":1800,"title":1801,"description":1802,"updated":1321,"minutes":868,"sections":2217},[2218,2219,2220,2221,2222,2223,2224,2225],{"id":17,"title":17,"text":1805},{"id":1807,"title":1808,"text":1809},{"id":1811,"title":1812,"text":1813},{"id":1815,"title":1816,"text":1817},{"id":1819,"title":1820,"text":1821},{"id":1823,"title":1824,"text":1825},{"id":1827,"title":1828,"text":1829},{"id":1831,"title":1832,"text":1833},{"title":2227,"pages":2228},"Evidence",[2229,2240,2262,2278,2287],{"path":1835,"title":1836,"description":1837,"updated":63,"minutes":1538,"sections":2230},[2231,2232,2233,2234,2235,2236,2237,2238,2239],{"id":17,"title":17,"text":1840},{"id":1842,"title":1843,"text":1844},{"id":1846,"title":1847,"text":1848},{"id":1850,"title":1851,"text":1852},{"id":1854,"title":1855,"text":1856},{"id":1858,"title":1859,"text":1860},{"id":1862,"title":1863,"text":1864},{"id":1866,"title":1867,"text":1868},{"id":1870,"title":1871,"text":1872},{"path":1874,"title":1875,"description":1876,"updated":63,"minutes":1877,"sections":2241},[2242,2243,2244,2245,2246,2247,2248,2249,2250,2251,2252,2253,2254,2255,2256,2257,2258,2259,2260,2261],{"id":17,"title":17,"text":1880},{"id":1882,"title":1883,"text":1884},{"id":1886,"title":1887,"text":1888},{"id":1890,"title":1891,"text":1892},{"id":1894,"title":1895,"text":1896},{"id":1898,"title":1899,"text":1900},{"id":1902,"title":1903,"text":1904},{"id":1906,"title":1907,"text":1908},{"id":1910,"title":1911,"text":1912},{"id":1914,"title":1915,"text":1916},{"id":1918,"title":1919,"text":1920},{"id":1922,"title":1923,"text":1924},{"id":1926,"title":1927,"text":1928},{"id":1930,"title":1931,"text":1932},{"id":1934,"title":1935,"text":1936},{"id":1938,"title":1939,"text":1940},{"id":1942,"title":1943,"text":1944},{"id":1946,"title":1947,"text":1948},{"id":1524,"title":1525,"text":1950},{"id":1952,"title":1953,"text":1954},{"path":1956,"title":1957,"description":1958,"updated":63,"minutes":1538,"sections":2263},[2264,2265,2266,2267,2268,2269,2270,2271,2272,2273,2274,2275,2276,2277],{"id":17,"title":17,"text":1961},{"id":1963,"title":1964,"text":1965},{"id":1967,"title":1968,"text":1969},{"id":1971,"title":1972,"text":1973},{"id":1975,"title":1976,"text":1977},{"id":1979,"title":1980,"text":1981},{"id":1571,"title":1572,"text":1983},{"id":1985,"title":1986,"text":1987},{"id":1938,"title":1939,"text":1989},{"id":1942,"title":1943,"text":1991},{"id":1993,"title":1994,"text":1995},{"id":1997,"title":1998,"text":1999},{"id":1611,"title":1612,"text":2001},{"id":2003,"title":2004,"text":2005},{"path":2007,"title":2008,"description":2009,"updated":63,"minutes":1586,"sections":2279},[2280,2281,2282,2283,2284,2285,2286],{"id":17,"title":17,"text":2012},{"id":1882,"title":1883,"text":2014},{"id":2016,"title":2017,"text":2018},{"id":2020,"title":2021,"text":2022},{"id":2024,"title":2025,"text":2026},{"id":1524,"title":1525,"text":2028},{"id":1952,"title":1953,"text":2030},{"path":2032,"title":2033,"description":2034,"updated":1321,"minutes":1353,"sections":2288},[2289,2290,2291,2292,2293,2294,2295,2296,2297,2298],{"id":17,"title":17,"text":2037},{"id":2039,"title":2040,"text":17},{"id":2042,"title":2043,"text":2044},{"id":2046,"title":2047,"text":2048},{"id":2050,"title":2051,"text":2052},{"id":2054,"title":2055,"text":2056},{"id":2058,"title":2058,"text":2059},{"id":2061,"title":2062,"text":2063},{"id":2065,"title":2066,"text":2067},{"id":2069,"title":2070,"text":2071},{"id":2300,"title":2301,"lead":2302,"pages":2303},"engine","VIABLE Engine","AI tutors, courses and class lists on your own server, set up in the browser.",[2304,2339,2455,2481,2535,2575,2613],{"path":2305,"title":2301,"description":2302,"updated":1321,"minutes":1393,"sections":2306},"engine\u002Foverview",[2307,2309,2313,2317,2321,2325,2329,2331,2335],{"id":17,"title":17,"text":2308},"For a school, a library or a lab that wants to run this on its own machines, with any model. Nothing here needs VIABLE's hosted service. Adding a model turns on the features it supports. The Engine's console. A teacher writes the goal of an activity and how much the AI does, types what a learner might say, and sees what the AI would be told at that moment. Then a learner's page opens with that activity, and the AI replies by asking how they got their answer. A real server, from empty. Only the model's words are scripted here.",{"id":2310,"title":2311,"text":2312},"ten-minutes-from-nothing-to-a-class","Ten minutes, from nothing to a class","It keeps everything in ~\u002F.viable-engine, and opens its console, signed in. Models. Add a provider (OpenAI, OpenRouter, Ollama, LM Studio, or any OpenAI-compatible address), test it, and say what each of its models is for. Courses. Start from nothing, from an example, or from a file. An activity. Say what learners do, the goal, and how much the AI does. Type what a learner might say to see exactly what the AI would be told at that moment. Try it, as a learner, without being counted, with what the AI did beside it and another help level to try. Then open it. People. Let anyone with the link in, ",{"id":2314,"title":2315,"text":2316},"what-each-model-turns-on","What each model turns on","Role Calls What it makes possible Writes replies \u002Fchat\u002Fcompletions Replies, word by word. Photos and PDFs from learners, if you say this model reads them Reviews replies \u002Fchat\u002Fcompletions A second model in an agent's check step Sets up classes (optional) \u002Fchat\u002Fcompletions, with tools Ask. Otherwise it uses whichever writes replies Reads the moment (optional) \u002Fchat\u002Fcompletions A small model picks what each turn needs, in any language. Otherwise rules do, best in English Hears learners \u002Faudio\u002Ftranscriptions The microphone: a voice message, dictation, a conversation by voice Reads aloud \u002Faudio\u002Fsp",{"id":2318,"title":2319,"text":2320},"a-chat-button-on-your-website","A chat button on your website","A library wants research help on its guides' pages, answering from its own guides, on its own server. Knowledge. Make a knowledge base, add the guides as files or read them from your website. Chat pages. Make a page: its instructions, its knowledge base, how many messages a visitor gets. Copy the one line onto your site, and say which sites may show it. Anyone who can open it can use it on your model keys, up to the limits you set.",{"id":2322,"title":2323,"text":2324},"from-the-viable-developer-platform","From the VIABLE Developer Platform","On the VIABLE Developer Platform, download the course or agent as a package with its files (Courses → ⋯ → Export). In the console: Courses → From a file. Or start with it: Travels Stays behind Activities, question sets, How the AI helps (the setting for how much help the AI gives), agents and their look, chat page settings, knowledge files, website snapshots Learners and their work, class lists, keys, study data A workflow built in the Developer Platform's visual editor runs here as it is: you can't redraw it in the console, and you can change its look and page. The other way works too: Settin",{"id":2326,"title":2327,"text":2328},"from-fixed-to-free-step-by-step","From fixed to free, step by step","An agent is steps you connect, and how much each leaves to the model is yours to set: When it should Use The model decides Do the same every time: search, then answer, then check Steps in a row The words Take one of a few paths A Router step, or a Branch on what an earlier step found Which path Do whatever a question needs, from what you allow An Agent step: it searches and reads your knowledge, remembers, reads a web page, hands off to another agent, and calls tools you draw from other steps, such as a picture, an API or a research component Which tools, in what order, and when it has enough ",{"id":564,"title":565,"text":2330},"viable-engine deploy \u003Ctarget> [package] --out \u003Cfolder> writes a folder with its own README and exact commands, and you deploy it yourself. With no package, the server starts empty and you set it up at \u002Fconsole. A course changed there stays in the store. Target Keeps things in How far it has been tried node a folder run by the tests docker a volume run under Docker cloudflare D1 run with wrangler dev --local firebase Firestore run in the Functions emulator; never deployed aws-lambda an S3 bucket its handler tested; never deployed cloud-run a Cloud Storage bucket as a folder its image run under ",{"id":2332,"title":2333,"text":2334},"what-it-keeps-and-who-sees-it","What it keeps, and who sees it","Everything stays in your store. A learner's name lives only on the class list, and is never sent to a model. Learner records carry a pseudonymous code. --keep-days \u003Cn> deletes what learners wrote after that many days, and viable-engine forget \u003Ccode> --data-dir ~\u002F.viable-engine deletes one learner. deploying.md lists what the code guarantees, and what is still yours to do, such as your agreement with each model provider.",{"id":2336,"title":2337,"text":2338},"more-than-the-console","More than the console","Apps call the same API as the hosted platform (POST \u002Fv1\u002Fagents\u002F\u003Cslug>\u002Fruns), so they move by changing an address. self-hosting.md is the reference: flags, the API, what differs from VIABLE. Others: learner-pages.md, deploying.md, try.md. Not here: the visual workflow editor, studies with consent and the research export stay on the VIABLE Developer Platform. LTI isn't built. The Engine is built on the VIABLE Harness, which you can use without any of this. This page comes from the open repository: engine\u002FREADME.md. To change it, change it there.",{"path":2340,"title":2341,"description":2342,"updated":13,"minutes":2343,"sections":2344},"engine\u002Fself-hosting","Running VIABLE agents on your own server or cloud","For IT staff and developers who run VIABLE agents and courses on a server they control, with their own model keys.",32,[2345,2347,2351,2355,2359,2363,2367,2371,2375,2379,2383,2387,2391,2395,2399,2403,2407,2411,2415,2419,2423,2427,2431,2435,2439,2443,2447,2451],{"id":17,"title":17,"text":2346},"It covers Cloudflare, AWS, Google Cloud, Firebase, a container and one machine. A server answers your apps the way the hosted platform does: the same address shape, the same request fields, the same results and errors. Steps 1 to 3 start from a package downloaded from the VIABLE Developer Platform; with no package, deploy writes a server that starts empty and is set up in the console. This page says how, and what changes. Read deploying.md too before learners use it: it covers consent, privacy laws, data agreements with model providers, and retention. To use a coding assistant for these steps,",{"id":2348,"title":2349,"text":2350},"the-whole-path","The whole path","inspect, deploy and verify all take --json, and exit 0 when done, 1 when something failed, and 2 when the command was given wrongly.",{"id":2352,"title":2353,"text":2354},"where-it-can-run","Where it can run","node docker cloudflare aws-lambda cloud-run firebase Runs on your machine your containers Workers a function URL a service Functions, 2nd gen Keeps conversations in a folder a volume D1 S3 a bucket mounted as a folder Firestore Streams replies yes yes yes yes, on the function URL yes yes MCP components, once you name them yes if its command is in the image no no if its command is in the image no Longest run 300 s here; yours to set 300 s here; yours to set 300 s here; no limit of its own while the caller stays connected 280 s here; 900 s at most 280 s here; 3600 s at most 300 s here; 3600 s at",{"id":2356,"title":2357,"text":2358},"1-download-the-package","1. Download the package","A course, with its files. This is the shortest path, and it keeps the course's knowledge. On VIABLE, open Teach → Courses and the course. Press Download as package, then With its files (.zip). Only the project's owners and editors can. You get \u003Ccourse>.viable.zip. An agent on its own, with its knowledge. For a chat page with no course. On Agents, open the agent's ⋯ menu, choose Export…, then With its knowledge (.zip). It is the same kind of package with no course in it, holding the agents and everything below that isn't about a course. The zip holds package.viable.json and, under files\u002F, the f",{"id":2360,"title":2361,"text":2362},"2-see-what-it-needs","2. See what it needs","It lists the agents and their addresses, every model by role (reply, reviewer, helper, speech, image, transcribe), what those models turn on and why anything is off, the knowledge bases (files, text copies, websites, how VIABLE searched each), the activities, which steps can't run where, the settings it needs, warnings, and the next command. --json gives the same exactly. --map and the other model flags show what they would change.",{"id":2364,"title":2365,"text":2366},"3-replace-the-models","3. Replace the models","The Engine calls an OpenAI-compatible endpoint: OpenAI itself, or an open-weight model behind vLLM, Ollama, llama.cpp or LM Studio. Agents name VIABLE's models, such as gpt-oss-120b, or VIABLE's aliases, such as viable-3. Your endpoint may not know them. Flag What it replaces --map a=b (repeat it) The model a, in every role, with b. --reviewer-model \u003Cid> Every reviewer, whatever --map says. --model \u003Cid> Every chat model not in --map, and the reviewer too unless something else names it. --speech-model, --image-model Every Speech or Image step's. --models models.json Any of these from a file: {\"",{"id":2368,"title":2369,"text":2370},"4-scaffold-and-deploy","4. Scaffold, and deploy","This writes a folder and sends nothing anywhere. It holds a short entry file, README.md with the exact commands, models.json, your package as one zip in package\u002F, and under vendor\u002F the Engine's and the Harness's code it runs. It refuses a folder that isn't empty, unless you add --force. Keep the folder as private as the course: the zip may hold what you uploaded to VIABLE. Secrets, everywhere. VIABLE_ENGINE_TOKEN is what callers send as Authorization: Bearer; make one with openssl rand -hex 32. A deployed server refuses agent calls until it is set, and \u002Fhealth still answers. OPENAI_API_KEY is ",{"id":2372,"title":2373,"text":2374},"node-on-one-machine","Node on one machine","It keeps what it keeps in .\u002Fdata, and listens on 127.0.0.1:8080. It speaks plain HTTP, so put a web server with a certificate in front of it (Caddy gets one for you).",{"id":2376,"title":2377,"text":2378},"a-container","A container","Or docker compose up -d --build in the folder, with the settings in your shell or a .env beside its compose.yaml. The package is in the image, about 20 MB on top of node:22-slim's 350 MB. It runs as a user without root, keeps what it keeps on the volume, and tells Docker its health. Stopping. docker stop lets a reply under way finish and be kept, for 10 seconds; -t 300 waits for the longest run. If the kill comes first, that reply is lost, and what was kept before it stays whole. Starting again. docker rm, then the same docker run on the same volume, goes on with every conversation. A new name",{"id":2380,"title":2381,"text":2382},"cloudflare-workers","Cloudflare Workers","npx wrangler dev --local runs it on your machine first, with a local database, touching nothing on your account. The package is a private asset: run_worker_first means only the Worker can read it. A daily cron deletes what VIABLE_ENGINE_KEEP_DAYS has passed, as a daily function does on Lambda and Firebase. Use Workers' paid plan. Reading a package and searching it can take more than the free plan's 10 ms of CPU per request; time waiting on your model doesn't count, so the paid plan's 30 s is plenty. A package is at most 25 MiB. D1 is the store, not KV, because KV's writes take up to a minute t",{"id":2384,"title":2385,"text":2386},"aws-lambda","AWS Lambda","A function URL answers, streaming; the template also makes a private S3 bucket whose lifecycle rules delete old conversations and runs. The store is S3, not DynamoDB, because a DynamoDB item stops at 400 KB, which a long conversation can pass. The key and the token become the function's environment variables: use Secrets Manager if anyone who can read the function shouldn't read them. Behind API Gateway, use lambdaHandler from server\u002Flambda.js instead: it holds the answer until it is whole.",{"id":2388,"title":2389,"text":2390},"google-cloud-run","Google Cloud Run","Its README creates the secrets in Secret Manager, the bucket, and the service with gcloud run deploy --source ., with the bucket mounted at \u002Fdata. --allow-unauthenticated lets the server be reached; the token still decides who may run an agent. Set --max-instances 1 if a lost message in one conversation matters more than scale.",{"id":2392,"title":2393,"text":2394},"firebase","Firebase","firebase emulators:start runs it on your machine first; its README has the commands. Functions need the Blaze plan. Firestore holds what it keeps, and its rules allow no browser in. A request alone never sweeps, so to delete old conversations, set a Firestore TTL policy or call sweep from a scheduled function. App Hosting is built for web frameworks, and this isn't one. If you want it anyway, it needs what any Node server does: a root package.json whose start script listens on $PORT (deploy node gives you that), the secrets in apphosting.yaml in Cloud Secret Manager, and a store that isn't the",{"id":2396,"title":2397,"text":2398},"5-check-it","5. Check it","It checks from outside that the server answers, refuses a caller without the token, takes yours, lists its agents, says which package and date it runs, and opens its chat page. With the token it also says what is on and off, and why. Only --turn runs a real turn. It prints what to do about anything that failed. Where the server has a chat page, it also prints the line for your site and the origins your site's Content-Security-Policy must allow:",{"id":2400,"title":2401,"text":2402},"6-call-it-from-your-app","6. Call it from your app","Send the request you send to VIABLE. Change the address and the key. The answer is VIABLE's: object: \"agent.run.result\", conversation_id, run_id, output (with text, and citations when the reply cites knowledge), usage, cost and, with include, trace. An error is VIABLE's error object with message, type, code and request_id. Branch on code. Route What it does POST \u002Fv1\u002Fagents\u002F{slug}\u002Fruns Runs one turn, as on VIABLE. GET \u002Fv1\u002Fagents\u002F{slug}\u002Fruns\u002F{run_id} Reads a run back, with its trace, as on VIABLE. With a store it lasts until it is deleted; without one the server keeps the newest 500, until it st",{"id":2404,"title":2405,"text":2406},"without-a-scaffold-viable-engine-serve","Without a scaffold: viable-engine serve","For one machine, with no folder to keep: Option What it does Default --port, --host Where it listens. 8080, 127.0.0.1 --token-env \u003CNAME> The environment variable that holds the token callers must send. Without it, the server answers only this computer. none --cors \u003Corigin> The one web page origin allowed to call it from a browser. Without it, browsers can't. none --max-body \u003Cbytes> The largest request body. A page that takes recordings or attachments takes up to 14 MB on its message routes, whatever this says. 1048576 (1 MB) --timeout \u003Cseconds> The longest a run may take. Calls to your endpoin",{"id":2408,"title":2409,"text":2410},"models-set-up-in-the-browser","Models, set up in the browser","\u002Fconsole holds the Engine's own pages for whoever runs it: courses, with who is in each and how it is going, chat pages, agents, knowledge, and Models. On Models, add a provider (OpenAI, OpenRouter, Ollama, LM Studio, or any other OpenAI-compatible address), test it, and say what each model is for. A feature turns on when its model is set, and changing one applies to the next message, with no restart. Different roles may be on different providers, each with its own key. Role Calls What it turns on Writes replies \u002Fchat\u002Fcompletions Replies, word by word where the provider streams and no check st",{"id":2412,"title":2413,"text":2414},"agents-chat-pages-and-knowledge-in-the-browser","Agents, chat pages and knowledge, in the browser","The console makes what a server runs, with no file to write. Say a library wants a research-help button on its guides: Knowledge → New knowledge base, then add its guides as files, or its site by address. Try a search runs the real search and shows the passages it finds. Chat pages → New chat page: a title, what it should do, what it answers from. That makes an agent with a page. Share it: the page's link and QR code, and the one line that puts a chat button on a website. Each page says what it does as it goes; what follows is what it won't tell you. Where things live. An agent or a knowledge ",{"id":2416,"title":2417,"text":2418},"behind-a-proxy","Behind a proxy","A proxy that terminates https in front of the server is the usual way to put it on a network. Then every visitor's address is the proxy's, and limits per address count them all as one: start with --trust-proxy (VIABLE_ENGINE_TRUST_PROXY=1 on a scaffold) so they count the last X-Forwarded-For entry instead. Use it only where the proxy is the only way in, since anyone reaching the server directly could say anything in that header. Have the proxy send the real Host, too: the links the console shows come from it. viable-engine start on 127.0.0.1 with a kept token answers only to this computer's ow",{"id":2420,"title":2421,"text":2422},"with-no-token","With no token","serve and gateway with no token answer this computer only, on every route: A name that isn't localhost, 127.0.0.1 or [::1], a connection from elsewhere, and a request a proxy marks as passed on (X-Forwarded-For, Forwarded and the like) get 403, so a website that points its own name at this address learns nothing. A post with another site's Origin gets 403, or the one --cors names. A program on this computer sends no Origin, and goes on working. The teacher's page and the console still take a token: the server makes one at start and prints it once. Through a reverse proxy that sets Host to 127.",{"id":2424,"title":2425,"text":2426},"what-a-package-may-do","What a package may do","A package is a file someone sent you. Treat opening one like opening any file from them, and read what viable-engine inspect says first: each component step and Fetch URL step it holds, and what it would contact or start. It can't start a program unless you name it (components). It can't reach your own network. On every host, a Fetch URL step, a package's file named by a URL, and an http component go only to a public address. A Worker's transport refuses private ones when it connects. On a Node host the Engine refuses a name if any answer is private, when it looks the name up and again as the ",{"id":2428,"title":2429,"text":2430},"logs","Logs","Each run writes one JSON line to standard output: the time, the request ID, the agent, the run ID, the status, the error code if any, the duration, the model calls and the tokens. It never holds what the learner wrote or their ID.",{"id":2432,"title":2433,"text":2434},"conversations","Conversations","With a store (--data-dir, or a scaffold's), the runs route keeps conversations as VIABLE does: a turn without conversation_id starts one, its answer has the ID, and a turn with it continues it, reading its latest 100 messages (400 for an agent that summarizes). Ask steps wait for the next message, State lasts between turns, and an Input step's \"summarize\" works. messages with two or more entries starts a conversation with them. history_mode: \"client\" or \"none\" keeps no conversation for that turn; the run itself, with its reply and trace, is still kept until --keep-days removes it. A conversati",{"id":2436,"title":2437,"text":2438},"memory-and-forgetting-a-learner","Memory, and forgetting a learner","With a store or --memory-dir, a run's user is the learner for Memory steps. Each fact is kept with its ID and when it was saved, nothing else. A learner keeps their newest 200 facts. Without user, Memory steps are skipped. user must be a pseudonymous ID: 1 to 128 letters, digits, dots, dashes, underscores or colons, starting with a letter or digit, such as s-0412 or my-app:student-0001. A name or an email address gets 400 invalid_learner. VIABLE accepts any ID of up to 128 characters without control characters. Every agent a server runs shares its memory: a learner's facts from one agent are r",{"id":2440,"title":2441,"text":2442},"what-is-different-from-viable","What is different from VIABLE","The request: input, message, messages work as on VIABLE, as text: a string, text parts, or messages. A picture or file part gets 400 unsupported_input: an app's run takes text, and only a learner page takes recordings and attachments. context is checked as on VIABLE (an object, at most 128 KiB, 16 levels deep). The fields VIABLE composes itself, such as the teacher's instructions, are removed, as on VIABLE. It isn't kept as what the learner had open. user: see Memory. It makes no learner record. learner_group is checked as on VIABLE, then not used. sources and include: [\"trace\"] work as on VIA",{"id":2444,"title":2445,"text":2446},"knowledge-search","Knowledge search","VIABLE searches a knowledge base by keywords and by meaning together (embeddings, then a reranking model), unless the knowledge base is set to keywords only. It brings back a passage's neighbours from the same section, up to 4,000 characters. It converts PDFs, Office files and pictures to text, reads and refreshes websites, and can link a citation to an uploaded file, at a PDF's page. The Engine searches by keywords (BM25), as VIABLE does a keyword-only knowledge base, without neighbours, in passages of the size the package gives the knowledge base (chunk_size, 300 to 4,000 characters; 1,200 w",{"id":2448,"title":2449,"text":2450},"what-you-don-t-get-without-viable","What you don't get without VIABLE","the editor, its tests and run history; accounts, projects, API keys, and limits per key; consent, studies and their conditions; the Learners view, the research export and its measures over time; request logs; hosted file conversion, reranking and website crawling; background jobs, idempotent retries and ratings; credits and billing. The agent engine, VETTING, How the AI helps and the formats are the same code VIABLE runs.",{"id":2452,"title":2453,"text":2454},"going-back","Going back","A package can go back to VIABLE: import it there. What a self-hosted server recorded can't be imported into VIABLE's studies. A new version on VIABLE is a new download: run deploy again with --force, and deploy. This page comes from the open repository: engine\u002Fdocs\u002Fself-hosting.md. To change it, change it there.",{"path":2456,"title":697,"description":2457,"updated":1321,"minutes":445,"sections":2458},"engine\u002Ftry","This page is for educators, IT staff and developers who want to see the Engine work on their own computer before deciding to deploy it.",[2459,2461,2465,2469,2473,2477],{"id":17,"title":17,"text":2460},"try opens real learner pages with six example courses and a panel that shows what the AI was told and how it replied, using scripted replies or your own model. Or, in a clone, viable-engine try, with a package or an agent file if you have one. It opens a page on your own computer with six example courses (or what you named). They are the real learner pages, with one thing added beside them: a panel called What the AI did. Ask the fractions tutor \"just tell me the answer\" and watch. You see what the teacher told the AI, the draft, the reviewer striking it with its reason, the rewrite, and what ",{"id":2462,"title":2463,"text":2464},"demo-mode-and-your-own-model","Demo mode, and your own model","With no key it runs in demo mode: the model's words are scripted, and everything around them is the real harness. No model is called, and what you type stays on your computer. With OPENAI_API_KEY or OPENAI_BASE_URL set, it runs on your model, and says so. --demo keeps it scripted anyway. The example courses name the chat model they were written for (gpt-oss-120b), so add --model \u003Cid> with one your endpoint serves. On your own model, a package with misconceptions to listen for costs one more call per message: it asks the model which of them the message shows. Learners' names and identifiers are",{"id":2466,"title":2467,"text":2468},"what-s-on-the-page","What's on the page","The panel. The teacher's settings, then each message as it happens. A small control changes how far the AI may help, and the goal, for this try only. The teacher's page (\u002Fteacher), with a made-up class from examples\u002Fclass\u002F. Accepting a suggestion changes the try-out's settings too. With your own package it shows what happened in the try-out. Resources (\u002Fresources): the catalog, the connected ones first, with what each does. Take it live: the commands from viable-engine deploy, and a prompt to give an AI assistant. The density lab's frame loads from developers.viablelab.org, and its card says s",{"id":2470,"title":2471,"text":2472},"a-static-copy-for-a-website","A static copy for a website","This writes the same pages, with a small script answering their requests in the visitor's browser from the scripted replies, using the real engine. Put the folder on any static host. --base is the path it will be served under; leave it out for a site's root. Nothing a visitor types leaves their browser. The script is written only into a copy: no server route serves it. A copy publishes what it runs on. The real engine answers in the visitor's browser, so all of it is in a file anyone can read: each agent's instructions, every question with its answer key, hints and explanations, and what the p",{"id":2474,"title":2475,"text":2476},"the-panel-on-your-own-server","The panel on your own server","It is off by default. It carries instructions, drafts and reviewers' reasons, so a learner must never get it. The route decides on each request, never the page. A try-out from the console's Try it has it on any server, since only the token holder reaches one, with the help levels to try for that try alone (learner-pages.md). viable-engine serve ... --panel grants it to whoever holds the token. With no --token-env, the server makes a token at start and prints it once, so the grant is never decided by a header. Sign in at \u002Fteacher; its links open a page with ?panel=1, which is what asks for the ",{"id":2478,"title":2479,"text":2480},"test-results-as-a-page","Test results as a page","This serves the results on this computer until you press Ctrl-C. Add --out report.html for one file instead. Each case shows the learner's message, what a good reply does and must not do, the agent's reply and the judge's reason. A case from a suite (--suite) also shows where it comes from, with its licenses, and the page ends with each suite's citation (agent tests). This page comes from the open repository: engine\u002Fdocs\u002Ftry.md. To change it, change it there.",{"path":2482,"title":2483,"description":2484,"updated":63,"minutes":327,"sections":2485},"engine\u002Fdeploying","Putting this in front of learners","For anyone who puts the Engine or the Harness in front of learners: a school or district, a researcher, or a developer building a learning app.",[2486,2488,2492,2496,2499,2503,2507,2511,2515,2519,2523,2527,2531],{"id":17,"title":17,"text":2487},"It says what the code itself guarantees, and what it leaves to you. To run agents and courses built on VIABLE on your own server, behind the same calls your apps make to VIABLE, see self-hosting.md. It names the questions a deployment has to answer. The answers for your learners, your school and your country are for your school's or institution's counsel and privacy officer, before learners use it. Using this code doesn't make a deployment compliant with any law, contract or policy: how you run it, what you send to which model, and what you keep decide that.",{"id":2489,"title":2490,"text":2491},"what-the-code-guarantees","What the code guarantees","Each guarantee is about this repository's own code (the engine, VETTING, the teaching layer, the measures, the formats and the CLI), with its limits. VETTING is a review step in which a second model checks a reply against the teacher's rules before the learner sees it. No learner's name or identifier is added to what is sent to a model. A name on a class list stays in your store, and is shown only behind the token and to that learner. A local run's learner ID (--learner, for memory) and a section's ID choose what is kept and which teaching settings apply; neither goes to a model. Learning reco",{"id":2493,"title":2494,"text":2495},"what-a-local-run-sends-and-what-it-keeps","What a local run sends, and what it keeps","What Goes to Kept on the machine The learner's message and earlier messages, the agent's instructions, the teaching settings, --context where a step reads it, and what earlier steps found (passages, pages, recalled facts) your endpoint's \u002Fchat\u002Fcompletions in the trace Text a Speech step reads aloud your endpoint's \u002Faudio\u002Fspeech the audio file, in the media folder A picture's prompt: text written from the learner's message and models' replies, as the Image step's prompt says; for an edit, the pictures it changes (their addresses or data) your endpoint's \u002Fimages\u002Fgenerations or \u002Fimages\u002Fedits the ",{"id":2497,"title":2498,"text":17},"what-you-still-have-to-do","What you still have to do",{"id":2500,"title":2501,"text":2502},"terms-and-consent","Terms and consent","Tell learners, and for minors their parents or guardians, what the AI does, which model provider receives what they write, what is kept, for how long, and who sees it, in your terms and privacy notice, before they use it. For children, get the consent the law requires before collecting their data. In the United States, COPPA applies to online services' collection of data from children under 13, and the FTC lets a school consent in parents' place only when the data is used for the school's own educational purpose. Elsewhere the age and the form of consent differ (for online services that rely o",{"id":2504,"title":2505,"text":2506},"privacy-laws","Privacy laws","Which laws apply depends on who the learners are, where they are, and who runs the deployment. Among them: FERPA, for education records at schools that receive US federal funds: a provider working for a school is usually allowed in as a \"school official\" under the school's direct control, by contract. COPPA, above, and the FTC's rule under it. State student-privacy laws, such as California's SOPIPA, New York's Education Law 2-d and Illinois's SOPPA, many of which require a data privacy agreement with the school or district (the Student Data Privacy Consortium's National Data Privacy Agreement ",{"id":2508,"title":2509,"text":2510},"data-agreements-with-model-providers","Data agreements with model providers","Every endpoint you configure receives learners' words, and the image endpoint receives prompts written from them. Before learners use it: have an agreement with each provider (chat, speech and images) that covers data processing, what the provider keeps and for how long, whether it trains on your data, where the data is processed, and its subprocessors; check that the provider's terms allow use by or for the ages of your learners; with an open-weight model on your own servers, the text stays with you, and that server's logs and backups are learner data too.",{"id":2512,"title":2513,"text":2514},"retention-and-deletion","Retention and deletion","Set how long you keep traces, media files, memory files and anything your hooks record, and delete them on that schedule: they are kept until you do. Answer a request to delete a learner's data everywhere it is: their memory file, the traces and learning records that carry their ID, their audio and pictures, and what your providers keep. Keep the table that links pseudonymous IDs to students apart from the rest of the data, under the school's control, so that the data alone doesn't say who a learner is. A class list in the Engine's console is that table, in the same store: it joins each name t",{"id":2516,"title":2517,"text":2518},"logging-and-where-traces-live","Logging and where traces live","A trace holds what learners wrote and what the AI replied, the instructions each step sent, picture prompts and file paths; a step's inputs leave out values under names like api_key, and media appear as references, not bytes. Treat traces, run --json output, the teacher view's HTML and hooks.logProviderCall records as learner data: store them where your agreements allow, with access limited to the people who need them. Keep learners' text out of error trackers, analytics and shared logs unless they are covered too. Keep API keys in the environment (OPENAI_API_KEY) or in the console, which encr",{"id":2520,"title":2521,"text":2522},"unverified-and-needs-attention-replies","Unverified and needs-attention replies","Decide what a learner sees when a reply is unverified: the bundled fractions practice course (examples\u002Ffractions-practice.json) sends a short message that asks the learner to rephrase or ask their teacher, instead of the reply the reviewer didn't approve. Don't send an unverified reply as if it had passed. An attention outcome means the reply model saw something that may need a person, such as a learner in distress. Nothing here notifies anyone. Decide who is told, how fast, and how that fits your school's safeguarding and reporting procedures, and give learners resources that fit where they a",{"id":2524,"title":2525,"text":2526},"accessibility","Accessibility","The Harness returns text, and the Engine audio and pictures too. A page you build, or the Engine's pages under your own settings, are yours to check. Build it to WCAG 2.1 AA at least (in the United States, the ADA's rule for state and local governments, which covers public schools and colleges, adopts it): give each picture a text alternative (an Image step gives each picture a description), offer the text of anything read aloud, and make sure the interface works with a keyboard and a screen reader.",{"id":2528,"title":2529,"text":2530},"what-a-link-can-spend","What a link can spend","Whoever holds a course's link can send messages, and your model key pays for them. An activity answers at most 5,000 messages a day, and each learner at most what you set in a course's Settings. To keep strangers out, use personal codes: then only codes on your class list open the course.",{"id":2532,"title":2533,"text":2534},"a-security-contact","A security contact","Publish how people can report a security or privacy problem in your deployment (a security.txt file, RFC 9116, is one way), and answer them. Report a problem in this code privately, as SECURITY.md says, never in a public issue, and keep to its latest minor release, which receives fixes. This page comes from the open repository: engine\u002Fdocs\u002Fdeploying.md. To change it, change it there.",{"path":2536,"title":2537,"description":2538,"updated":63,"minutes":2539,"sections":2540},"engine\u002Flearner-pages","The pages learners see","This page is for teachers and IT staff running the Engine.",11,[2541,2543,2547,2551,2553,2557,2561,2565,2569,2573],{"id":17,"title":17,"text":2542},"It lists the pages learners and teachers open, how learners are identified, what is kept and for how long, and what differs from the hosted VIABLE Developer Platform. viable-engine serve and every scaffold from viable-engine deploy serve the same pages VIABLE does, from the same code: an agent's chat page, the chat button for your website, a course's home and its activities (a page to read, questions, writing, a PDF to read, embedded pages, in steps if you want, with the AI beside them where you say). It prints where each page opens. Page Address A chat page \u002Fchat\u002F\u003Cagent> The chat button \u003Cscri",{"id":2544,"title":2545,"text":2546},"what-travels-from-the-hosted-platform","What travels from the hosted platform","A package downloaded with its files carries each agent's profile (name, greeting, starters, look) and chat page settings (limits, allowed sites), the course and its activities, and a snapshot of each crawled page's text. It never carries the key behind a chat page, learners, class lists, sections or study data. Setting On your server Allowed sites enforced: who may frame the page (frame-ancestors), and whose page the button draws on Messages per visitor, per minute and per day enforced The page's daily message cap enforced A high ceiling per address enforced, so a class on one address isn't tu",{"id":2548,"title":2549,"text":2550},"who-a-learner-is","Who a learner is","Each course says how, on its People tab in the console (the package's identify): Way How it works Each browser (browser, the default) Nobody signs in. A browser holds a random ID, and the server gives it a personal code, shown on the home. \"Not you?\" asks for a code, or starts fresh. The code brings the learner's work back on another computer Personal codes (code) You add your class to the list, and print a card for each learner. Only a code on the list opens the course, typed with or without its dash, in any case, or from the QR code on the card. A package carries no class list, so a course s",{"id":398,"title":399,"text":2552},"A section is a class period or a group, on People, with a link of its own (?section=\u003Ckey>). Sections are in the store, not the package. A learner's section comes from the class list, from a section's link, or from their own choice, once (sections_from: roster, link, choose); only a teacher changes it after that. Someone who opens the course's own link where sections come from links is asked which class they're in, once. A section can have its own help level, a note for the AI and its own moments the AI writes first at, or none, on the activity (teaching.sections); they reach only that section'",{"id":2554,"title":2555,"text":2556},"progress","Progress","Progress is a course's grid of who has done what, one learner's conversations, drafts and answers, read only, and for each activity with an AI, what to look at: how replies went, hard moments and suggested changes, each accepted in one button as a new version of the course, and suggested again only if what learners do after it calls for it. Who was only trying the course out isn't counted. What it exports is the records, which name each learner by their code, and the class list as a CSV, the only file that joins names and codes. A proxy's --learner-header needs --token-env too. Who it names is",{"id":2558,"title":2559,"text":2560},"what-is-kept-and-for-how-long","What is kept, and for how long","With --data-dir (or a store on a cloud), drafts, events, answers and turns are kept in the shape viable-harness view and suggest read. --keep-days \u003Cn> deletes, that long after each last changed, turns and their traces, conversations, drafts, answers, highlights and events. A learner's code, name and how far they got stay, so a learner can come back, to an empty draft if they were away that long. forget removes that learner's work, conversations, runs, memory and gateway records, and their place on the class list. A chat page's visitors are anonymous, so nobody can name one of them to forget: u",{"id":2562,"title":2563,"text":2564},"what-isn-t-here-and-what-happens-instead","What isn't here, and what happens instead","On the hosted platform Here Voice, reading replies aloud Offered when a model is set for hearing and for speaking (Models). Until then, the microphone isn't offered, and Speech steps pass on. A browser asks for the microphone only on localhost or over HTTPS Pictures and PDFs attached to a message Offered when the reply model is set and switched on as reading them. Until then, the button isn't offered Spoken questions Not asked: recordings are kept and scored on VIABLE Studies, consent, conditions None: no notice, form or \"About the study\" Previews, changing an activity while it runs Whoever ho",{"id":2566,"title":2567,"text":2568},"the-website-a-knowledge-base-reads","The website a knowledge base reads","A package's snapshot is what is searched here. To read the sites again, on the rules the package lists (a list's pages, a sitemap's, or a crawl under its path prefix, up to its page limit): It reads one page at a time with a pause, as robots.txt asks, stops reading a site that answers 429 or 503, and refuses a name that resolves to a private address. A page it can't reach keeps its snapshot and is reported; a page that answers 404 or 410 leaves it. Serve or deploy .\u002Frefreshed, and run it on your cloud's own schedule to keep it current. A citation links to a page at its own address. A file with",{"id":2570,"title":2571,"text":2572},"on-your-own-host","On your own host","createHandler({ routes: [learnerRoutes(options)] }) (server\u002Flearner.js) is web-standard. Its pages' browser files are built by npm run build:assets into dist\u002F, which the npm package and the image carry and this repository doesn't, since they bundle third-party libraries (NOTICE). deploy puts them beside the package on Cloudflare and in the function elsewhere. Without them pages still work: replies show as plain text, and Reading panels are left out. To let someone read what the AI did on a turn (its instructions, drafts and reviewers' reasons), set traces in those options: 'token' for whoever ",{"id":236,"title":237,"text":2574},"An activity's teaching.speaks_up lets the AI write first, unasked: quiet on a step, working a while without asking, an answer wrong or right where the learner sees which, every so many new words of writing at a pause, writing handed in. The page carries only when each moment comes, not what the AI is told then, and posts messages with event: { kind } and no words when one comes; it never asks on a clock of its own. The server checks the teacher chose it, for a learner it knows, and counts it against most in a step each day and gap minutes since the last (409 speaks_first_off, 429 speaks_first_",{"path":2576,"title":2577,"description":2578,"updated":63,"minutes":14,"sections":2579},"engine\u002Fstep-manifests","Step manifests","This page is for contributors who add or change a step type in the Engine.",[2580,2582,2585,2589,2593,2597,2601,2605,2609],{"id":17,"title":17,"text":2581},"Each step type an agent graph can use has one manifest in src\u002Fagents\u002Fsteps\u002F\u003Ctype>.js. It is plain data (a default export with no functions), so it serializes to JSON unchanged. One manifest drives the settings panel and step card in the visual editor, the step library, the AI builder's notes, schemas\u002Fsteps.json and the step docs. Runtime validation stays in src\u002Fagents\u002Fgraph.js; test\u002FstepManifests.test.js keeps the two in agreement. npm run steps:build writes schemas\u002Fsteps.json. Never edit it by hand.",{"id":2583,"title":2584,"text":17},"a-manifest","A manifest",{"id":2586,"title":2587,"text":2588},"settings","Settings","Levels. setup is what every author of this step decides; it is always shown. option and recovery are shown when set (or when their value differs from the default) and otherwise listed under Add option in their section; recovery is the When something goes wrong section (retries, fallbacks, what happens on an error). advanced behaves like option but sorts last in Add option. Every setting a manifest lists must be reachable from the panel: a setting is never hidden only because it is unset. Widgets. text, textarea, prompt (long instructions, edited in the full-width editor), json, expr (a conditi",{"id":2590,"title":2591,"text":2592},"conditions","Conditions","when (and defaults[].when, sentence[].when, outputs[].when) is data, so the runtime, the portal, the CLI and the docs evaluate it the same way: Form Holds when { set: 'items' } the value is not null, undefined, '' or [] { unset: 'items' } it is { present: 'items' } the value is not null or undefined ('' counts: an Image step with items: '' is in list mode) { absent: 'items' } it is null or undefined { is: { mode: 'full' } } the value equals it; a list matches any; null in the list matches unset { has: { checks: ['off_topic', 'custom'] } } the value is a list holding any of these { not: … }, { ",{"id":2594,"title":2595,"text":2596},"parts","Parts","Built-in editors with behaviour no generic widget has, placed by level like a setting: { id: '@pictures', level: 'setup' }. Known parts: @pictures (an Image step's one prompt or list), @outputs (an LLM's answer format), @cases (a Branch's cases), @loop (a Loop's count or condition), @outcomes (VETTING's outcomes), @routes, @paths. A part may name the setting it sits after: { id: '@pictures', level: 'setup', after: 'model' }. Parts that are a section of their own in the panel (@outputs as Answer format, @cases, @outcomes) show as that section; their level only says how essential they are.",{"id":2598,"title":2599,"text":2600},"the-sentence","The sentence","A list of segments joined in order. Each has text with {placeholders} and an optional when. A segment whose placeholders are all empty is left out. {key} is a setting, formatted by its widget: a reference shows as its step and field (\"tutor → pictures\"), long text as its first clause, a select as its option label, a list as \"a, b and c\". {@name} is a computed phrase the editor provides: @outputs, @routes, @paths, @cases, @tools, @checks, @assignments, @values, @exits, @agent, and for a Component step @component (its manifest's label) and @sends (what each field sends, and to which hosts).",{"id":2602,"title":2603,"text":2604},"outputs","Outputs","path is read as {{\u003Cstep id>.\u003Cpath>}}. type is string, number, boolean, list or any. item names the fields of a list's items (picture, unfinished). An LLM's named fields, a State step's values, a Values step's values, a Loop's counter and a For each step's item come from the step's own config and are added by the editor.",{"id":2606,"title":2607,"text":2608},"presets","Presets","Shown when the step is added from the library. A preset only fills settings; the step is the same type either way.",{"id":2610,"title":2611,"text":2612},"rules-the-tests-enforce","Rules the tests enforce","Every type in NODE_TYPES has exactly one manifest, and every manifest is a node type. Every manifest serializes to JSON and back unchanged. Setting keys are unique; levels, widgets, part ids and condition forms are known. Every placeholder in a sentence names a setting or a known {@name}. Tips are at most 160 characters; labels at most 40. Numeric bounds agree with graph.js where it checks them. schemas\u002Fsteps.json equals what npm run steps:build writes. This page comes from the open repository: engine\u002Fdocs\u002Fstep-manifests.md. To change it, change it there.",{"path":2614,"title":2615,"description":2616,"updated":1321,"minutes":715,"sections":2617},"engine\u002Fguide","Using the command lines","This reference is for developers and IT staff using the VIABLE Harness and Engine command lines, and for researchers reading the measures.",[2618,2620,2624,2628,2632,2636,2639,2643,2647,2651,2655,2659,2661,2664,2668,2671,2675,2679],{"id":17,"title":17,"text":2619},"It covers the command line, what a local run does, the services a host passes in, the open formats and the measures. The README is the overview; components.md, mcp.md, xapi.md and step-manifests.md go deeper.",{"id":2621,"title":2622,"text":2623},"the-command-line","The command line","viable-harness --help and viable-engine --help have every flag. viable-engine try [package...] opens the real pages on this computer with what the AI did beside them; --demo --tour plays the scene by itself and --export \u003Cdir> writes a static copy of demo mode (try.md). view and suggest also take a folder, which stands for every JSON file in it. Run any command with npx @viable-lab\u002Fengine \u003Ccommand> in place of viable-harness or viable-engine, or from a clone with node engine\u002Fbin\u002Fviable-engine.mjs \u003Ccommand>. run: a .viable.zip (a course downloaded with its files) runs as it is: its files are rea",{"id":2625,"title":2626,"text":2627},"what-runs-locally","What runs locally","Steps In a local run Input, LLM, Condition, Router, Agent, VETTING, Guardrail, Transform, State, Loop, For each, Parallel, Ask, Reply (output), Note Run as on VIABLE. An Agent step's memory tools work as Memory steps do; in a course package it searches the package's knowledge bases (search_knowledge, not browsing or reading whole documents) and calls its other agents. Fetch URL (http) Reads JSON, text and HTML pages, which become Markdown (headings, paragraphs, lists, links, images, table rows) without scripts, styles or site chrome. Knowledge In a course package (a folder or its .viable.zip),",{"id":2629,"title":2630,"text":2631},"serving-it","Serving it","serve is for one machine. For a cloud, inspect says what a package needs, deploy \u003Ctarget> writes a folder ready to deploy, and verify checks it from outside (self-hosting.md). In code, createHandler({ agents, runtime, store, options, routes }) is a function from a web Request to a Response, and createApp({ bytes, vars, store, models }) builds one from a package's bytes. serve --panel adds the panel to your own server, for the token holder, on a page asked for with ?panel=1. test ... --html shows results as a page.",{"id":2633,"title":2634,"text":2635},"learners-pages","Learners' pages","A package carries each agent's look and chat page settings, and serve hosts them: \u002Fchat\u002F\u003Cagent>, \u002Fembed.js, \u002Fcourse\u002F\u003Ccourse>, and \u002Fteacher and \u002Fconsole behind the token (with none set, one made at start and printed once). Limits and allowed sites are enforced. A learner is who the course says: a browser with a code they can re-enter, a personal code from its class list, or a name they type; or whoever has a class code (--class-code-env), or who a proxy says (--learner-header). The console sets up models, courses, class lists, chat pages and knowledge in the browser. viable-engine records expor",{"id":2637,"title":2638,"text":17},"from-code","From code",{"id":2640,"title":2641,"text":2642},"services","Services","The engine takes whatever only a host has as services, so a host decides where models, knowledge, memory and media come from: runAgent(doc, { services: { callChatModel, searchKnowledge, memory, resolveSubAgent, generateImage, generateSpeech, transcribeAudio, toMarkdown, models } }), with the shapes src\u002Fagents\u002Fengine.js calls. A local run brings its own for models (openAICompatible({ baseUrl, apiKey, model, fetch })), speech and pictures (openAISpeech({ baseUrl, apiKey, model, fetch, save }) and openAIImages({ baseUrl, apiKey, model, fetch, save }), saving with mediaFiles(dir)), memory when ask",{"id":2644,"title":2645,"text":2646},"in-another-harness-or-assistant","In another harness or assistant","For a host that keeps its own harness, assistant or agent SDK: An MCP server. viable-harness mcp serves its tools over stdio: check_reply, prepare_task, teaching_instructions, find_misconceptions, find_guidance, find_designs, compute_measures, validate_document, draft_tests, calibrate_judge, suggest_changes, list_components and find_public_goods; viable-engine mcp adds run_agent and run_agent_tests. A client starts it as node \u002Fpath\u002Fto\u002Fviable\u002Fharness\u002Fbin\u002Fviable-harness.mjs mcp, with OPENAI_BASE_URL and OPENAI_API_KEY for the tools that call models. The host decides whether a reply is checked an",{"id":2648,"title":2649,"text":2650},"the-open-formats","The open formats","JSON Schema (draft 2020-12) in schemas\u002F, each with an example and published at its $id, https:\u002F\u002Fdevelopers.viablelab.org\u002Fschemas\u002F\u003Cname>.schema.json: Schema What Example agent.schema.json An exported agent (.agent.json, format viable.agent): its graph, profile and what it requires schemas\u002Fexamples\u002Fagent.example.json course-package.schema.json A course with its agents and question sets (viable.course-package) the six files in examples\u002F learning-events.schema.json One learner's events and turns schemas\u002Fexamples\u002Flearning-events.example.json teaching.schema.json An activity's teaching settings, wit",{"id":2652,"title":2653,"text":2654},"the-measures","The measures","measureLearner({ events, turns }) returns the research export's learner metrics (messages, sessions, think time, revision, pasting, accuracy, mastery, wheel-spinning, ...), mastery per skill, and how the learner wrote in each writing panel. Each metric's definition, computation, rationale, caveats and sources are exported as METRICS, WRITING, PANELS and CITATIONS, from src\u002Futils\u002FresearchMetrics.js.",{"id":2656,"title":2657,"text":2658},"the-teacher-view","The teacher view","viable-harness view (or teacherView({ teaching, records, runs, title, suggestions })) makes one HTML page for a teacher who doesn't read JSON. It opens on what happened, in sentences and a row of marks, one group for each reply reviewed and one mark for each round. Then come How the AI helps as it was set, with each section's own level and note; what VETTING did, with every reply that was sent back as a marked-up draft (the draft struck, the reviewer's reason beside it, the rewrite); each learner's measures, by the ID their record carries, as a row of ticks and crosses and small bars, with eve",{"id":458,"title":459,"text":2660},"The loop's fourth step: viable-harness suggest \u003Crecords and runs...> (or suggestChanges({ teaching, runs, records })) proposes changes to How the AI helps from the evidence, each with the evidence beside it, and the teacher view shows them. Rules, no model, so each one says exactly why: Rule When Proposes Answers given away at least 30% of 5 or more reviewed replies failed their first VETTING review for giving too much away one step less help (from explain to hint, ...) Replies unverified at least 20% of 5 or more replies never passed review nothing: the teacher reads those replies Misconcepti",{"id":2662,"title":1714,"text":2663},"components","Other teams' work joins the harness as a component in one of six slots, with a manifest saying what learner data it receives, where it sends it, its license, citation and evidence (components.md; each built-in component has a page in docs\u002Fcomponents\u002F). A component that runs out of process, as an HTTP endpoint or a stdio MCP server, is called with callComponent(manifest, payload) or viable-harness component \u003Cmanifest.json> --input payload.json. The harness sends only the fields receives lists, calls an HTTP entry only on a host in sends_to, and stops at a timeout or an oversized answer; what an",{"id":2665,"title":2666,"text":2667},"the-public-goods-catalog","The public goods catalog","catalog.md lists open datasets, benchmarks, knowledge graphs, standards, evaluators, models, tools, open content and learning data repositories for K-12 AI, one file each in catalog\u002F (schemas\u002Fcatalog-entry.schema.json), each with its license and a note on gated, non-commercial, mixed or conflicting terms, how to get it, whether it is released, the slot it would fill and the date it was checked. searchCatalog(query, { kind, slot, open, connected }), viable-harness catalog and the MCP tool find_public_goods search it with no network; open keeps what anyone may download and use, commercially too.",{"id":2669,"title":968,"text":2670},"agent-tests","The loop's fifth step: cases written from the teacher's intent, run again after every change. viable-harness draft-tests \u003Cpackage.json | teaching.json> --model \u003Cid> (or draftCases, or the draft_tests MCP tool) has a model draft cases from How the AI helps (asking for the answer, a listed misconception, a section's own level, distress, unsafe and off-topic requests), each checked like a saved case, with malformed drafts listed and the reason; a person reads every draft before it runs. viable-harness tests-from-records \u003Crecord.json...> (casesFromTurns) takes cases from learners' past turns witho",{"id":2672,"title":2673,"text":2674},"conformance-and-xapi","Conformance and xAPI","conformance\u002F holds language-neutral JSON fixtures: documents in each format, graphs, expressions, teaching settings, VETTING's reviewer outputs and prompts, and learning records, each with what the harness does with it. Another implementation, such as a port of VETTING or an engine that reads VIABLE's formats, runs the same cases to show it agrees; the fixtures decide when two disagree (conformance\u002FREADME.md). npm test runs them against the harness, viable-harness conformance [suite] prints pass or FAIL per case (exit code 1 on a failure), and runConformance() runs them from code. toStatements",{"id":2676,"title":2677,"text":2678},"the-examples","The examples","examples\u002F holds six course packages: fractions practice, a PDF reading with a Socratic tutor, argument writing, English speaking practice, a density lab on an embedded page, and a library research desk. All six run locally as they are (test\u002Fexamples.test.js runs each on a scripted endpoint): the library desk downloads its four guides and answers from them with citations, and the English partner's reply is read aloud on your endpoint's \u002Faudio\u002Fspeech; its Transcribe step is skipped, since a local run sends typed text, not a recording. On VIABLE the reading tutor and the density lab coach also se",{"id":2680,"title":2681,"text":2682},"how-it-relates-to-the-viable-developer-platform","How it relates to the VIABLE Developer Platform","The VIABLE Developer Platform runs this same engine, teaching layer and measures, and adds what running it for many projects takes: accounts, a visual workflow editor, studies with consent, coding and the research export; learners open its activities on the VIABLE Learning Platform. It passes its own services (model calls on its provider keys, media, billing fields, its model catalog) and runs exactly the code in this repository. This page comes from the open repository: docs\u002Fguide.md. To change it, change it there.",{"id":2684,"title":2685,"lead":2686,"pages":2687},"resources","Open resources","The public learning-science resources VIABLE builds on, and their licenses.",[2688,2715],{"path":2689,"title":2690,"description":2691,"updated":63,"minutes":256,"sections":2692},"resources\u002Flearning-commons","Learning Commons","How VIABLE uses Learning Commons' Knowledge Graph for standards, skills and math misconceptions, what it keeps, and how to credit it.",[2693,2695,2699,2703,2707,2711],{"id":17,"title":17,"text":2694},"VIABLE reads academic standards and durable skills from Learning Commons' Knowledge Graph, an open dataset of standards, skills and what they break into. This page explains what VIABLE takes from it, when, and what you owe it when you share your work.",{"id":2696,"title":2697,"text":2698},"what-viable-uses","What VIABLE uses","The Knowledge Graph connects standards and skills to smaller pieces of learning. VIABLE uses five parts of it, all in an activity's How the AI helps: In the Knowledge Graph In VIABLE Academic standards K-12 standard: every state, Washington, D.C. and Common Core, pre-K to grade 12 Learning components It breaks into: the skills inside a standard Prerequisite relations Standards before it: what the AI can go back to Carnegie Skills Progressions Durable skill: collaboration, communication and critical thinking, at four levels Eedi Misconceptions Graph Misconceptions to listen for: math misconcept",{"id":2700,"title":2701,"text":2702},"when-viable-asks-and-what-it-keeps","When VIABLE asks, and what it keeps","You choose a standard or a skill. While you search for a standard, VIABLE asks Learning Commons, and keeps each answer for a day. Durable skills and misconceptions come from VIABLE's own copy. VIABLE keeps a copy. What you pick, with the pieces you leave ticked, is saved in the activity's version, with its source and license. Learners never wait on it. When a learner sends a message, the agent reads that saved copy. Learning Commons isn't asked again. So a change at Learning Commons never changes what an activity's AI was already given, and your research export says exactly what each version u",{"id":2704,"title":2705,"text":2706},"how-each-part-is-obtained","How each part is obtained","Learning Commons publishes the graph two ways: an API, and release files of about a gigabyte. VIABLE uses each where it works best. Standards are looked up. The API finds a standard from a teacher's own words, and stays current without VIABLE storing it. The saved copy means learners' runs never depend on it. Durable skills are copied. The API doesn't search them yet, so VIABLE carries the Carnegie Skills Progressions from the release files: 31 indicators, each at four levels. Misconceptions are copied, and matched by words. The release files carry Eedi's 8,117 math misconceptions and the 2,25",{"id":2708,"title":2709,"text":2710},"crediting-it","Crediting it","The Knowledge Graph is licensed CC BY 4.0, and Carnegie and Eedi share their parts under the same license. VIABLE shows the attribution beside every standard, skill and misconception, and keeps it in the saved copy. When you publish materials or data that include their text, credit them, for example: \"Standards from the Learning Commons Knowledge Graph, CC BY 4.0.\" or \"Misconceptions from the Eedi Misconceptions Graph v1.0, (c) 2026 Eedi Ltd., via Learning Commons, CC BY 4.0.\"",{"id":2712,"title":2713,"text":2714},"not-teaching-k-12","Not teaching K-12?","A durable skill fits learners of any age, and a goal in your own words fits anyone: a university seminar, an adult literacy class, a library workshop. See How the AI helps. Standards, skills and misconceptions: choose them for an activity. The research export: what each activity version used, in one download.",{"path":2716,"title":2717,"description":2718,"updated":421,"minutes":32,"sections":2719},"resources\u002Flicenses","Licenses and credit","What VIABLE builds on, under which licenses, and how to credit it when you publish materials, papers or data.",[2720,2722,2726,2730,2734],{"id":17,"title":17,"text":2721},"VIABLE builds on open research and open data. This page lists what it uses, under which license, and what to credit when you share a course, a paper or a dataset made with it.",{"id":2723,"title":2724,"text":2725},"what-viable-builds-on","What VIABLE builds on","Resource What VIABLE uses it for License Learning Commons Knowledge Graph Standards, what they break into, and the standards before them CC BY 4.0 Eedi Misconceptions Graph v1.0, (c) 2026 Eedi Ltd., via Learning Commons Math misconceptions to listen for, and the skills they hinder CC BY 4.0 VETTING Checking each reply against rules and an answer key MIT (reference implementation) The VIABLE CLI and its Agent Skill Your own AI doing project work as you MIT Research methods in the export How each measure is computed Cited in data_dictionary.csv",{"id":2727,"title":2728,"text":2729},"where-the-credit-already-appears","Where the credit already appears","You don't have to add attribution inside VIABLE. It is already there: In the activity editor, beside every standard, with the date it was retrieved, and under the misconceptions. In the activity's version, which keeps each standard's and misconception's source, license and attribution. In the research export. manifest.json keeps each activity version's settings, standard and misconceptions included. When a version used them, README.md says how to credit them. In the data dictionary, measures name the papers they come from.",{"id":2731,"title":2732,"text":2733},"when-you-publish","When you publish","Materials with a standard's or a misconception's text. Add a line such as: \"Standards from the Learning Commons Knowledge Graph, CC BY 4.0.\" or \"Misconceptions from the Eedi Misconceptions Graph v1.0, (c) 2026 Eedi Ltd., via Learning Commons, CC BY 4.0.\" A paper about an agent that uses VETTING. Cite the VETTING study. A dataset from the research export. Keep README.md, manifest.json and data_dictionary.csv with it, so others know what each column means and where it comes from. Learners' data isn't open data. Share an export only as your approval and your consent form allow. Learners appear in",{"id":2735,"title":2736,"text":2737},"your-own-materials-and-the-models","Your own materials and the models","What you and your learners put into VIABLE is covered by VIABLE's Terms of Service and Privacy Policy. Replies come from the model you choose, and that model's provider sets its own usage terms. Models lists each provider. When a question set or a knowledge base holds someone else's material, its license still applies. Keep its credit with it, for example in the question set's description or the document itself. Learning Commons: what VIABLE takes from it, when, and what it keeps. The research export: the files, their documentation and how to cite what learners saw.",{"meta":2739,"blocks":2740,"headings":2744,"sections":2751},{"path":2007,"title":2008,"description":2009,"updated":63,"minutes":1586},[2741],{"type":2742,"html":2743},"html","\u003Cp>Three\ntests compare computing the mistake with asking a model.\u003C\u002Fp>\n\u003Ch2 id=\"summary\">Summary\u003Ca class=\"doc-anchor\" href=\"#summary\" aria-label=\"Link to this section\">\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>For a problem that is two numbers and an operation, the Harness applies each of 66 faulty procedures to the problem\nand names the one that gives exactly what the learner wrote (\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FVIABLE-Learning-Lab\u002Fviable\u002Fblob\u002Fmain\u002Fharness\u002Fsrc\u002Fdiagnose.js\" target=\"_blank\" rel=\"noreferrer\">\u003Ccode>src\u002Fdiagnose.js\u003C\u002Fcode>\u003C\u002Fa>). When none\ndoes, it names nothing, and the turn goes on as it would have without a name.\u003C\u002Fp>\n\u003Cp>\u003Cimg src=\"https:\u002F\u002Fraw.githubusercontent.com\u002FVIABLE-Learning-Lab\u002Fviable\u002Fmain\u002Fdocs\u002Fimages\u002Fdiagnosis-checks.svg\" alt=\"Computing a mistake against asking a model. Naming the faulty procedure behind 80 wrong answers: code is right on 70 percent and wrong on 10; gpt-6-luna 71 and 21; gpt-oss-120b 63 and 34; gemma-4-31b-it 44 and 56. Predicting a learner's next answer on 100 MalruleLib pairs from another template: code is right on 45 percent and wrong on 7; gemma-4-31b-it 33 and 65; gpt-oss-120b 56 and 41; code first and then gemma-4-31b-it 60 and 39; code first and then gpt-oss-120b 63 and 34.\">\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Code names the right procedure as often as the best of three models asked the same question (70 answers in 100\nagainst 71), and names a wrong one half as often (10 against 21).\u003C\u002Fli>\n\u003Cli>On wrong answers generated by another team's library, code names 61 in 100 of those it can read, and the same\nprocedure of theirs gets the same name of ours 88 times in 100.\u003C\u002Fli>\n\u003Cli>On that library's own task, predicting a learner's next answer, a prediction from code is right about nine times in\nten. With code first and a model asked only where code has no prediction, a small open-weight model goes from 33\nright in 100 to 60.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"guide-table\">\u003Ctable>\u003Cthead>\n\u003Ctr>\n\u003Cth>Test\u003C\u002Fth>\n\u003Cth>Cases\u003C\u002Fth>\n\u003Cth>Models asked\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ca href=\"#against-a-model-asked-the-same-question\">Against a model asked the same question\u003C\u002Fa>\u003C\u002Ftd>\n\u003Ctd>80 wrong answers, the test half of the scorecard's set\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>gpt-6-luna\u003C\u002Fcode>, \u003Ccode>gpt-oss-120b\u003C\u002Fcode>, \u003Ccode>gemma-4-31b-it\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ca href=\"#on-wrong-answers-from-another-library\">On wrong answers from another library\u003C\u002Fa>\u003C\u002Ftd>\n\u003Ctd>MalruleLib's 4,991 problems, of which code takes the 547 that are two numbers and one operation\u003C\u002Ftd>\n\u003Ctd>None\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ca href=\"#on-predicting-the-next-answer\">On predicting a learner's next answer\u003C\u002Fa>\u003C\u002Ftd>\n\u003Ctd>MalruleLib's 12,706 pairs, of which 779 are in scope and 200 were put to models\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>gemma-4-31b-it\u003C\u002Fcode>, \u003Ccode>gpt-oss-120b\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\u003C\u002Fdiv>\u003Ch2 id=\"against-a-model-asked-the-same-question\">Against a model asked the same question\u003Ca class=\"doc-anchor\" href=\"#against-a-model-asked-the-same-question\" aria-label=\"Link to this section\">\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>The cases are the 80 wrong answers in the test half of \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FVIABLE-Learning-Lab\u002Fviable\u002Fblob\u002Fmain\u002Fharness\u002Fscorecard\u002Fwrong-answers.json\" target=\"_blank\" rel=\"noreferrer\">\u003Ccode>wrong-answers.json\u003C\u002Fcode>\u003C\u002Fa>,\neach labelled with the faulty procedure behind it. Six of them are slips that no procedure explains. Code computes.\nEach model is shown the problem, the learner's answer and the same list of 66 procedures, and is told to work a\nprocedure through before choosing it, or to answer &quot;none&quot;.\u003C\u002Fp>\n\u003Cdiv class=\"guide-table\">\u003Ctable>\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003C\u002Fth>\n\u003Cth style=\"text-align:right\">Names the labelled procedure\u003C\u002Fth>\n\u003Cth style=\"text-align:right\">Names another\u003C\u002Fth>\n\u003Cth style=\"text-align:right\">Gives a slip a procedure\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Code, no model\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">\u003Cstrong>70% (56 of 80; 59 to 79)\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">\u003Cstrong>10% (8; 5 to 19)\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">\u003Cstrong>0 of 6\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gpt-6-luna\u003C\u002Fcode>, asked\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">71% (57; 61 to 80)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">21% (17; 14 to 31)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">2 of 6\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gpt-oss-120b\u003C\u002Fcode>, asked\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">63% (50; 52 to 72)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">34% (27; 24 to 45)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">3 of 6\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gemma-4-31b-it\u003C\u002Fcode>, asked\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">44% (35; 33 to 55)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">56% (45; 45 to 67)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">6 of 6\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\u003C\u002Fdiv>\u003Cp>Each range is a 95% interval. Code and the models answer the same 80 cases, so the differences are taken case by case:\u003C\u002Fp>\n\u003Cdiv class=\"guide-table\">\u003Ctable>\u003Cthead>\n\u003Ctr>\n\u003Cth>Code against\u003C\u002Fth>\n\u003Cth style=\"text-align:right\">Names the labelled procedure, points\u003C\u002Fth>\n\u003Cth style=\"text-align:right\">Names another, points\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gpt-6-luna\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">-1.3 (-6.3 to 3.8)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">-11.3 (-18.8 to -5.0)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gpt-oss-120b\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">+7.5 (0.0 to 16.3)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">-23.8 (-33.8 to -13.8)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gemma-4-31b-it\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">+26.3 (16.3 to 37.5)\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">-46.3 (-57.5 to -35.0)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\u003C\u002Fdiv>\u003Cp>Code finds as many as the best of the three models. It names a wrong procedure on 11 fewer answers in 100 than that\nmodel, 24 fewer than the larger open-weight model and 46 fewer than the smaller. The difference lies in what happens\nwhen there is nothing to find: code says nothing, and the models name something. \u003Ccode>gemma-4-31b-it\u003C\u002Fcode>, of a size a\ndistrict could run on its own server, never answered &quot;none&quot; and was wrong more often than right.\u003C\u002Fp>\n\u003Cp>A wrong name is the costlier error, since a tutor told the wrong misconception addresses a mistake the learner didn't\nmake.\u003C\u002Fp>\n\u003Ch2 id=\"on-wrong-answers-from-another-library\">On wrong answers from another library\u003Ca class=\"doc-anchor\" href=\"#on-wrong-answers-from-another-library\" aria-label=\"Link to this section\">\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsonkar-lab\u002Fmalrulelib\" target=\"_blank\" rel=\"noreferrer\">MalruleLib\u003C\u002Fa> (Chen, Liu &amp; Sonkar, 2026, arXiv 2601.03217) holds 101 faulty\nprocedures in school mathematics as code, and 4,991 generated problems with the wrong answer each procedure gives.\nNone of the Harness's procedures were written from it. Nothing is matched by hand: a script counts how many of their\nproblems are in scope, how many of their wrong answers get a name, and whether one of their procedures keeps getting\nthe same name of ours.\u003C\u002Fp>\n\u003Cdiv class=\"guide-table\">\u003Ctable>\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003C\u002Fth>\n\u003Cth style=\"text-align:right\">Result\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>Their problems that are two numbers and one operation, and read correctly\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">547\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Wrong answers to those that code names\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">333 of 547 (60.9%)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Named answers that carry the name most often given to their procedure\u003C\u002Ftd>\n\u003Ctd style=\"text-align:right\">88.3%\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\u003C\u002Fdiv>\u003Cp>About one problem in nine is in scope. Most of MalruleLib is algebra, exponents, radicals, statistics and geometry.\u003C\u002Fp>\n\u003Cp>The test also found a fault. The code that reads a problem took 94 problems for two-number arithmetic that weren't:\n\u003Ccode>|3x - 4| when x = -3\u003C\u002Fcode> for 3 × -4, \u003Ccode>√(3+1)\u003C\u002Fcode> for 3 + 1, and a word problem with three numbers for the two inside its\nbrackets. A wrong reading gives a wrong right answer, and then a confident name for a mistake nobody made. The reader\nwas changed to refuse a problem with a root, a power, an absolute value, an equals sign before the numbers, a letter beside\nthem, or any other number in it. It then misreads 2 of the same problems and takes 540 as in scope.\u003C\u002Fp>\n\u003Cp>Four more changes came from the answers that went unnamed. A decimal cut short is read as the longer one (7.11 for\n64\u002F9). An answer that is one of the problem's own numbers counts when it stands alone or ends a line of working (7\u002F9\nfor 1\u002F9 × 7\u002F9). Two procedures from the classic lists of arithmetic bugs were added (Brown &amp; Burton, 1978): the\ncarried digit never added when multiplying, and the points left out of a sum. With these, code names 361 of those 540 wrong\nanswers (66.9%). That figure was reached by reading this same data, so it shows only that the gaps found are closed,\nand 60.9% is the estimate for cases the procedures weren't written from.\u003C\u002Fp>\n\u003Cp>Still without a name are MalruleLib's borrowing variants in column subtraction, misaligned rows in multi-digit\nmultiplication, and carrying the wrong digit when adding.\u003C\u002Fp>\n\u003Ch2 id=\"on-predicting-the-next-answer\">On predicting the next answer\u003Ca class=\"doc-anchor\" href=\"#on-predicting-the-next-answer\" aria-label=\"Link to this section\">\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>MalruleLib's paper asks models to infer a misconception from one worked mistake and predict the same student's answer\nto another problem. Across nine models it reports 66% on solving the problems and 40% on predicting the answer when\nthe second problem is from another template. Two problems share a template when the same generator of the library\nmade both.\u003C\u002Fp>\n\u003Cp>A procedure that is code can do this directly: name the procedure behind the first answer, then apply it to the\nsecond problem (\u003Ca href=\"https:\u002F\u002Fgithub.com\u002FVIABLE-Learning-Lab\u002Fviable\u002Fblob\u002Fmain\u002Fharness\u002Fsrc\u002Fdiagnose.js\" target=\"_blank\" rel=\"noreferrer\">\u003Ccode>applyProcedure\u003C\u002Fcode>\u003C\u002Fa>). Of the library's 12,706 pairs, 779 have both problems in\nscope. On those, code predicts the next answer exactly on 62.5% of the 504 same-template pairs and 40.0% of the 275\ncross-template pairs. It predicts another answer on 3.0% and 7.6%, and makes no prediction on the rest.\u003C\u002Fp>\n\u003Cp>Two open-weight models were asked the same question on 200 of those pairs, 100 of each kind:\u003C\u002Fp>\n\u003Cdiv class=\"guide-table\">\u003Ctable>\u003Cthead>\n\u003Ctr>\n\u003Cth>On the same 200 pairs\u003C\u002Fth>\n\u003Cth>Same template: right, wrong, none\u003C\u002Fth>\n\u003Cth>Cross template: right, wrong, none\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Code\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>60%, 6%, 34%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>45%, 7%, 48%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gemma-4-31b-it\u003C\u002Fcode>, asked\u003C\u002Ftd>\n\u003Ctd>58%, 42%, 0%\u003C\u002Ftd>\n\u003Ctd>33%, 65%, 2%\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gpt-oss-120b\u003C\u002Fcode>, asked\u003C\u002Ftd>\n\u003Ctd>79%, 19%, 2%\u003C\u002Ftd>\n\u003Ctd>56%, 41%, 3%\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Code, then \u003Ccode>gemma-4-31b-it\u003C\u002Fcode> where code has no prediction\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>73%, 27%, 0%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>60%, 39%, 1%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Code, then \u003Ccode>gpt-oss-120b\u003C\u002Fcode> where code has no prediction\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>79%, 19%, 2%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Cstrong>63%, 34%, 3%\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\u003C\u002Fdiv>\u003Cp>When code makes a prediction it is right about nine times in ten, and it makes one for half to two thirds of the\npairs. The larger model gets more pairs right than code and is wrong three to six times as often. Putting code first\nhelps the small model clearly: on cross-template pairs it goes from 33% right to 60%. The larger goes from 56% to 63%,\nwhich is within what chance could give, since with 100 pairs in each cell a difference under about 14 points could be\nchance. Both make fewer wrong predictions.\u003C\u002Fp>\n\u003Cp>The Harness uses a diagnosis the same way in a turn. Its instructions say what the answer shows only when code found a\nprocedure, and otherwise leave the model to work it out.\u003C\u002Fp>\n\u003Ch2 id=\"limits\">Limits\u003Ca class=\"doc-anchor\" href=\"#limits\" aria-label=\"Link to this section\">\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>The 80 wrong answers of the first test were written by an AI model together with their labels, and no teacher has\nchecked them. MalruleLib's wrong answers are generated by its procedures. No learner's answers are in any of the three\ntests, which measure whether a name or a prediction matches a label.\u003C\u002Fp>\n\u003Ch2 id=\"print-the-tables-again\">Print the tables again\u003Ca class=\"doc-anchor\" href=\"#print-the-tables-again\" aria-label=\"Link to this section\">\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>Every answer a model gave is in \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FVIABLE-Learning-Lab\u002Fviable\u002Ftree\u002Fmain\u002Fharness\u002Fevals\u002Fdiagnosis\u002Fruns\u002F\" target=\"_blank\" rel=\"noreferrer\">\u003Ccode>runs\u002F\u003C\u002Fcode>\u003C\u002Fa>, by case and by pair. With no key set, these commands read the kept\nanswers and print the tables without a model:\u003C\u002Fp>\n\u003Cdiv class=\"guide-code\">\u003Cdiv class=\"guide-code-head\">\u003Cspan>sh\u003C\u002Fspan>\u003Cbutton type=\"button\" data-copy-code aria-label=\"Copy sh code\">Copy\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cpre>\u003Ccode class=\"hljs\">node evals\u002Fdiagnosis\u002Fask-a-model.mjs --models gpt-6-luna,gpt-oss-120b,gemma-4-31b-it --kept evals\u002Fdiagnosis\u002Fruns\u002Fasked.jsonl\n\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\u003Cp>MalruleLib's license allows research and open-source use, including evaluating models whose weights are public, and\nforbids commercial use, so none of it is in this repository. Clone it beside this one for the other two tests:\u003C\u002Fp>\n\u003Cdiv class=\"guide-code\">\u003Cdiv class=\"guide-code-head\">\u003Cspan>sh\u003C\u002Fspan>\u003Cbutton type=\"button\" data-copy-code aria-label=\"Copy sh code\">Copy\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cpre>\u003Ccode class=\"hljs\">git \u003Cspan class=\"hljs-built_in\">clone\u003C\u002Fspan> https:\u002F\u002Fgithub.com\u002Fsonkar-lab\u002Fmalrulelib &amp;&amp; git -C malrulelib checkout 8ddedfb\nnode evals\u002Fdiagnosis\u002Fmalrulelib.mjs malrulelib\u002Fdata\u002Fraw_data.csv --rules\nnode evals\u002Fdiagnosis\u002Fpredict-next.mjs malrulelib\u002Fdata\u002Fexperiment_pairs.csv --models gemma-4-31b-it,gpt-oss-120b --sample 200 --kept evals\u002Fdiagnosis\u002Fruns\u002Fpredicted.jsonl\n\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\u003Cp>To ask a model again, set \u003Ccode>OPENAI_BASE_URL\u003C\u002Fcode> and \u003Ccode>OPENAI_API_KEY\u003C\u002Fcode>. New answers are added to the file \u003Ccode>--kept\u003C\u002Fcode> names.\u003C\u002Fp>\n\u003Chr>\n\u003Cp>This page comes from the open repository: \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FVIABLE-Learning-Lab\u002Fviable\u002Fblob\u002Fmain\u002Fharness\u002Fevals\u002Fdiagnosis\u002FREADME.md\" target=\"_blank\" rel=\"noreferrer\">harness\u002Fevals\u002Fdiagnosis\u002FREADME.md\u003C\u002Fa>. To change it, change it there.\u003C\u002Fp>\n",[2745,2746,2747,2748,2749,2750],{"level":32,"id":1882,"text":1883},{"level":32,"id":2016,"text":2017},{"level":32,"id":2020,"text":2021},{"level":32,"id":2024,"text":2025},{"level":32,"id":1524,"text":1525},{"level":32,"id":1952,"text":1953},[2752,2753,2754,2755,2756,2757,2758],{"id":17,"title":17,"text":2012},{"id":1882,"title":1883,"text":2014},{"id":2016,"title":2017,"text":2018},{"id":2020,"title":2021,"text":2022},{"id":2024,"title":2025,"text":2026},{"id":1524,"title":1525,"text":2028},{"id":1952,"title":1953,"text":2030},1795237299362]