> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PowerPath

> PowerPath API client for adaptive learning

## Overview

The `@timeback/powerpath` package provides a client for the PowerPath API, enabling:

* **Assessments**: Create tests, attempts, and submit responses
* **Placement Tests**: Determine appropriate grade level
* **Screening**: Session management and test assignment
* **Lesson Plans**: Course progress and lesson plan operations
* **Test Assignments**: CRUD operations for test assignments

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @timeback/powerpath
  ```

  ```bash pnpm theme={null}
  pnpm add @timeback/powerpath
  ```

  ```bash yarn theme={null}
  yarn add @timeback/powerpath
  ```

  ```bash bun theme={null}
  bun add @timeback/powerpath
  ```

  ```bash pip theme={null}
  pip install timeback-powerpath
  ```

  ```bash uv theme={null}
  uv add timeback-powerpath
  ```
</CodeGroup>

## Quick Start

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { PowerPathClient } from '@timeback/powerpath'

  const client = new PowerPathClient({
  	env: 'staging',
  	auth: {
  		clientId: process.env.POWERPATH_CLIENT_ID!,
  		clientSecret: process.env.POWERPATH_CLIENT_SECRET!,
  	},
  })

  const level = await client.placement.getCurrentLevel({ student: 'student-123', subject: 'Math' })
  ```

  ```python Python theme={null}
  from timeback_powerpath import PowerPathClient

  client = PowerPathClient(
      env="staging",
      client_id=os.environ["POWERPATH_CLIENT_ID"],
      client_secret=os.environ["POWERPATH_CLIENT_SECRET"],
  )

  level = await client.placement.get_current_level({"student": "student-123", "subject": "Math"})
  ```
</CodeGroup>

## Client Structure

<CodeGroup>
  ```typescript TypeScript theme={null}
  const client = new PowerPathClient(options)

  client.assessments // Tests, attempts, and responses
  client.lessonPlans // Course lesson plans and progress
  client.placement // Placement testing
  client.screening // MAP test sessions
  client.syllabus // Course structure
  client.testAssignments // Test assignment CRUD
  ```

  ```python Python theme={null}
  client = PowerPathClient(options)

  client.assessments        # Tests, attempts, and responses
  client.lesson_plans       # Course lesson plans and progress
  client.placement          # Placement testing
  client.screening          # MAP test sessions
  client.syllabus           # Course structure
  client.test_assignments   # Test assignment CRUD
  ```
</CodeGroup>

## Typed Responses

All methods return typed responses:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import type { ExternalTestCreateResponse, GetNextPlacementTestResponse } from '@timeback/powerpath'

  const test: ExternalTestCreateResponse = await client.assessments.createExternalTestOut({
  	courseId: 'course-123',
  	lessonType: 'test-out',
  	toolProvider: 'mastery-track',
  	grades: [3],
  	xp: 10,
  	resourceMetadata: { subject: 'Math' },
  })
  console.log(test.lessonId, test.resourceId)

  const next: GetNextPlacementTestResponse = await client.placement.getNextPlacementTest({
  	student: 'student-123',
  	subject: 'Math',
  })
  console.log(`${next.availableTests} tests available, next: ${next.lesson}`)
  ```

  ```python Python theme={null}
  from timeback_powerpath import ExternalTestCreateResponse, GetNextPlacementTestResponse

  test = await client.assessments.create_external_test_out({
      "course_id": "course-123",
      "lesson_type": "test-out",
      "tool_provider": "mastery-track",
      "grades": [3],
      "xp": 10,
      "resource_metadata": {"subject": "Math"},
  })
  print(test.lesson_id, test.resource_id)

  next_test = await client.placement.get_next_placement_test({
      "student": "student-123",
      "subject": "Math",
  })
  print(f"{next_test.available_tests} tests available, next: {next_test.lesson}")
  ```
</CodeGroup>

## Assessments

Create and manage assessments, attempts, and responses.

### Create Tests

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.assessments.createInternalTest({ studentId, subject, gradeLevel })
  client.assessments.createExternalTestOut({
  	courseId,
  	lessonType,
  	toolProvider,
  	grades,
  	xp,
  	resourceMetadata,
  })
  client.assessments.createExternalPlacementTest({ studentId, subject })
  ```

  ```python Python theme={null}
  await client.assessments.create_internal_test({
      "course_id": course_id,
      "lesson_type": lesson_type,
      "test_type": test_type,
      "grades": grades,
      "xp": xp,
  })
  await client.assessments.create_external_test_out({
      "course_id": course_id,
      "lesson_type": lesson_type,
      "tool_provider": tool_provider,
      "grades": grades,
      "xp": xp,
      "resource_metadata": resource_metadata,
  })
  await client.assessments.create_external_placement_test({
      "course_id": course_id,
      "tool_provider": tool_provider,
      "grades": grades,
  })
  ```
</CodeGroup>

### Manage Attempts

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.assessments.createNewAttempt({ studentId, testId })
  client.assessments.getAttempts({ studentId, testId })
  client.assessments.resetAttempt({ attemptId })
  ```

  ```python Python theme={null}
  await client.assessments.create_new_attempt({"student": student_id, "lesson": lesson_id})
  await client.assessments.get_attempts({"student": student_id, "lesson": lesson_id})
  await client.assessments.reset_attempt({"student": student_id, "lesson": lesson_id})
  ```
</CodeGroup>

### Questions and Responses

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.assessments.getNextQuestion({ attemptId })
  client.assessments.updateStudentQuestionResponse({ attemptId, questionId, response })
  client.assessments.finalStudentAssessmentResponse({ attemptId })
  client.assessments.getAssessmentProgress({ studentId, testId })
  ```

  ```python Python theme={null}
  await client.assessments.get_next_question({"student": student_id, "lesson": lesson_id})
  await client.assessments.update_student_question_response({"student": student_id, "question": question_id, "response": response, "lesson": lesson_id})
  await client.assessments.final_student_assessment_response({"student": student_id, "lesson": lesson_id})
  await client.assessments.get_assessment_progress({"student": student_id, "lesson": lesson_id})
  ```
</CodeGroup>

## Placement

Manage placement testing and determine appropriate grade levels. All query methods take `{ student, subject }`:

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.placement.getCurrentLevel({ student, subject })
  client.placement.getAllPlacementTests({ student, subject })
  client.placement.getNextPlacementTest({ student, subject })
  client.placement.getSubjectProgress({ student, subject })
  client.placement.resetUserPlacement({ student, subject })
  ```

  ```python Python theme={null}
  await client.placement.get_current_level({"student": student, "subject": subject})
  await client.placement.get_all_placement_tests({"student": student, "subject": subject})
  await client.placement.get_next_placement_test({"student": student, "subject": subject})
  await client.placement.get_subject_progress({"student": student, "subject": subject})
  await client.placement.reset_user_placement({"student": student, "subject": subject})
  ```
</CodeGroup>

| Method                   | Returns           | Description                     |
| ------------------------ | ----------------- | ------------------------------- |
| `getCurrentLevel()`      | `PlacementLevel`  | Current placement grade level   |
| `getAllPlacementTests()` | `PlacementTest[]` | All placement tests for student |
| `getNextPlacementTest()` | `PlacementTest`   | Next recommended test           |
| `getSubjectProgress()`   | `SubjectProgress` | Progress in subject             |
| `resetUserPlacement()`   | `void`            | Reset placement to start over   |

## Screening

Manage screening sessions and results.

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.screening.getResults(userId)
  client.screening.getSession(userId)
  client.screening.resetSession({ userId })
  client.screening.assignTest({ userId, subject })
  ```

  ```python Python theme={null}
  await client.screening.get_results(user_id)
  await client.screening.get_session(user_id)
  await client.screening.reset_session({"user_id": user_id})
  await client.screening.assign_test({"user_id": user_id, "subject": subject})
  ```
</CodeGroup>

## Lesson Plans

Manage lesson plans and course progress.

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.lessonPlans.get(courseId, userId)
  client.lessonPlans.create({ courseId, userId, classId? })
  client.lessonPlans.getCourseProgress(courseId, studentId)
  client.lessonPlans.getTree(lessonPlanId)
  client.lessonPlans.getStructure(lessonPlanId)
  client.lessonPlans.listOperations(lessonPlanId)
  client.lessonPlans.createOperations(lessonPlanId, { operation: [{ type: 'set-skipped', payload: { target: { type: 'resource', id: itemId }, value: true } }] })
  client.lessonPlans.sync(lessonPlanId)
  client.lessonPlans.recreate(lessonPlanId)
  client.lessonPlans.deleteAll(courseId)
  ```

  ```python Python theme={null}
  await client.lesson_plans.get(course_id, user_id)
  await client.lesson_plans.create({"course_id": course_id, "user_id": user_id, "class_id": class_id})
  await client.lesson_plans.get_course_progress(course_id, student_id)
  await client.lesson_plans.get_tree(lesson_plan_id)
  await client.lesson_plans.get_structure(lesson_plan_id)
  await client.lesson_plans.list_operations(lesson_plan_id)
  await client.lesson_plans.create_operations(lesson_plan_id, {"operation": [{"type": "set-skipped", "payload": {"target": {"type": "resource", "id": item_id}, "value": True}}]})
  await client.lesson_plans.sync(lesson_plan_id)
  await client.lesson_plans.recreate(lesson_plan_id)
  await client.lesson_plans.delete_all(course_id)
  ```
</CodeGroup>

## Syllabus

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.syllabus.get(courseSourcedId)
  ```

  ```python Python theme={null}
  await client.syllabus.get(course_sourced_id)
  ```
</CodeGroup>

## Test Assignments

CRUD operations for test assignments.

<CodeGroup>
  ```typescript TypeScript theme={null}
  client.testAssignments.list({ studentId })
  client.testAssignments.create({ studentId, testId, dueDate })
  client.testAssignments.get(assignmentId)
  client.testAssignments.update(assignmentId, { status })
  client.testAssignments.delete(assignmentId)
  client.testAssignments.bulk({ assignments: [{ studentId, testId }] })
  ```

  ```python Python theme={null}
  await client.test_assignments.list({"student": student_id})
  await client.test_assignments.create({"student": student_id, "subject": subject, "grade": grade})
  await client.test_assignments.get(assignment_id)
  await client.test_assignments.update(assignment_id, {"test_name": test_name})
  await client.test_assignments.delete(assignment_id)
  await client.test_assignments.bulk({"items": [{"student": student_id, "subject": subject, "grade": grade}]})
  ```
</CodeGroup>

## Error Handling

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { NotFoundError, PowerPathError } from '@timeback/powerpath/errors'

  try {
  	await client.testAssignments.get('missing-id')
  } catch (error) {
  	if (error instanceof NotFoundError) {
  		console.log('Assignment not found')
  	} else if (error instanceof PowerPathError) {
  		console.log(error.statusCode)
  		console.log(error.message)
  	}
  }
  ```

  ```python Python theme={null}
  from timeback_powerpath import NotFoundError, PowerPathError

  try:
      await client.test_assignments.get("missing-id")
  except NotFoundError:
      print("Assignment not found")
  except PowerPathError as error:
      print(error)
  ```
</CodeGroup>

## SDK Integration

When using the full SDK:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { createTimeback } from '@timeback/sdk'

  const timeback = await createTimeback({
  	/* ... */
  })

  const level = await timeback.api.powerpath.placement.getCurrentLevel({
  	student: 'student-123',
  	subject: 'Math',
  })
  ```

  ```python Python theme={null}
  from timeback.server import create_server, TimebackConfig, ApiCredentials

  timeback = create_server(TimebackConfig(
      env="staging",
      api=ApiCredentials(
          client_id=os.environ["TIMEBACK_API_CLIENT_ID"],
          client_secret=os.environ["TIMEBACK_API_CLIENT_SECRET"],
      ),
  ))

  level = await timeback.api.powerpath.placement.get_current_level({
      "student": "student-123",
      "subject": "Math",
  })
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="QTI" icon="clipboard-question" href="/beta/build-on-timeback/clients/qti">
    Standard assessments
  </Card>

  <Card title="Caliper" icon="chart-line" href="/beta/build-on-timeback/clients/caliper">
    Track learning events
  </Card>

  <Card title="Types" icon="brackets-curly" href="/beta/api-reference/overview">
    PowerPath type definitions
  </Card>
</CardGroup>