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.find_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.1

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.1
File Size Uploaded Provenance Actions
aloc_sdk-1.0.1.tar.gz 85.0 kB Without provenance Details for aloc_sdk-1.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 293.3 kB

Release files / aloc_sdk-1.0.1.tar.gz

Download URL aloc_sdk-1.0.1.tar.gz
Size 85.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b91f0d42897f16cc0e20b18425e264163e6031c5854590d59969a14dd718efb4
BLAKE2b-256 checksum
How to use checksums
506ba7c75366f079d15cc2494275339ee2250db094ebe3e5f1a9348bf3d21ae3
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.1-py3-none-any.whl

Download URL aloc_sdk-1.0.1-py3-none-any.whl
Size 208.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3428f186658e3a255f354e3476c4a62758b21cf86f11976c070a9b6f2161321f
BLAKE2b-256 checksum
How to use checksums
40e4a36b2f0b87618e0ae7034da01aafe8a71e42ff4828e646aa9b351ebc579e
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.1

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.1 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