Conspectus resource

Specification status

Specification only. The Conspectus HTTP API is not implemented in the application code yet. This hub is the working product narrative: data shapes, intended paths, and idempotency ideas. After the API spec is finalized, implementation and OpenAPI will follow.

Business context

A conspectus is a saved study note created after a learning session. Our methodology uses a 3-step process: Extract (pull cues from content), Transform (write a summary paragraph and bullet points). The API stores this package, along with scheduling info: slot (A–D ladder), next_review_at, and an optional title. Retrieval is planned via API endpoints for due and review; slot movement will live in a dedicated schedule policy module once implemented.

Each conspectus is owned by a User identified by the (system_user_id, system_uuid) pair (in requests or query params)—the same key as the User.

{
                    "topic": "Water cycle",
                    "rows": [
                    {
                    "keywords": "evaporation",
                    "question": "What drives water into vapor?",
                    "hint": "Sun heats surface"
                    },
                    {
                    "keywords": "condensation",
                    "question": "Where do clouds form?",
                    "hint": "Cooling air"
                    },
                    {
                    "keywords": "precipitation",
                    "question": "Rain vs snow depends on?",
                    "hint": "Temperature aloft"
                    }
                    ]
                    }

Data contract (summary)

Full schemas are in OpenAPI; this table is the shorthand for reviews and client onboarding.

Worked example

Scenario: the learner studied the water cycle (evaporation, condensation, precipitation). They already have a user with the same (system_user_id, system_uuid) in our database. Below is a realistic POST /api/v1/conspectuses body: the cue_sheet object is the same as in the paper ↔ JSON example above (three rows); add dense_paragraph and bullets for the Transform layer.

{
                    "system_user_id": "learner-01",
                    "system_uuid": "b2c3d4e5-0002-4000-8000-000000000002",
                    "title": "The water cycle",
                    "cue_sheet": {
                    "topic": "Water cycle",
                    "rows": [
                    {
                    "keywords": "evaporation",
                    "question": "What drives water into vapor?",
                    "hint": "Sun heats surface"
                    },
                    {
                    "keywords": "condensation",
                    "question": "Where do clouds form?",
                    "hint": "Cooling air"
                    },
                    {
                    "keywords": "precipitation",
                    "question": "Rain vs snow depends on?",
                    "hint": "Temperature aloft"
                    }
                    ]
                    },
                    "dense_paragraph": "The sun heats oceans and lakes so water evaporates. Rising vapor cools and condenses into clouds. When droplets or ice grow heavy enough, water returns as rain or snow.",
                    "bullets": [
                    "Evaporation moves water from surface to atmosphere.",
                    "Condensation forms clouds when air cools.",
                    "Precipitation completes the loop back to Earth.",
                    "Energy from the sun drives the cycle.",
                    "The same water moves through states and locations over time."
                    ]
                    }

After 201 Created, the response includes conspectus_uuid, slot (starts at A), next_review_at, and timestamps. Use Idempotency-Key on this POST as for other critical writes.

Method pages (per endpoint)

Navigation matches HTTP method + path (how clients are expected to call the API). Planned operationId names appear in the table; OpenAPI will be generated when routes exist.

Use the sidebar under API → Conspectus, or open a row below. Schedule summary (FR-5) is documented here as a related read surface. The error log (/api/v1/errors, FR-4) has a dedicated Error log hub — separate internal nav, same product scope.

API surface

Planned conspectus routes share prefix /api/v1/conspectuses. Writes that change scheduling are expected to use POST …/actions/review (command-style). When implemented, routes should require X-API-Key and rate limiting per ADR 0005.

Request path and layers

Middleware in app/main.py (metrics, body limit, API key + rate limit, security headers, request ID) → route handler → service → repository → SQLite. Writes that use idempotency also touch idempotency_keys via IdempotencyRepository.

Technical overview

Current codebase: user identity and idempotency infrastructure only (app/api/v1/user.py, shared middleware in app/main.py, SQLite via SQLITE_DB_PATH). Conspectus, schedule, and error-log persistence are not present until the spec is implemented (new routers, services, repositories, ORM models, and Alembic migrations).

Ownership and change management

Who changes this feature: contributors following CONTRIBUTING.md — PRs on main, review, green CI.

• Quality gate: make verify-ci (lint, types, OpenAPI, contract tests, tests, docs-check).
• Contract: HTTP changes → code + make openapi-accept-changes (ADR 0007).
• Internal narrative: update this hub and method pages when behavior or idempotency paths change (ADR 0026).

Page history