Metadata-Version: 2.4
Name: aloc-sdk
Version: 1.0.1
Summary: Official Python SDK for the ALOC Assessment Content Infrastructure Platform (WAEC, JAMB, NECO, Post-UTME — L1 Questions, L2 Curriculum Metadata, L3 AI Explanations, L4 Vector Similarity).
Author-email: ALOC Core Team <aloc.mass@gmail.com>
License: Proprietary
Project-URL: Homepage, https://aloc.com.ng
Project-URL: Documentation, https://aloc.com.ng/docs
Project-URL: API Playground, https://aloc.com.ng/playground
Keywords: aloc,edtech,africa,nigeria,waec,jamb,neco,utme,assessment,curriculum,ai-tutor,langchain
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.7.0
Requires-Dist: typing-extensions>=4.7.1

# aloc-sdk

> Official Python SDK for the **ALOC Assessment Content Infrastructure Platform**.

[![PyPI version](https://img.shields.io/pypi/v/aloc-sdk.svg)](https://pypi.org/project/aloc-sdk/)
[![Python Versions](https://img.shields.io/pypi/pyversions/aloc-sdk.svg)](https://pypi.org/project/aloc-sdk/)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-gold.svg)](https://aloc.com.ng/terms)

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

```bash
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)

```python
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:

```python
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)

```python
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)

```python
# 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:

```python
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](https://aloc.com.ng/docs)
- 🎮 **Interactive API Playground**: [https://aloc.com.ng/playground](https://aloc.com.ng/playground)
- 📧 **Engineering Support**: [aloc.mass@gmail.com](mailto:aloc.mass@gmail.com)
