feat(ts-sdk): Knowledge Graph client layer by adnanrhussain · Pull Request #97 · learning-commons-org/evaluators

adnanrhussain · 2026-06-10T03:39:17Z

Summary

Adds a typed HTTP client for the Learning Commons Knowledge Graph API. Infrastructure used by the Math Standards Alignment Evaluator (PR #91), kept as a separate PR so it can be reviewed independently.

KnowledgeGraphClient — single class that handles all KG HTTP calls with concurrency limiting (p-limit), promise caching (evict-on-reject so transient 429/503 errors are retryable), 30s timeout, and cursor-based pagination for learning components
KnowledgeGraphError — typed error for KG HTTP failures, exported from SDK root
platformApiKey added to BaseEvaluatorConfig for any evaluator that needs KG access
kg-api.d.ts generated from the official spec at docs.learningcommons.org/api-reference/knowledge-graph-api/openapi.yaml via npm run generate:kg-types

PR #91 depends on this

ahussain/math-standards-alignment (PR #91) must be merged after this one.

Test plan

npm test -- --run tests/unit/knowledge-graph — 19 tests pass
npx tsc --noEmit — 0 errors
npm run lint — 0 errors

Adds a typed HTTP client for the Learning Commons Knowledge Graph API, used as infrastructure by the Math Standards Alignment Evaluator. - KnowledgeGraphApiRepository — fetches standards and learning components via the KG REST API with cursor-based pagination, 30s timeout, and correct MP standard filtering by normalizedStatementType - KnowledgeGraphClient — concurrency-limited wrapper with promise caching (evicts on rejection so transient errors are retryable) - KnowledgeGraphError — typed error for KG HTTP failures - platformApiKey added to BaseEvaluatorConfig - kg-api.d.ts generated from official spec at docs.learningcommons.org/api-reference/knowledge-graph-api/openapi.yaml via npm run generate:kg-types (openapi-typescript devDep)

codecov · 2026-06-10T03:42:13Z

Codecov Report

❌ Patch coverage is 97.33333% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
sdks/typescript/src/knowledge-graph/client.ts	97.22%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

Removes the KnowledgeGraphApiRepository/StandardsRepository abstraction layer. KnowledgeGraphClient now handles HTTP calls directly alongside its caching and concurrency logic — one class, one responsibility. - repository.ts removed; HTTP logic moved into client.ts private methods - StandardsRepository interface removed — no longer needed without the JSON repository variant - Tests consolidated into client.test.ts covering all HTTP paths, caching eviction, pagination, and error mapping

Copilot

Pull request overview

Adds a TypeScript Knowledge Graph (KG) client layer to the SDK to support evaluators that need to fetch academic standards and learning components from the Learning Commons KG REST API.

Changes:

Introduces KnowledgeGraphClient with concurrency limiting, promise caching, and KG HTTP error handling.
Adds Knowledge Graph-specific types/utilities (AcademicStandard, LearningComponent, StandardInfo, parseGradeFromStandard) and generated OpenAPI typings (kg-api.d.ts).
Extends SDK configuration/error surface with platformApiKey on BaseEvaluatorConfig and KnowledgeGraphError exported from the SDK root.

Reviewed changes

Copilot reviewed 9 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sdks/typescript/src/knowledge-graph/client.ts	Implements KG HTTP fetch wrapper, caching, concurrency limiting, and KG query helpers.
sdks/typescript/src/knowledge-graph/types.ts	Defines KG-facing domain types and grade parsing helper.
sdks/typescript/src/knowledge-graph/index.ts	Barrel exports for KG client/types.
sdks/typescript/src/knowledge-graph/README.md	Documents the KG client module and regeneration of generated types.
sdks/typescript/src/knowledge-graph/kg-api.d.ts	Generated OpenAPI TypeScript types for KG API.
sdks/typescript/src/errors.ts	Adds `KnowledgeGraphError`.
sdks/typescript/src/index.ts	Exports `KnowledgeGraphError` from SDK root.
sdks/typescript/src/evaluators/base.ts	Adds `platformApiKey` to base evaluator config.
sdks/typescript/tests/unit/knowledge-graph/client.test.ts	Adds unit tests for KG client behavior and error handling.
sdks/typescript/package.json	Adds `generate:kg-types` script and `openapi-typescript` dev dependency.
sdks/typescript/package-lock.json	Lockfile updates reflecting dependency additions/adjustments.

Files not reviewed (1)

sdks/typescript/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…inated Adds the same hasMore guard as getLearningComponents — if limit=500 is ever insufficient for a grade, callers get an explicit error rather than a silent truncation.

The API confirmed it never returns 'Mathematical Practice' as a normalizedStatementType for Mathematics subject queries — the URL constraint normalizedStatementType=Standard already handles filtering. The client-side filter was dead code based on a wrong assumption. README stripped to bare minimum.

API confirmed HS standards are indexed under grades 9-12, not 'HS'. parseGradeFromStandard now throws for HS-prefixed codes — callers pass the explicit grade (9/10/11/12) when evaluating HS standards.

The evaluator requires callers to pass grade explicitly on every call. Parsing grade from a statementCode prefix was ambiguous (HS codes span 4 grade years) and is no longer needed.

Evaluates whether assessment questions align to CCSS math standards by checking alignment at the learning-component level via the LC Knowledge Graph API (see PR #97 for the KG client layer). Three evaluation methods: - evaluate(question, grade, statementCode) — single pair, primitive - evaluateQuestionBank(questions[], statementCodes[]) — M×N cross-product with optional coarse filter (useCoarseFilter: true) - evaluateByGrade(questions[], grade) — grade-level discovery wrapper Model, temperature, supported grades, and max question length all read from config.json / input_schema.json. platformApiKey doubles as partnerKey for telemetry when not set separately.

czi-fsisenda

🚀

czi-fsisenda · 2026-06-11T03:35:50Z

czi-fsisenda · 2026-06-11T03:40:34Z

+    throw new AuthenticationError(`Knowledge Graph authentication failed: ${body}`, response.status);
+  }
+  if (response.status === 429) {
+    throw new RateLimitError(`Knowledge Graph rate limit exceeded: ${body}`);


[P1] Is this retryable?

czi-fsisenda · 2026-06-11T03:41:47Z

+  private readonly standardInfoCache = new Map<string, Promise<StandardInfo>>();
+  private readonly lcCache = new Map<string, Promise<LearningComponent[]>>();


We have caching! Nice!

[P2] AI says these are unbounded. Valid concern. But I think we can fit all the data these have in memory, right?

czi-fsisenda · 2026-06-11T03:46:31Z

+  private readonly lcCache = new Map<string, Promise<LearningComponent[]>>();
+
+  constructor(apiKey: string, concurrency = 20) {
+    this.apiKey = apiKey;


[P1] validate not empty.
I think you check the config elsewhere for this, right?

czi-fsisenda · 2026-06-11T03:51:54Z

[P1] add to .gitattributes as generated

LearningComponent now exposes the KG system identifier alongside description. Used by the evaluator to verify model responses map to the correct learning component — eliminating silent mismatches.

adnanrhussain mentioned this pull request Jun 10, 2026

feat(ts-sdk): Math Standards Alignment Evaluator #91

Open

5 tasks

adnanrhussain requested a review from Copilot June 10, 2026 03:55

Copilot started reviewing on behalf of adnanrhussain June 10, 2026 03:55 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

Comment thread sdks/typescript/src/knowledge-graph/client.ts

Comment thread sdks/typescript/src/index.ts

Comment thread sdks/typescript/src/errors.ts

Comment thread sdks/typescript/src/knowledge-graph/README.md Outdated

fix: throw KnowledgeGraphError when getStandardsByGrade result is pag…

8418e6a

…inated Adds the same hasMore guard as getLearningComponents — if limit=500 is ever insufficient for a grade, callers get an explicit error rather than a silent truncation.

adnanrhussain requested review from a team, czi-fsisenda and georgemelvin June 10, 2026 04:09

adnanrhussain added 3 commits June 9, 2026 21:20

fix: remove HS from parseGradeFromStandard; clean up comment

ee3bf26

API confirmed HS standards are indexed under grades 9-12, not 'HS'. parseGradeFromStandard now throws for HS-prefixed codes — callers pass the explicit grade (9/10/11/12) when evaluating HS standards.

refactor: remove parseGradeFromStandard — grade is always explicit

ae7ca9c

The evaluator requires callers to pass grade explicitly on every call. Parsing grade from a statementCode prefix was ambiguous (HS codes span 4 grade years) and is no longer needed.

czi-fsisenda approved these changes Jun 11, 2026

View reviewed changes

feat: preserve LC identifier from KG API response

c185b70

LearningComponent now exposes the KG system identifier alongside description. Used by the evaluator to verify model responses map to the correct learning component — eliminating silent mismatches.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ts-sdk): Knowledge Graph client layer#97

feat(ts-sdk): Knowledge Graph client layer#97
adnanrhussain wants to merge 7 commits into
mainfrom
ahussain/kg-client

adnanrhussain commented Jun 10, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

czi-fsisenda left a comment

Uh oh!

czi-fsisenda Jun 11, 2026

Uh oh!

czi-fsisenda Jun 11, 2026

Uh oh!

czi-fsisenda Jun 11, 2026

Uh oh!

czi-fsisenda Jun 11, 2026

Uh oh!

czi-fsisenda Jun 11, 2026

Uh oh!

czi-fsisenda Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		private readonly standardInfoCache = new Map<string, Promise<StandardInfo>>();
		private readonly lcCache = new Map<string, Promise<LearningComponent[]>>();

Conversation

adnanrhussain commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

PR #91 depends on this

Test plan

Uh oh!

codecov Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

czi-fsisenda left a comment

Choose a reason for hiding this comment

Uh oh!

czi-fsisenda Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

czi-fsisenda Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

czi-fsisenda Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

czi-fsisenda Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

czi-fsisenda Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

czi-fsisenda Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adnanrhussain commented Jun 10, 2026 •

edited

Loading

codecov Bot commented Jun 10, 2026 •

edited

Loading