Getting Started

Installation

These examples describe the unreleased 0.2.0 development version. From the repository root, install this checkout:

pip install .
# or with uv
uv sync

Requires Python 3.10–3.14. NumPy, SciPy, Click and Rich are installed automatically. pip install knowledgespaces installs the latest published PyPI release, which can differ from this checkout.

Your first knowledge structure

A knowledge structure is a family of subsets (called knowledge states) of a domain of items. Each state represents a plausible combination of items a student might have mastered.

The simplest way to build one is from prerequisite relations:

import knowledgespaces as ks

structure = ks.space_from_prerequisites(
    items=["add", "sub", "mul"],
    prerequisites=[("add", "sub"), ("sub", "mul")],
)

print(structure.n_states)          # 4
print(structure.is_learning_space) # True

The prerequisites say: addition is required before subtraction, and subtraction before multiplication. This gives 4 valid states:

State

Interpretation

\(\emptyset\)

Knows nothing

\(\{add\}\)

Knows only addition

\(\{add, sub\}\)

Knows addition and subtraction

\(\{add, sub, mul\}\)

Knows everything

Assess a student

Given a student’s responses, estimate their knowledge state:

result = ks.assess(structure, {"add": True, "sub": True, "mul": False})

print(result["state"])        # {'add', 'sub'}
print(result["probability"])  # Posterior mass under the assumed model
print(result["outer_fringe"]) # {'mul'} — what to learn next

The outer fringe contains items that can be added individually while remaining in the structure. The inner fringe contains items whose individual removal leaves an admissible state. These are structural boundaries of the estimated state; they do not reconstruct the student’s learning history or guarantee readiness independently of the model.

Adaptive assessment

For a real assessment, provide multiple instances (concrete questions) per item. The engine picks the most informative question at each step:

result = ks.adaptive_assess(
    structure,
    ask_fn=my_question_function,
    instances={
        "add": ["3+2", "7+5", "12+9"],
        "sub": ["8-3", "15-7"],
        "mul": ["4*3", "6*7"],
    },
)
print(f"Estimated state: {result['state']}")
print(f"Questions asked: {result['questions_asked']}")

Command-line interface

If you prefer working from the terminal, the ks command provides interactive tools that don’t require writing Python:

# Inspect a file
ks inspect structure.json

# Derive a structure by answering expert questions
ks query add sub mul

# Run an adaptive assessment
ks assess structure.json

See Command Line Interface for the full CLI reference.

What’s next?