Skip to main content

aloc-sdk

Official Python SDK for the ALOC Assessment Content Infrastructure Platform.

PyPI version Python Versions License: Proprietary

Integrate curriculum-aligned examination content spanning WAEC, JAMB/UTME, NECO, and Post-UTME syllabi with Pydantic v2 type safety, Bloom difficulty ratings, step-by-step AI explanations, and vector similarity search. Built for Python backends (FastAPI, Django), AI Socratic tutors, LangChain / LlamaIndex agents, and academic evaluation pipelines.


Installation

pip install aloc-sdk
# or with uv / poetry
uv add aloc-sdk
poetry add aloc-sdk

Quickstart

1. Query Curriculum Questions (L1 Questions & L2 Metadata)

from aloc_sdk import AlocClient

# Reads ALOC_API_KEY from environment automatically if api_key is omitted
client = AlocClient(api_key="aloc_live_...")

response = client.questions.list_questions(
    subject="mathematics",
    exam_type="jamb",
    year=2022,
    limit=10,
)

for q in response.data:
    print(f"[{q.exam_type.upper()} {q.year}] {q.text}")
    print(f"Answer: {q.correct_answer} | Topic: {q.metadata.topic if q.metadata else None}")

Data Provenance Default: All retrieval endpoints return verified historical past questions (content_source="historical") by default. Pass content_source="synthetic" or content_source="all" only when explicitly opting into curriculum-aligned AI-generated items.


2. Request Step-by-Step AI Explanations (L3 Explanation API)

Ideal for grounding AI tutors, RAG pipelines, and LangChain / LlamaIndex tool calls in verified worked solutions and common student misconceptions:

explanation_res = client.explanations.explain_question(
    id="9b1deb4d-3b7d-4bad-9bdd-2b0d7b3d0001"
)

print(explanation_res.data.explanation)
print("Simplified:", explanation_res.data.simplified_explanation)

3. Assemble Syllabus-Balanced Assessment Papers (Assessments API)

from aloc_sdk import AlocClient, GenerateAssessmentRequest

client = AlocClient(api_key="aloc_live_...")

paper = client.assessments.generate_assessment(
    generate_assessment_request=GenerateAssessmentRequest(
        subject="mathematics",
        examType="jamb",
        preset="jamb_standard_40",
        seed="school_mock_2026_batch_a",
        shuffleOptions=True,
    )
)

print(f"Assembled {len(paper.data.questions)} questions | Credits used: {paper.meta.credits_used}")

4. Vector Similarity & Curriculum Trend Analytics (L4 Intelligence API)

# Find conceptually similar questions via pgvector embeddings
similar = client.intelligence.get_similar_questions(
    id="9b1deb4d-3b7d-4bad-9bdd-2b0d7b3d0001",
    limit=5,
)

# Retrieve longitudinal syllabus frequency & difficulty trends
trends = client.intelligence.get_exam_trends(
    subject="mathematics",
    exam_type="jamb",
)

Direct OpenAPI Classes (Alternative Initialization)

If you prefer instantiating individual OpenAPI service classes directly:

from aloc_sdk import ApiClient, Configuration, QuestionsApi

config = Configuration()
config.api_key["apiKeyAuth"] = "aloc_live_..."

with ApiClient(config) as api_client:
    questions_api = QuestionsApi(api_client)
    res = questions_api.list_questions(subject="physics", exam_type="waec", limit=5)

API Layer Coverage

Layer Client Property / Class Description Required Tier
L1 client.questions (QuestionsApi) & client.assessments (AssessmentsApi) Question access (1 cr) & psychometric paper assembly (5 cr) Free+
L2 client.metadata (MetadataApi) & client.subjects (SubjectsApi) Topic taxonomy, difficulty scores & curriculum tree (3 cr) Developer+
L3 client.explanations (ExplanationsApi) Step-by-step worked solutions & common mistakes (10 cr) Developer+
L4 client.intelligence (IntelligenceApi) Vector similarity search & longitudinal exam trends (10 cr) Growth+ / Scale+

Documentation & Support

Metadata

Release files for aloc-sdk 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aloc-sdk 1.0.0
File Size Uploaded Provenance Actions
aloc_sdk-1.0.0.tar.gz 76.9 kB Without provenance Details for aloc_sdk-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aloc-sdk 1.0.0
File Interpreter ABI Platform Actions
aloc_sdk-1.0.0-py3-none-any.whl Python 3 none any Details for aloc_sdk-1.0.0-py3-none-any.whl

Total release size: 263.1 kB

Release files / aloc_sdk-1.0.0.tar.gz

Download URL aloc_sdk-1.0.0.tar.gz
Size 76.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b68fe613d731d403679b24590682a6bbeac11c625561723c4ddcb15b0e1e9370
BLAKE2b-256 checksum
How to use checksums
12759db68112494a8f7bdcd13644070cea7476e5b74ae03aa7910c074344234d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / aloc_sdk-1.0.0-py3-none-any.whl

Download URL aloc_sdk-1.0.0-py3-none-any.whl
Size 186.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ec2372e98869083ddb95c70fb407d2232d570e3b2cb7d89b41f77d2461851e63
BLAKE2b-256 checksum
How to use checksums
fb5d97d28de9cea00df3149196be7615c09606495438f02196ca9101a02222bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Security for aloc-sdk 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page