Correxit API / Browser / Workbook
Workbook¶
Notebook state, identity, lifecycle, and grading operations.
Namespaces¶
| Namespace | Description |
|---|---|
| Audit | - |
| Cell | - |
| Credentials | - |
| Grade | - |
| Identifier | - |
Type Aliases¶
Audit¶
Defined in: src/correxit/workbook.ts:34
The result of an audit on a workbook's rubric.
Certified¶
Certified =
object
Defined in: src/correxit/workbook.ts:45
Properties¶
grade¶
grade:
Verified
Defined in: src/correxit/workbook.ts:46
identifier¶
identifier:
Assigned
Defined in: src/correxit/workbook.ts:47
workbook¶
workbook:
Workbook
Defined in: src/correxit/workbook.ts:48
Credentials¶
Credentials = {
key:null;passphrase:null;path:string;unlock:null; } |object&Secret| {key:null;passphrase:null;path:string;unlock:boolean; }
Defined in: src/correxit/workbook.ts:51
Grade¶
Grade =
object& {verified:true; } | {verified:false; }
Defined in: src/correxit/workbook.ts:71
Type Declaration¶
path¶
path:
string
resolved¶
resolved:
boolean
score¶
score:
Score
spec¶
spec:
KernelSpec.ISpecModel|null
Headed¶
Headed =
object
Defined in: src/correxit/workbook.ts:85
A workbook with a live notebook widget.
Properties¶
content¶
readonlycontent:Notebook
Defined in: src/correxit/workbook.ts:86
context¶
readonlycontext:DocumentRegistry.IContext\<INotebookModel>
Defined in: src/correxit/workbook.ts:87
Headless¶
Headless =
object
Defined in: src/correxit/workbook.ts:91
A workbook retaining document context without a live notebook widget.
Properties¶
content¶
readonlycontent:null
Defined in: src/correxit/workbook.ts:92
context¶
readonlycontext:DocumentRegistry.IContext\<INotebookModel>
Defined in: src/correxit/workbook.ts:93
Identifier¶
Identifier =
object
Defined in: src/correxit/workbook.ts:107
A type for plugins to identify a workbook/assignment/assignee match.
Properties¶
assignee¶
assignee:
string|null
Defined in: src/correxit/workbook.ts:108
assignment¶
assignment:
string|null
Defined in: src/correxit/workbook.ts:109
file¶
file:
string|null
Defined in: src/correxit/workbook.ts:110
issue¶
issue:
string|null
Defined in: src/correxit/workbook.ts:111
rubric¶
rubric:
string
Defined in: src/correxit/workbook.ts:112
Functions¶
acknowledge()¶
acknowledge(
workbook,receipt?):Promise\<Locked>
Defined in: src/correxit/workbook.ts:456
Acknowledge a submitted workbook grade with a receipt.
Parameters¶
| Parameter | Type | Default value |
|---|---|---|
workbook |
Workbook |
undefined |
receipt |
string | null |
null |
Returns¶
Promise\<Locked>
add()¶
add(
workbook,cell,references?):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:444
Add a cell to a workbook's rubric.
Parameters¶
| Parameter | Type | Default value |
|---|---|---|
workbook |
Workbook |
undefined |
cell |
Cell |
undefined |
references |
Readonly\<{ cell: string; points: number; referent: string; secret: boolean; }>[] |
[] |
Returns¶
Promise\<Unlocked>
assign()¶
assign(
workbook,assignment?):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:479
Update a workbook's assignment metadata.
Parameters¶
| Parameter | Type | Description |
|---|---|---|
workbook |
Workbook |
the workbook to update. |
assignment |
Partial\<Assignment> |
the partial assignment data to apply. #### Notes Fields that are undefined in the assignment argument are ignored, i.e., the existing values in the rubric are preserved. Fields that are null (where allowed, e.g. expiration) will explicitly clear the value in the rubric. |
Returns¶
Promise\<Unlocked>
audit()¶
audit(
workbook,rubric):Audit
Defined in: src/correxit/workbook.ts:515
Audits a workbook's rubric, pruning impossible cells and references. Never throws.
Notes¶
If the rubric is locked, it is left unmodified.
Headed workbooks repair missing notebook state when possible: orphaned references are removed, and cells left invalid or unscorable are dropped. Headless workbooks fail immediately. Batch grading cannot recover from a structurally incomplete notebook.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
Rubric | null |
Returns¶
certify()¶
certify(
workbook,trans,bypass?):Promise\<Certified>
Defined in: src/correxit/workbook.ts:591
Certify a workbook: correct, lock, and freeze.
When bypass is true, skip kernel re-execution and build the grade
from the existing report scores. Use this when all cells have already
been graded and reviewed (e.g. after the last manual intervention).
Parameters¶
| Parameter | Type | Default value |
|---|---|---|
workbook |
Workbook |
undefined |
trans |
TranslationBundle |
undefined |
bypass |
boolean |
false |
Returns¶
Promise\<Certified>
collect()¶
collect(
workbook,receipt?):Promise\<Locked>
Defined in: src/correxit/workbook.ts:567
Collect a certified workbook grade.
Parameters¶
| Parameter | Type | Default value |
|---|---|---|
workbook |
Workbook |
undefined |
receipt |
string | null |
null |
Returns¶
Promise\<Locked>
comment()¶
comment(
workbook,id,comment):Promise\<Unlocked|null>
Defined in: src/correxit/workbook.ts:775
Adds a comment to a cell in the assignment score report.
Parameters¶
| Parameter | Type | Description |
|---|---|---|
workbook |
Workbook |
the workbook to modify the report for. |
id |
string |
the id of the cell to add comment for. |
comment |
string |
- |
Returns¶
Promise\<Unlocked | null>
a promise that resolves when the workbook has been updated.
convert()¶
convert(
workbook,credentials,unlocker):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:640
Convert a plain notebook into a workbook and return its rubric.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
credentials |
string | Secret |
unlocker |
Unlocker |
Returns¶
Promise\<Unlocked>
correct()¶
Call Signature¶
correct(
workbook,id,verbose):Promise\<Verbose>
Defined in: src/correxit/workbook.ts:685
Correct a cell (if id is provided) or an entire workbook.
Parameters¶
| Parameter | Type | Description |
|---|---|---|
workbook |
Workbook |
the workbook to correct. |
id |
string |
the id of the cell to correct. |
verbose |
true |
- |
Returns¶
Promise\<Verbose>
a promise that resolves to the correction result, i.e.,
- the score for the cell or the whole workbook
- the spec of the kernel used to get that score
Call Signature¶
correct(
workbook,id?,verbose?):Promise\<Grade>
Defined in: src/correxit/workbook.ts:690
Correct a cell (if id is provided) or an entire workbook.
Parameters¶
| Parameter | Type | Description |
|---|---|---|
workbook |
Workbook |
the workbook to correct. |
id? |
string |
the id of the cell to correct. |
verbose? |
false |
- |
Returns¶
Promise\<Grade>
a promise that resolves to the correction result, i.e.,
- the score for the cell or the whole workbook
- the spec of the kernel used to get that score
decrypt()¶
decrypt(
workbook,rubric,sealed?):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:791
Decrypts workbook content.
Parameters¶
| Parameter | Type | Default value |
|---|---|---|
workbook |
Workbook |
undefined |
rubric |
Unlocked |
undefined |
sealed |
Prepared[] |
[] |
Returns¶
Promise\<Unlocked>
dereference()¶
dereference(
workbook,referent):Promise\<void>
Defined in: src/correxit/workbook.ts:820
Remove a single reference from a cell.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
referent |
string |
Returns¶
Promise\<void>
distribute()¶
distribute(
workbook):Promise\<Rubric>
Defined in: src/correxit/workbook.ts:577
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
Promise\<Rubric>
draft()¶
draft(
workbook):Promise\<Locked>
Defined in: src/correxit/workbook.ts:831
Revert a submission to draft, restoring cell editability.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
Promise\<Locked>
execute()¶
execute(
workbook,rubric,id?):Promise\<{outputs:Outputs;spec:ISpecModel|null; } |null>
Defined in: src/correxit/workbook.ts:854
Executes the code cells of a workbook.
Parameters¶
| Parameter | Type | Description |
|---|---|---|
workbook |
Workbook |
the workbook to run. |
rubric |
Rubric |
- |
id? |
string |
the ID of the target cell. |
Returns¶
Promise\<{ outputs: Outputs; spec: ISpecModel | null; } | null>
a promise that resolves to a collection of executed cell outputs.
Notes¶
If id is not provided, the whole workbook is executed.
If id is provided and the target cell is 'answerable', the workbook is
executed up to this cell.
If id is provided and the target cell is comparable or correctable,
the workbook is executed up to both target and reference cells.
headed()¶
headed(
workbook):workbook is Headed
Defined in: src/correxit/workbook.ts:97
Type guard for workbooks with a live notebook widget.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook | null |
Returns¶
workbook is Headed
headless()¶
headless(
workbook):workbook is Headless
Defined in: src/correxit/workbook.ts:102
Type guard for workbooks without a live notebook widget.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook | null |
Returns¶
workbook is Headless
identifier()¶
identifier(
workbook):Identifier
Defined in: src/correxit/workbook.ts:895
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
intervene()¶
intervene(
workbook,id,intervention):Promise\<Unlocked|null>
Defined in: src/correxit/workbook.ts:934
Intervenes with a manual score for a cell.
Parameters¶
| Parameter | Type | Description |
|---|---|---|
workbook |
Workbook |
the workbook to modify the report for. |
id |
string |
the id of the cell to intervene on. |
intervention |
Readonly\<{ code: Code; comment: string; id: string; points: number; possible: number; status: Status; }> | null |
the manual score intervention. |
Returns¶
Promise\<Unlocked | null>
a promise that resolves when the workbook has been updated.
lock()¶
lock(
workbook):Promise\<void>
Defined in: src/correxit/workbook.ts:907
Lock a workbook if its rubric is unlocked.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
Promise\<void>
open()¶
open(
workbook,quiet?):Rubric|null
Defined in: src/correxit/workbook.ts:965
Synchronously returns a workbook's rubric or null from notebook metadata.
Parameters¶
| Parameter | Type | Default value | Description |
|---|---|---|---|
workbook |
Workbook | null |
undefined |
The current workbook. May be null. |
quiet |
boolean |
false |
Whether to return null or throw errors. #### Notes If a rubric exists in the pool for the given workbook, it is returned. If no rubric exists in the pool for the given workbook, its notebook metadata for the key correxit is read, parsed, normalized, and audited. Each of these steps may throw an error or return null. |
Returns¶
Rubric | null
See¶
update
recipients()¶
recipients(
workbook,credentials):Promise\<string[]>
Defined in: src/correxit/workbook.ts:991
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
credentials |
string | Secret | null |
Returns¶
Promise\<string[]>
provisioned recipient keys for a given workbook.
recover()¶
recover(
workbook,credentials):Promise\<number>
Defined in: src/correxit/workbook.ts:1023
Attempt to decrypt all encrypted cells in a workbook.
Reads the rubric ID and encrypted PGP keys directly from raw notebook metadata (no normalization required). Tries symmetric decryption and, if PGP private keys can be recovered, asymmetric unsealing on every encrypted cell.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
credentials |
string | Secret |
Returns¶
Promise\<number>
the number of cells successfully recovered.
refer()¶
refer(
workbook,id,reference):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:1079
Add a reference to an existing comparable or correctable cell.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
id |
string |
reference |
Reference |
Returns¶
Promise\<Unlocked>
remove()¶
remove(
workbook,id):Promise\<void>
Defined in: src/correxit/workbook.ts:1091
Remove a cell from a workbook's rubric.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
id |
string |
Returns¶
Promise\<void>
reset()¶
reset(
workbook):Promise\<void>
Defined in: src/correxit/workbook.ts:1117
Reset a workbook back to a plain Jupyter notebook.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
Promise\<void>
restore()¶
restore(
workbook,snapshot):Rubric|null
Defined in: src/correxit/workbook.ts:1105
Restore a workbook snapshot, invalidating cached rubric state first.
Returns the restored rubric when the snapshot contains valid Correxit
metadata, otherwise null.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
snapshot |
INotebookContent |
Returns¶
Rubric | null
revise()¶
revise(
workbook,key):Promise\<Locked>
Defined in: src/correxit/workbook.ts:1122
Revise a sealed submission: unseal cells and clear submission state.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
key |
string | PrivateKey |
Returns¶
Promise\<Locked>
reweight()¶
reweight(
workbook,id,points):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:1141
Update points for a cell or reference.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
id |
string |
points |
number |
Returns¶
Promise\<Unlocked>
seal()¶
seal(
workbook,rubric,recipients):Promise\<string>
Defined in: src/correxit/workbook.ts:1162
Seal all rubric cells in a workbook, encrypting their sources to the given PGP public key recipients.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
Locked |
recipients |
string[] |
Returns¶
Promise\<string>
the seal hash (SHA-256 of concatenated ciphertexts).
submit()¶
submit(
workbook,recipients):Promise\<Locked>
Defined in: src/correxit/workbook.ts:1182
Submit an assignment: seal rubric cells, then freeze.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
recipients |
string[] |
Returns¶
Promise\<Locked>
toggle()¶
toggle(
workbook,referent):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:1202
Toggle a workbook reference's secret flag.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
referent |
string |
Returns¶
Promise\<Unlocked>
unlock()¶
unlock(
workbook,key):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:1213
Unlocks a workbook's rubric and decrypts its contents.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
key |
string |
Returns¶
Promise\<Unlocked>
unstarted()¶
unstarted(
workbook):Promise\<boolean>
Defined in: src/correxit/workbook.ts:1251
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
Promise\<boolean>
whether a workbook's assignment is started or not.
update()¶
Call Signature¶
update(
workbook,rubric,audited?):Promise\<Locked>
Defined in: src/correxit/workbook.ts:1278
Updates the workbook metadata with an audited rubric.
Notes¶
If an audited value is passed in, its results are used instead of running
another audit.
If rubric is null, the workbook is reset back to a notebook.
If the given rubric passes an audit, which may prune broken cells, it is
locked and written to the notebook metadata correxit key.
Superseded updates wait for the latest metadata write, including failures.
Completion follows that write; the returned rubric is this invocation's
audited snapshot and may already have been superseded. This does not save
the notebook file or serialize mutations performed before calling update.
The audited rubric is returned.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
Locked |
audited? |
Audit |
Returns¶
Promise\<Locked>
Call Signature¶
update(
workbook,rubric,audited?):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:1283
Updates the workbook metadata with an audited rubric.
Notes¶
If an audited value is passed in, its results are used instead of running
another audit.
If rubric is null, the workbook is reset back to a notebook.
If the given rubric passes an audit, which may prune broken cells, it is
locked and written to the notebook metadata correxit key.
Superseded updates wait for the latest metadata write, including failures.
Completion follows that write; the returned rubric is this invocation's
audited snapshot and may already have been superseded. This does not save
the notebook file or serialize mutations performed before calling update.
The audited rubric is returned.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
Unlocked |
audited? |
Audit |
Returns¶
Promise\<Unlocked>
Call Signature¶
update(
workbook,rubric):Promise\<null>
Defined in: src/correxit/workbook.ts:1288
Updates the workbook metadata with an audited rubric.
Notes¶
If an audited value is passed in, its results are used instead of running
another audit.
If rubric is null, the workbook is reset back to a notebook.
If the given rubric passes an audit, which may prune broken cells, it is
locked and written to the notebook metadata correxit key.
Superseded updates wait for the latest metadata write, including failures.
Completion follows that write; the returned rubric is this invocation's
audited snapshot and may already have been superseded. This does not save
the notebook file or serialize mutations performed before calling update.
The audited rubric is returned.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
null |
Returns¶
Promise\<null>