# Knowledge graph index

_Generated by `kg.mjs index` — do not edit. Start with [README](README.md)._

85 nodes.

## entity (8)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [scoring-item](nodes/scoring-item.md) | The item scoring configuration document - pattern (scoringPattern + rubricName), preprocessors, Score As, overrides, max score and precision penalty - looked up by itemUUID in Mongo items or the buildpack, or sent inline as /ws/stateless itemDefinition. | 34 | 4 | entity, core |
| [score](nodes/score.md) | Entity - the Score result object (patterns.score.Score) returned by every scoring route - status code, numeric score, message, echoed requestUUID, maxScoreExceeded, scoring_details and reporting_categories. | 31 | 1 | entity, payload |
| [request-archive](nodes/request-archive.md) | A log.request document - one per scored request - holding the archived score request, the resulting score/status/message, administration, timing and the downloadState that downstream transfer/review processing advances. | 20 | 3 | entity, audit |
| [candidate-response](nodes/candidate-response.md) | The student's answer as sent to the MRE - a single {content} gap, a {values:[{identifier, content}]} multi-gap object, or a list of interactions (TestNav8 QTI) that CandidateResponse.transform_json collapses into one values list. | 15 | 1 | entity, payload |
| [scoring-client](nodes/scoring-client.md) | A registered API caller in scoring.client (or the clients buildpack) - clientId plus one or two salted SHA-256 secret hashes; checked by verify_client on every public scoring request. | 15 | 2 | entity, auth |
| [item-regression](nodes/item-regression.md) | Per-item regression test set (item.regression / regressions buildpack) - saved candidate responses with their accepted expected scores, replayed against the engine to gate builds and releases. | 13 | 3 | entity, testing |
| [score-request](nodes/score-request.md) | The public scoring request payload (BaseScoreRequest / ScoreRequest / ScoreStatelessRequest) - client credentials, item/test/request ids, admin, candidateResponse, optional itemDefinition or scoringInstructions - plus a server-generated transactionId. | 12 | 3 | entity, payload |
| [dependent-logic-entry](nodes/dependent-logic-entry.md) | One element of a DependentScoringPattern's listOfDependentLogics (or a LogicalPattern dependent item): the logic config, its credit and its constraints; also the dependentLogic body of /internal-dependent-scoring. | 4 | 0 | patterns, dependent, config |

## module (20)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [core-patterns](nodes/core-patterns.md) | The 14 standard scoring-pattern classes in patterns/*.py (number, numeric, algebraic, factoring, system of equations, ordered pair, scientific notation, list/logical meta-patterns) plus BasePattern, Score and MultipleEquals. | 42 | 6 | patterns, scoring |
| [scoring-pipeline](nodes/scoring-pipeline.md) | utils/scoring_utils.py - score_with_validation and friends - item lookup, manual override, response validation, Score As, MathTrees, preprocessing, triage to in-process / threaded / internal-HTTP scoring, max-score cap, precision penalty and archiving. | 38 | 9 | core, service |
| [dependent-patterns](nodes/dependent-patterns.md) | DependentScoringPattern plus its dependent logics and dependent constraints (patterns/dependent/): partial credit when a gap is correct relative to another gap's (possibly wrong) answer. | 29 | 7 | patterns, scoring, dependent |
| [client-auth](nodes/client-auth.md) | Client authentication - verify_client checks clientUUID/clientSECRET against salted SHA-256 hashes in scoring.client or the clients buildpack (with a hard-coded secretClientId bypass); _verify_internal_credentials guards the internal API. | 22 | 2 | auth, security |
| [scoring-server](nodes/scoring-server.md) | Flask app (server.py) serving the public math scoring API on port 5000; parses and authenticates requests, delegates scoring to scoring-pipeline or instruction-processor, and serves healthcheck, regression and docs pages. | 21 | 10 | api, service |
| [regression-runner](nodes/regression-runner.md) | Regression replay tooling - tests.py (unit tests + in-process buildpack regressions for CI), scripts/run_live_regressions.py (release gate against a deployed URL), GET /regressions (apis/regression_api.py) and the legacy Mongo-driven regressions.py. | 20 | 5 | testing, release |
| [representation](nodes/representation.md) | representation/ package — detects the input representation and parses content MathML, presentation MathML, LaTeX and Math+Text (HTML) into a MathTree; also MathML XSD validation and the Score As gap builders. | 19 | 5 | math-core, parsing |
| [math-tree](nodes/math-tree.md) | math_tree/ package — the MathTree class hierarchy (operators, relations, letters, numbers, forms) every response is parsed into, with cached LaTeX/MathML/SymPy views and tree-rewriting helpers. | 17 | 2 | math-core, math-tree |
| [internal-scoring-server](nodes/internal-scoring-server.md) | Flask app (server_internal.py) on 127.0.0.1:5001 that runs one scoring pattern or one dependent-logic block per request in a memory-capped gunicorn worker, so expensive sympy work can be timed out and killed. | 16 | 6 | api, service |
| [preprocessors](nodes/preprocessors.md) | preprocessors/ package — the ordered chain of MathTree rewrites (priority, mandatory, optional) that normalises a candidate response before a pattern scores it, plus PlaceholderFilter and the text replacers. | 16 | 5 | math-core, preprocessing |
| [scoring-forms](nodes/scoring-forms.md) | Form and equivalence checkers in forms/: EquivalenceWithPrecisionAndTolerance (precision, tolerance, rounding, monetary), NumberForms (allow/reward number forms), AlgebraicForms (linear/quadratic/polynomial/…), Parabola. | 16 | 0 | patterns, forms |
| [customized-patterns](nodes/customized-patterns.md) | Per-item subclasses of standard patterns in patterns/customized_pattern/custom_files/, loaded by item _id when the item has isCustomizedPattern true. | 13 | 3 | patterns |
| [custom-patterns](nodes/custom-patterns.md) | Deprecated CustomScoringPattern: 23 hand-written per-item scoring classes in patterns/custom/ (incl. mcas/ and the custom_unit helpers), selected by item _id. | 11 | 4 | patterns, legacy |
| [scoring-constraints](nodes/scoring-constraints.md) | Validators in constraints/ that patterns apply on top of equivalence: required/disallowed numbers, operators, inequality symbols, text placement, like terms, left-to-right ×/÷. | 11 | 1 | patterns, constraints |
| [instruction-processor](nodes/instruction-processor.md) | processors/instruction_processor.py + scoring_adapters/ - backs /v1/scoreWithInstructions by inferring a pattern (NumberPattern, AlgebraicExpressionPattern or AlgebraicRelationPattern) from the MathML answer and filling it with whitelisted options and defaults. | 10 | 2 | service, scoring |
| [precision-penalty](nodes/precision-penalty.md) | processors/precision_penalty.py - Precision Point Penalty (PPP) - takes one point off a top score when the response contains a numeric relation that is false or variable relations with inconsistent solutions. | 10 | 2 | scoring |
| [ci-pipeline](nodes/ci-pipeline.md) | Jenkinsfile + TestDockerfile - unit tests, Snyk scan, buildpack generation/import, in-container regression run, then image build and push to ECR as mre-scoring:<tag> and the downstream deploy job. | 7 | 3 | ci, release |
| [mongo-data-scripts](nodes/mongo-data-scripts.md) | Operator scripts under scripts/ - mirror/backup/restore DocDB collections to local Mongo over an SSH tunnel, create/rotate client secrets, reset log.request processing for the Review Tool, and a story-script template. | 7 | 5 | ops, scripts |
| [mre-utils](nodes/mre-utils.md) | utils/ package as a code module (file map) — shared helpers; the substantial ones are sympy_utils (equivalence, SymPy construction/rounding/polynomial checks), embedded_relations, candidate_response_utils, representation sniffing, exceptions and logging. Orchestration, data access and regression files are documented on their own nodes. | 5 | 3 | math-core, utils |
| [mathematics](nodes/mathematics.md) | mathematics/ package — pattern-agnostic maths helpers on MathTree/SymPy: unit conversion (Pint), factor extraction, interval-notation bounds, solution-set comparison. | 2 | 3 | math-core |

## interface (2)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [internal-scoring-api](nodes/internal-scoring-api.md) | Loopback-only HTTP API of internal-scoring-server (port 5001) - score one pattern (/internal-scoring) or one dependent-logic block (/internal-dependent-scoring) with the shared internal secret. | 25 | 3 | api, internal |
| [scoring-api](nodes/scoring-api.md) | Public HTTP API of scoring-server (port 5000) - score against a stored item (/ws/rest), an inline item definition (/ws/stateless) or inline instructions (/v1/scoreWithInstructions), plus convert, hash, healthcheck, regressions and docs. | 25 | 5 | api |

## integration (3)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [authoring-tool](nodes/authoring-tool.md) | ktmath-authoring (separate repo) - where math items, regressions and clients are authored; its item browser scores via /ws/rest as secretClientId, its GenerateBuildpack job exports buildpacks to S3, and its transfer service / Review Tool consume log.request. | 15 | 1 | integration |
| [sympy](nodes/sympy.md) | SymPy (pinned sympy==1.14.0) — the computer-algebra library under every MathTree's .sympy view and every equivalence/form check; in-process Python library, not a network service. | 10 | 0 | library, math-core, sympy |
| [hash-pipe](nodes/hash-pipe.md) | hash_pipe (private KT package, hash_pipe==2.0.1 from pypi.ktscoringservices.com) — normalises and hashes a candidate response; keys manual score overrides and the /ws/hash endpoint. | 6 | 0 | library, math-core |

## datastore (2)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [buildpack](nodes/buildpack.md) | Versioned JSON snapshots of items, clients and regressions in S3 (buildpack-artifacts bucket, development/ or production/ prefix) that staging/prod load into memory at boot instead of reading Mongo (USE_BUILDPACK). | 19 | 4 | datastore, release |
| [mre-mongo](nodes/mre-mongo.md) | MongoDB / AWS DocumentDB database (DB_NAME, default "math"; "content" on the dev DocDB cluster) holding items, scoring.client, item.regression and the log.request scoring archive. | 16 | 5 | datastore |

## config (5)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [pattern-catalog](nodes/pattern-catalog.md) | Every scoring-pattern, dependent-logic, dependent-constraint and preprocessor name the engine accepts (constants/pattern_names.py, dependent_names.py, preprocessor_names.py), with meaning and source. | 12 | 0 | patterns, config |
| [service-config](nodes/service-config.md) | config.py environment variables and constants - MODE (DEV/QA/PROD), DB_NAME, MONGO_URL, REGRESSION_URL, USE_BUILDPACK, BUILDPACK_VERSION, INTERNAL_SECRET, plus INTERNAL_CLIENT, THREADING_TIMEOUT_SECONDS and the hard-coded internal URL. | 10 | 0 | config |
| [preprocessor-settings](nodes/preprocessor-settings.md) | Catalog of every preprocessor name (PreprocessorNames) with its tier, the item keys that switch/tune it, and a one-line meaning. | 7 | 1 | config, math-core, preprocessing |
| [deploy-runtime](nodes/deploy-runtime.md) | How the container runs - Dockerfile (python 3.14 slim, supervisor + cron + logrotate) starting two gunicorn programs, backend server:app on 5000 and internal server_internal:app on 5001 with an RLIMIT_AS cap; uwsgi/nginx configs are legacy. | 3 | 0 | config, deploy |
| [acceptable-units](nodes/acceptable-units.md) | Hard-coded unit vocabulary (constants/acceptable_units.py) by category (Distance, Liquid, Time, Mass, Energy) used to recognise and strip typed units. | 2 | 2 | config, units |

## flow (7)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [select-pattern](nodes/select-pattern.md) | How the engine picks where and with which class a pattern runs - rubricName validation, then in-process (DEV), threaded in-process parent (Dependent/Logical/ListOfPatterns), or POST /internal-scoring, and inside that PatternFactory chooses a customized per-item class, a standard pattern or a deprecated custom one. | 9 | 9 | flow, patterns |
| [score-response](nodes/score-response.md) | End-to-end scoring of one response - HTTP request to scoring-server, parse and authenticate, load item, override check, validation, Score As, MathTrees, preprocessors, pattern triage (in-process, threaded parent, or internal HTTP), cap and precision penalty, archive, JSON Score. | 7 | 10 | flow, core |
| [release-regression-gate](nodes/release-regression-gate.md) | How a scoring change reaches production - CI unit tests, buildpack import from S3, in-container regression replay, image push to ECR, then live regressions against the inactive staging/prod stack before cutover. | 5 | 7 | flow, release |
| [apply-manual-override](nodes/apply-manual-override.md) | How a reviewer-set score for one exact response is applied - the authoring side hashes the response with /ws/hash (hash_pipe) and stores {hash: score} in the item's override map; at scoring time score_with_manual_override hashes the request the same way and short-circuits on a hit. | 4 | 7 | flow, scoring |
| [stateless-score-from-ad](nodes/stateless-score-from-ad.md) | AD (adam_ad) scoring a pearson.mre QTI custom operator - POST /ws/stateless with AD's client credentials, the QTI item identifier, the inline itemDefinition and a {location, values[]} response; MRE authenticates, scores the inline item, archives only in delivery (requestUUID + testUUID present) and always answers HTTP 200 with a status code AD maps to retry/score/error. | 4 | 8 | flow, cross-app |
| [convert-representation](nodes/convert-representation.md) | POST /ws/convert - unauthenticated conversion of one math string (content/presentation MathML, LaTeX or Math+Text HTML) to content MathML, LaTeX or a human-readable tree, by parsing it to a MathTree in the public worker. | 3 | 4 | flow, math-core |
| [score-dependent-response](nodes/score-dependent-response.md) | Scoring a DependentScoringPattern item - variable substitutions, primary patterns per gap via score_with_triage, and only when the primary score is 0 each dependent logic via POST /internal-dependent-scoring, combined by pointCountingStrategy. | 1 | 8 | flow, patterns |

## concept (21)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [scoring-pattern](nodes/scoring-pattern.md) | A scoring pattern: the configurable rule class (patterns/) that decides whether a math response is correct. | 13 | 5 | glossary, patterns |
| [symbolic-equivalence](nodes/symbolic-equivalence.md) | equiv — how MRE decides two SymPy expressions are mathematically equal — numeric tolerance first, then a cascade of simplify/expand/nsimplify/root-forcing strategies (utils/sympy_utils.py). | 9 | 1 | glossary, math-core, sympy |
| [multiple-equals](nodes/multiple-equals.md) | multipleEqualsConstraint - how a response with several relation signs (1 = 2/2 = 0.5+0.5) is split into subgaps and which of them must match: none, atLeastOne, all, atLeastOneAllPairs. | 8 | 1 | glossary, patterns |
| [score-as](nodes/score-as.md) | Glossary term Score As — the item setting that builds derived gaps by filling a template (MathML or LaTeX) with the candidate's gap contents, then scores the derived gap(s). | 8 | 1 | glossary, math-core |
| [dependent-constraint](nodes/dependent-constraint.md) | A constraint entry in listOfConstraints (dependent logic, ListOfExpressions entry, SystemOfEquations) that must hold for credit - className plus constraintApplication INDEPENDENT/DEPENDENT/GAP and optional gapId. | 7 | 2 | glossary, dependent |
| [math-expression-tree](nodes/math-expression-tree.md) | MathTree — the parsed, representation-independent tree of a response (or answer) that preprocessors rewrite and patterns score; carried on a gap as `mathTree` and over the wire as `mathTreeJson`. | 7 | 1 | glossary, math-core |
| [mathml](nodes/mathml.md) | MathML input representation — content MathML (the primary format, `mathml`) and presentation MathML (`presMathml`); also the canonical internal output (`tree.mathml`). | 7 | 1 | glossary, math-core, representation |
| [latex](nodes/latex.md) | LaTeX input representation (`latex`) — the fallback when content is neither HTML nor MathML; parsed by a hand-written tokenizer + recursive-descent LaTeXParser. | 6 | 1 | glossary, math-core, representation |
| [math-plus-text](nodes/math-plus-text.md) | Math+Text (MPT) input representation (`mathPlusText`, enum HTML) — XHTML paragraphs mixing prose and <math> fragments; parsed by HtmlParser and converted to content MathML before scoring. | 6 | 1 | glossary, math-core, representation |
| [point-counting-strategy](nodes/point-counting-strategy.md) | pointCountingStrategy - how a parent pattern adds up child results: return_first_correct, sum_each_correct, one_for_each_correct, points_for_number_correct. | 6 | 2 | glossary, patterns |
| [precision-and-tolerance](nodes/precision-and-tolerance.md) | Equivalence with precision, tolerance and rounding - the numeric-acceptance settings (requirePrecision, tolerance, roundingPermission, precisionType monetary) applied by EquivalenceWithPrecisionAndTolerance. | 5 | 1 | glossary, patterns |
| [dependent-gap](nodes/dependent-gap.md) | Independent vs dependent gap - in dependent scoring the independent gap holds the student's earlier work and the dependent gap is judged against what that work implies. | 3 | 1 | glossary, dependent |
| [manual-score-override](nodes/manual-score-override.md) | Manual score override - an item's `override` map from canonical response hash to score; a hit returns that score without running preprocessors or the pattern. | 3 | 2 | glossary |
| [secret-client-id](nodes/secret-client-id.md) | "secretClientId" - the magic clientUUID that verify_client accepts without any secret; used by the authoring tool item browser, regression runners and curls.txt. | 3 | 1 | glossary, security |
| [number-form](nodes/number-form.md) | Number form - the written shape of a numeric answer (integer, decimal, reduced fraction, mixed number, ratio, …) that NumberPattern can require (allow*) or reward with bonus points (reward*, formPointValue). | 2 | 1 | glossary, patterns |
| [placeholder](nodes/placeholder.md) | Placeholder / box (□): an empty input slot in a response, parsed as the Empty MathTree node; filtered out by PlaceholderFilter unless a priority preprocessor turns it into a variable. | 2 | 1 | glossary, math-core |
| [transaction-id](nodes/transaction-id.md) | transactionId (tid) - a server-generated uuid4 hex per public scoring request, used to correlate log lines and internal-server calls; not the caller's requestUUID. | 2 | 1 | glossary |
| [parent-pattern](nodes/parent-pattern.md) | Parent pattern - a pattern that scores by calling other patterns (DependentScoringPattern, LogicalPattern, ListOfPatternsPattern); it runs in a thread in the public worker so its children can use the internal server. | 1 | 2 | glossary, patterns |
| [rubric-name](nodes/rubric-name.md) | rubricName - the short pattern class name (e.g. NumberPattern) on an item that selects the scoring pattern; stored on Mongo/buildpack items, derived from scoringPattern.className for /ws/stateless. | 1 | 2 | glossary |
| [scoring-status-code](nodes/scoring-status-code.md) | The MRE scoring status code (Score.status, enum Status 0-11) - 0 scored, 1 unscorable (final), 2 service error (retry), 3-11 request errors; scoring routes always answer HTTP 200 and signal everything through this field. | 1 | 1 | glossary |
| [invalid-sympy-value](nodes/invalid-sympy-value.md) | InvalidSympyValue - the sentinel sympy.Basic subclass a MathTree's .sympy becomes when it can't be built (placeholders, unsupported symbols, division by zero, any exception); never equal to anything else. | 0 | 2 | glossary, math-core |

## capability (17)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [dependent-scoring](nodes/dependent-scoring.md) | Carry-forward partial credit - a later answer earns points when it is correct for the student's own (possibly wrong) earlier answer. | 3 | 5 | capability, dependent |
| [response-hashing](nodes/response-hashing.md) | Fingerprint a student response so content staff can pin a manual score to that exact answer (POST /ws/hash plus item overrides). | 2 | 2 | capability |
| [buildpack-item-bank](nodes/buildpack-item-bank.md) | Staging and production score against a frozen, versioned snapshot of the item bank and client list (a buildpack) that passed regressions, instead of the live authoring database. | 1 | 4 | capability, release |
| [combined-pattern-scoring](nodes/combined-pattern-scoring.md) | Score multi-part or multi-answer items by combining several patterns with partial credit, any-order matching, and AND/OR/NOT logic. | 1 | 2 | capability |
| [item-specific-scoring](nodes/item-specific-scoring.md) | One-off scoring code for a single item when no configuration of the standard patterns fits (customized patterns; legacy custom patterns). | 1 | 2 | capability |
| [multi-gap-expression-scoring](nodes/multi-gap-expression-scoring.md) | Capability (product feature) - score an expression the student builds across several boxes as one combined expression (Score As). | 1 | 2 | capability |
| [stateless-scoring](nodes/stateless-scoring.md) | Score a math answer against scoring rules sent in the same request (POST /ws/stateless), so the caller owns the item definition and MRE needs no copy of the item. | 1 | 3 | capability |
| [unit-aware-scoring](nodes/unit-aware-scoring.md) | Score answers typed with units - ignore recognised unit words (5 km → 5) or, on NumberPattern, convert between units (cm vs m) when the answer carries units. | 1 | 3 | capability, units |
| [answer-form-requirements](nodes/answer-form-requirements.md) | Require or reward the written shape of an answer (reduced fraction, mixed number, factored, expanded, linear…) and restrict which numbers or operators may be used. | 0 | 4 | capability |
| [item-regression-testing](nodes/item-regression-testing.md) | Every item carries saved student answers with their accepted scores; each build and release replays them all and is blocked if any score changes. | 0 | 2 | capability, release |
| [math-conversion](nodes/math-conversion.md) | Convert a math answer between MathML, LaTeX and a readable form, for authoring and debugging (POST /ws/convert). | 0 | 2 | capability |
| [precision-point-penalty](nodes/precision-point-penalty.md) | Take one point off a full-credit answer when the student's shown work contains a false numeric statement or inconsistent equations (PPP). | 0 | 2 | capability |
| [scoring-review-archive](nodes/scoring-review-archive.md) | Every scored test response is archived (log.request) so the authoring side's transfer service and Review Tool can report on item performance and let content staff review and re-score responses. | 0 | 3 | capability, audit |
| [scoring-with-instructions](nodes/scoring-with-instructions.md) | Score a MathML answer from a short instruction (the correct answer plus a few options) without authoring a full item; the engine infers Number, Algebraic Expression or Algebraic Relation scoring (POST /v1/scoreWithInstructions). | 0 | 2 | capability |
| [show-work-scoring](nodes/show-work-scoring.md) | Score responses that show work as a chain of equals signs (2+3 = 5 = 10/2), requiring one, every, or no step to be correct. | 0 | 2 | capability |
| [stored-item-scoring](nodes/stored-item-scoring.md) | Score a student's math answer against an item whose scoring rules are stored in the MRE item bank, by item id (POST /ws/rest). | 0 | 4 | capability |
| [tolerance-scoring](nodes/tolerance-scoring.md) | Accept numeric answers within a tolerance, with a required number of decimal places, rounded a permitted way, or in monetary format. | 0 | 3 | capability |