tflux2011/contextual-engineering-framework

Contextual Engineering Patterns: Architecting Adaptable AI Agents

Reference implementations for the architectural patterns defined in the book "Contextual Engineering: Architecting Adaptable AI Agents for the Real World" by Tobi Lekan Adeosun.

📖 Overview

Standard AI agents are designed for the "Abundance Baseline" of Silicon Valley—perfect internet, unlimited power, and institutional trust. When deployed in the Global South, these agents fail due to the "Agentic Gap" between their reasoning capabilities and environmental realities.

This repository contains the Python reference implementations for the three core adaptation layers introduced in the book:

1. Infrastructure Adapter: Handling offline states and compute scarcity.
2. Cultural Adapter: Managing semantic drift and high-context communication.
3. Safety Adapter: Enforcing constitutional guardrails and Human-in-the-Loop (HITL) workflows.

⚡ Quick Start (Hybrid Router)

How to use the Infrastructure Adapter to route traffic based on connectivity:

from src.infrastructure.inference_router import HybridRouter

# Initialize router with cost/latency preferences
router = HybridRouter(preference="economy", offline_fallback=True)

# The router automatically checks network status (N(t))
model_choice = router.select_model(
    prompt="Summarize this contract",
    complexity_score=0.85
)

print(f"Routing to: {model_choice}")
# Output: "Llama-3-8B-Local" (if offline) or "GPT-4o" (if online)

## 📂 Repository Structure

The code is organized by the "Adapter Layer" it serves, matching the chapters of the manuscript.

```text
├── src
│   ├── infrastructure
│   │   ├── sync_manager.py       # (Chapter 3) The "Sync-Later" Architecture & Offline Queue
│   │   └── inference_router.py   # (Chapter 4) The Hybrid Router (Local vs. Cloud)
│   ├── safety
│   │   ├── sentinel.py           # (Chapter 9) Constitutional Safety Checks & Kill Switches
│   │   └── escalation_ladder.py  # (Chapter 10) Human-in-the-Loop Risk Evaluation Logic
│   └── culture
│       └── context_injector.py   # (Chapter 6) Dynamic Few-Shot Prompting logic
└── README.md


## Citation

If you use this framework in your research, please cite the associated whitepaper:

```bibtex
@article{adeosun2026contextual,
  title={Contextual Engineering: Architectural Patterns for Resilient AI Agents},
  author={Adeosun, Tobi},
  journal={AfricArXiv},
  year={2026},
  url={[https://osf.io/preprints/africarxiv/](https://osf.io/preprints/africarxiv/)[YOUR_HANDLE]}
}