---

Overview

zainahmed-sdk is an open-source Python client for interacting with Zain Ahmed's verified cloud architecture portfolio, enterprise blueprints, advisory consulting services, and autonomous agent discovery endpoints.

Built on HTTPX, the library provides both synchronous and asynchronous clients with connection pooling, configurable timeouts, RFC 9457 structured error handling, and direct integration with AI agent frameworks (LangChain, LlamaIndex).

Features

• Dual Sync & Async Interfaces: Use ZainClient for automation scripts and Jupyter notebooks, or AsyncZainClient for asyncio agent swarms and FastAPI services.
• Strict PEP 561 Types: Full type annotations across all methods and return values for IDE autocomplete and mypy validation.
• Typed RFC 9457 Problem Details: Exceptions raise ZainAhmedAPIError with machine-readable status_code and problem_details.
• Zero-Mutation Sandbox: Pass sandbox=True to simulate API calls against /api/v1/sandbox without mutating live records.
• Natural Language NLWeb (ask): Query verified multi-cloud case studies and credentials using natural language with cited source links.
• Dual MCP Server Export: Generate Model Context Protocol configurations for both the Operations MCP (/mcp) and Documentation MCP (/mcp/docs) servers.
• Context Manager Support: Clean connection lifecycle management with with and async with blocks.

---

Table of Contents

• Installation
• Quickstart
  • Synchronous (ZainClient)
  • Asynchronous (AsyncZainClient)
• API Reference
• Interactive Sandbox Mode
• Error Handling (RFC 9457)
• Model Context Protocol (MCP) Integration
• Agent Framework Integration
  • LangChain Custom Tool
  • LlamaIndex Tool
• Configuration & Environment
• Contributing
• License

---

Installation

Requirements

• Python >= 3.10
• httpx >= 0.24.0

Install using your preferred package manager:

# pip
pip install zainahmed-sdk

# uv
uv add zainahmed-sdk

# poetry
poetry add zainahmed-sdk

# pdm
pdm add zainahmed-sdk

---

Quickstart

1. Synchronous Usage (ZainClient)

For scripts, CLI utilities, and data science workflows:

from zainahmed import ZainClient

with ZainClient() as client:
    # 1. Fetch verified architect credentials & 5x certifications
    profile = client.get_profile()
    print(f"Connected: {profile['name']} — {profile['title']}")

    # 2. Query architectural case studies by category
    projects = client.list_projects(category="cloud-architecture", limit=5)
    for project in projects.get("projects", []):
        print(f"  - [{project['category']}] {project['title']}")

    # 3. Query technical knowledge base via NLWeb
    response = client.ask("What multi-cloud certifications does Zain hold?")
    print("\nAnswer:", response["answer"])
    for source in response.get("sources", []):
        print(f"  Source: {source['title']} ({source['url']})")

    # 4. Fetch plain markdown pricing and SLA terms
    pricing = client.get_pricing()
    print("\nPricing preview:\n", pricing[:120])

2. Asynchronous Usage (AsyncZainClient)

For asyncio agent loops, FastAPI microservices, or concurrent workloads:

import asyncio
from zainahmed import AsyncZainClient

async def main():
    async with AsyncZainClient() as client:
        # Run concurrent requests
        profile_task = client.get_profile()
        projects_task = client.list_projects(category="kubernetes")

        profile, projects = await asyncio.gather(profile_task, projects_task)

        print(f"Architect: {profile['name']}")
        print(f"Found {len(projects.get('projects', []))} Kubernetes case studies")

asyncio.run(main())

---

API Reference

Both ZainClient and AsyncZainClient expose the same methods:

Method	HTTP Path	Return Type	Description
get_profile(section=None)	GET /api/v1/profile	dict	Retrieve engineer profile, credentials, and social links. section can be "all", "credentials", "bio", or "contacts".
list_projects(category=None, limit=None)	GET /api/v1/projects	dict	List enterprise case studies. Filter by category: "cloud-architecture", "devsecops", "ai-ml", "finops".
list_articles(category=None, limit=None)	GET /api/v1/articles	dict	List published technical deep-dives and SRE blueprints.
list_services(tier=None)	GET /api/v1/services	dict	List advisory consulting tiers, retainer scopes, and engagement models.
get_pricing()	GET /pricing.md	str	Retrieve plain Markdown pricing tiers, SLAs (P1-P4), and payment terms.
submit_contact(...)	POST /api/v1/contact	dict	Submit consultation inquiry with optional RFC 7231 idempotency_key.
ask(query)	POST /ask	dict	Query NLWeb reasoning engine. Returns query, answer, and citation sources.
get_mcp_config()	Local generator	dict	Generate Claude Desktop / Cursor mcpServers configuration dictionary.

---

Interactive Sandbox Mode

Test integrations, webhooks, or agent tool calling safely with zero mutation risk against production records:

from zainahmed import ZainClient

# Route all calls to https://zainahmed.net/api/v1/sandbox
with ZainClient(sandbox=True) as client:
    result = client.submit_contact(
        name="Agent Tester",
        email="tester@example.com",
        subject="Sandbox Verification",
        message="Simulating automated agent submission in test mode.",
    )
    print("Status:", result["status"])  # "success" (simulated ID, no email sent)

---

Error Handling (RFC 9457)

Non-2xx HTTP responses raise ZainAhmedAPIError containing RFC 9457 Problem Details:

from zainahmed import ZainClient, ZainAhmedAPIError

client = ZainClient()

try:
    client.submit_contact(
        name="",  # Validation failure: missing required field
        email="invalid-email",
        message="",
    )
except ZainAhmedAPIError as exc:
    print(f"HTTP Status: {exc.status_code}")
    print(f"Title: {exc.problem_details.get('title')}")
    print(f"Detail: {exc.problem_details.get('detail')}")
    print(f"Code: {exc.problem_details.get('code')}")

---

Model Context Protocol (MCP) Integration

Connect Claude Desktop, Cursor, or Antigravity agents directly to Zain Ahmed's live knowledge base.

Programmatic Config Export

from zainahmed import ZainClient

client = ZainClient()
print(client.get_mcp_config())

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "zainahmed": {
      "url": "https://zainahmed.net/mcp",
      "transport": "streamable-http"
    },
    "zainahmed-docs": {
      "url": "https://zainahmed.net/mcp/docs",
      "transport": "streamable-http"
    }
  }
}

---

Agent Framework Integration

LangChain Custom Tool

from langchain.tools import tool
from zainahmed import ZainClient

client = ZainClient()

@tool
def ask_zain_architecture(question: str) -> str:
    """Queries Zain Ahmed's verified multi-cloud and SRE architecture knowledge base."""
    result = client.ask(question)
    return result.get("answer", "No answer found.")

LlamaIndex Tool

from llama_index.core.tools import FunctionTool
from zainahmed import ZainClient

client = ZainClient()

def search_case_studies(category: str) -> str:
    """Searches Zain Ahmed's case studies by category."""
    projects = client.list_projects(category=category)
    return str(projects)

case_studies_tool = FunctionTool.from_defaults(fn=search_case_studies)

---

Configuration & Environment

from zainahmed import ZainClient

client = ZainClient(
    # Custom base URL (default: https://zainahmed.net)
    base_url="https://zainahmed.net",

    # Optional Bearer token for authenticated enterprise tiers
    api_key="your_api_key_here",

    # Route requests through the verified Sandbox test environment
    sandbox=False,

    # Request timeout in seconds (default: 15.0)
    timeout=15.0,
)

---

Contributing

1. Clone the repository:

   git clone https://github.com/thezaynahmed/portfolio.git
   cd portfolio/packages/sdk-python
   

2. Install editable package with test dependencies:

   pip install -e .
   pip install pytest build twine
   

3. Build distribution packages:

   python3 -m build
   

---

License

MIT © Zain Ahmed (hello@zainahmed.net)

---