aloc-sdk
Official Python SDK for the ALOC Assessment Content Infrastructure Platform.
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
historicalpast questions (content_source="historical") by default. Passcontent_source="synthetic"orcontent_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
- 📖 Developer Documentation: https://aloc.com.ng/docs
- 🎮 Interactive API Playground: https://aloc.com.ng/playground
- 📧 Engineering Support: aloc.mass@gmail.com
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.