Getting Started

Installation

pip install knowledgespaces
# or with uv
uv add knowledgespaces

Requires Python 3.10+ and numpy.

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"])  # ~0.72
print(result["outer_fringe"]) # {'mul'} — what to learn next

The outer fringe tells you what the student is ready to learn next. The inner fringe tells you what they most recently consolidated.

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 knowledgespaces 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?