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:33
The result of an audit on a workbook's rubric.
Certified¶
Certified =
object
Defined in: src/correxit/workbook.ts:44
Properties¶
grade¶
grade:
Grade
Defined in: src/correxit/workbook.ts:45
identifier¶
identifier:
Assigned
Defined in: src/correxit/workbook.ts:46
workbook¶
workbook:
Workbook
Defined in: src/correxit/workbook.ts:47
Credentials¶
Credentials = {
key:null;passphrase:null;path:string;unlock:null; } | {key:string;passphrase:null;path:string;unlock:null; } | {key:null;passphrase:string;path:string;unlock:null; } | {key:null;passphrase:null;path:string;unlock:boolean; }
Defined in: src/correxit/workbook.ts:50
Grade¶
Grade =
object
Defined in: src/correxit/workbook.ts:71
Properties¶
path¶
path:
string
Defined in: src/correxit/workbook.ts:72
resolved¶
resolved:
boolean
Defined in: src/correxit/workbook.ts:73
score¶
score:
Score
Defined in: src/correxit/workbook.ts:74
spec¶
spec:
KernelSpec.ISpecModel|null
Defined in: src/correxit/workbook.ts:75
Headed¶
Headed =
object
Defined in: src/correxit/workbook.ts:83
A workbook with a live notebook widget.
Properties¶
content¶
readonlycontent:Notebook
Defined in: src/correxit/workbook.ts:84
context¶
readonlycontext:DocumentRegistry.IContext\<INotebookModel>
Defined in: src/correxit/workbook.ts:85
Headless¶
Headless =
object
Defined in: src/correxit/workbook.ts:89
A workbook retaining document context without a live notebook widget.
Properties¶
content¶
readonlycontent:null
Defined in: src/correxit/workbook.ts:90
context¶
readonlycontext:DocumentRegistry.IContext\<INotebookModel>
Defined in: src/correxit/workbook.ts:91
Identifier¶
Identifier =
object
Defined in: src/correxit/workbook.ts:105
A type for plugins to identify a workbook/assignment/assignee match.
Properties¶
assignee¶
assignee:
string|null
Defined in: src/correxit/workbook.ts:106
assignment¶
assignment:
string|null
Defined in: src/correxit/workbook.ts:107
file¶
file:
string|null
Defined in: src/correxit/workbook.ts:108
issue¶
issue:
string|null
Defined in: src/correxit/workbook.ts:109
rubric¶
rubric:
string
Defined in: src/correxit/workbook.ts:110
Functions¶
acknowledge()¶
acknowledge(
workbook,receipt?):Promise\<Locked>
Defined in: src/correxit/workbook.ts:423
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:411
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:446
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:469
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:546
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:522
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:725
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,passphrase,unlocker):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:595
Convert a plain notebook into a workbook and return its rubric.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
passphrase |
string |
unlocker |
Unlocker |
Returns¶
Promise\<Unlocked>
correct()¶
Call Signature¶
correct(
workbook,id,verbose):Promise\<Verbose>
Defined in: src/correxit/workbook.ts:640
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:645
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):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:741
Decrypts workbook content.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
Unlocked |
Returns¶
Promise\<Unlocked>
dereference()¶
dereference(
workbook,referent):void
Defined in: src/correxit/workbook.ts:761
Remove a single reference from a cell.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
referent |
string |
Returns¶
void
distribute()¶
distribute(
workbook):Promise\<Rubric>
Defined in: src/correxit/workbook.ts:532
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
Promise\<Rubric>
draft()¶
draft(
workbook):Promise\<Locked>
Defined in: src/correxit/workbook.ts:772
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:795
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:95
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:100
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:836
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
Returns¶
intervene()¶
intervene(
workbook,id,intervention):Promise\<Unlocked|null>
Defined in: src/correxit/workbook.ts:875
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:848
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:906
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,passphrase):Promise\<string[]>
Defined in: src/correxit/workbook.ts:932
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
passphrase |
string | null |
Returns¶
Promise\<string[]>
provisioned recipient keys for a given workbook.
recover()¶
recover(
workbook,passphrase):Promise\<number>
Defined in: src/correxit/workbook.ts:964
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 |
passphrase |
string |
Returns¶
Promise\<number>
the number of cells successfully recovered.
refer()¶
refer(
workbook,id,reference):Promise\<Unlocked>
Defined in: src/correxit/workbook.ts:1020
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):void
Defined in: src/correxit/workbook.ts:1032
Remove a cell from a workbook's rubric.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
id |
string |
Returns¶
void
reset()¶
reset(
workbook):Promise\<void>
Defined in: src/correxit/workbook.ts:1058
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:1046
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:1063
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:1082
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:1103
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:1123
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:1143
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:1154
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:1189
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:1212
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.
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:1217
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.
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:1222
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.
The audited rubric is returned.
Parameters¶
| Parameter | Type |
|---|---|
workbook |
Workbook |
rubric |
null |
Returns¶
Promise\<null>