Command Line Interface

The knowledgespaces command provides three interactive tools that work directly from the terminal. They are designed for domain experts, teachers, and researchers who want to use KST without writing Python code.

After installing the library, the knowledgespaces command is available system-wide:

ks --help
ks --version

All commands support:

  • --json for machine-readable JSON output (suitable for piping into jq, scripts, etc.)

  • --no-color for environments without color support (CI, log files)

ks inspect — examine a KST file

Load a knowledge structure, surmise relation, or skill map and display its properties.

# JSON files are auto-detected by schema
ks inspect structure.json
ks inspect relation.json
ks inspect skillmap.json

# CSV files require --kind (format is ambiguous)
ks inspect data.csv --kind structure
ks inspect prereqs.csv --kind relation
ks inspect mapping.csv --kind skill-map

Structure output

For a knowledge structure, the command shows:

  • Domain and item count

  • Number of states and their size distribution

  • Structural properties: knowledge space, closure space, well-graded, learning space

  • Atoms and base (for knowledge spaces)

  • Hanging states (structural problems)

Optional flags:

ks inspect structure.json --states    # full state matrix
ks inspect structure.json --paths     # learning paths from empty set to full domain
ks inspect structure.json --paths --max-paths 50

Relation output

For a surmise relation, the command shows:

  • Edge counts (stored, transitive closure, Hasse diagram)

  • Whether the relation is a partial order (antisymmetric on the closure)

  • Topological levels, minimal and maximal items

  • Hasse diagram edges

If the relation contains cycles, the command warns explicitly and does not show the Hasse diagram or levels (which are undefined for cyclic relations).

Skill map output

For a skill map, the command shows the binary matrix \(\mu\) mapping items to required skills.

Machine-readable output

ks inspect structure.json --json
ks inspect structure.json --states --paths --json

The --states and --paths flags also affect the JSON output, adding "states" and "learning_paths" fields respectively.

ks query — derive a structure from expert knowledge

Run the QUERY algorithm (Koppen & Doignon, 1990) interactively. You play the role of the expert, answering prerequisite questions about your domain.

ks query add sub mul div

The algorithm asks questions following the original Koppen & Doignon (1990) failure-based formulation:

Q1. If a student has not mastered add, can we conclude they have also not mastered sub?
     y/n [y/n]:
Q2. If a student has not mastered any of [add, mul],
     can we conclude they have also not mastered div?
     y/n [y/n]:

The logic: a “yes” answer means the prerequisite relationship holds (failing the listed items implies failing the target item).

At the end, the derived knowledge structure is displayed with full statistics (expert queries vs. inferred answers per block).

Options

# Items from a file (one per line)
ks query --items-file items.txt

# Skip Phase 0 (Qmax minimality test)
ks query add sub mul --no-qmax

# Only Block 1 (no group queries)
ks query add sub mul --max-block 1

# Save the result
ks query add sub mul -o structure.json
ks query add sub mul -o structure.csv

# Machine-readable output
ks query add sub mul --json

How many questions?

The number of expert queries depends on the domain size and the prerequisite structure. The algorithm uses transitivity, antisymmetry, and monotonicity to skip redundant questions. For \(n\) items:

  • Block 1 (pair queries): up to \(n(n-1)\), typically much fewer

  • Block 2 (group queries, \(|A|=2\)): up to \(\binom{n-1}{2} \times n\), but most are inferred

ks assess — adaptive student assessment

Run an adaptive assessment using the BLIM model and Expected Information Gain (EIG) item selection. The engine picks the most informative question at each step and updates the posterior distribution over knowledge states.

ks assess structure.json

The student (or someone on their behalf) answers:

Q1.  [sub] - correct? [y/n]:
Q2.  [add] - correct? [y/n]:
Q3.  [mul] - correct? [y/n]:

At the end, the command shows:

  • The estimated knowledge state and its probability

  • Inner fringe (recently consolidated) and outer fringe (ready to learn next)

  • Marginal mastery probability per item (with a visual bar)

  • Full response history

Multi-instance mode

In a real assessment, each item (competency) should be tested through multiple concrete questions. Provide an instance pool as a JSON file:

{
    "add": ["3+2", "7+5", "12+9"],
    "sub": ["8-3", "15-7", "20-6"],
    "mul": ["4*3", "6*7", "9*8"]
}

ks assess structure.json --instances pool.json

The engine selects the best un-asked instance, maps it to its parent item for the BLIM update, and never repeats the same question.

BLIM parameters

ks assess structure.json --beta 0.05 --eta 0.1

  • --beta: slip probability (P(incorrect | mastered)), default 0.1

  • --eta: guess probability (P(correct | not mastered)), default 0.2

The constraint \(\beta + \eta < 1\) is enforced.

Stopping rules

ks assess structure.json --threshold 0.95 --max-questions 15

  • --threshold: stop when the most likely state exceeds this probability (default 0.85)

  • --max-questions: hard limit on questions asked (default 25)

The assessment stops at whichever condition is met first.