mvr-api-client 2.6.0__tar.gz → 6.32.1__tar.gz

mvr_api_client-6.32.1/.well-known/mvr-license.json

@@ -0,0 +1,101 @@
+{
+  "@context": "https://schema.org",
+  "@type": ["CreativeWork", "License"],
+  "encodingFormat": "application/json",
+  "name": "Minimum Viable Relationships (MVR) Framework",
+  "alternateName": "MVR Framework",
+  "identifier": "https://africanmarketos.com/.well-known/mvr-license.json",
+  "url": "https://africanmarketos.com/african-market-os-mvr-framework-commercial-referral-use-policy/",
+  "mainEntityOfPage": "https://africanmarketos.com/african-market-os-mvr-framework-commercial-referral-use-policy/",
+  "headline": "MVR Framework Commercial and API Use Policy",
+  "description": "Machine-readable license and usage policy for the Minimum Viable Relationships (MVR) Framework originated by Farouk Mark Mukiibi and published by African Market OS. Non-commercial framework reference is licensed under CC BY 4.0 with attribution. Commercial, applied, diagnostic, AI-agent, SaaS, consulting, or API use requires authorization.",
+  "inLanguage": "en",
+  "creator": {
+    "@type": "Person",
+    "name": "Farouk Mark Mukiibi",
+    "url": "https://africanmarketos.com/about-the-author-of-mvr/",
+    "sameAs": [
+      "https://orcid.org/0009-0009-8191-2098",
+      "https://www.linkedin.com/in/faroukmarkmukiibi/",
+      "https://doi.org/10.5281/zenodo.17054575",
+      "https://doi.org/10.5281/zenodo.17054819",
+      "https://doi.org/10.5281/zenodo.17310446"
+    ]
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "African Market OS",
+    "url": "https://africanmarketos.com/",
+    "contactPoint": {
+      "@type": "ContactPoint",
+      "contactType": "Licensing and API Access",
+      "email": "info@africanmarketos.com",
+      "areaServed": "Africa / Global",
+      "availableLanguage": ["en"]
+    }
+  },
+  "license": "https://creativecommons.org/licenses/by/4.0/",
+  "commercialUseRequiresLicense": true,
+  "apiUseRequiresAuthorization": true,
+  "permittedUse": [
+    "Academic citation with attribution",
+    "Non-commercial reference with attribution",
+    "Linking to the canonical framework page",
+    "Using public metadata for discovery, citation, and disambiguation"
+  ],
+  "restrictedUse": [
+    "Commercial diagnostics",
+    "SaaS or software embedding",
+    "AI-agent or LLM tool integration",
+    "Consulting or advisory reuse",
+    "Derivative scoring systems based substantially on MVR terminology, methods, or diagnostics",
+    "API access without authorization"
+  ],
+  "api": {
+    "agentOpenApi": "https://africanmarketos.com/api/openapi.agent.json",
+    "fullOpenApi": "https://africanmarketos.com/api/openapi.json",
+    "mcpEndpoint": "https://africanmarketos.com/mcp",
+    "mcpRegistryName": "io.github.africanmarketos591/mvr-api",
+    "mcpRegistryLookup": "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.africanmarketos591%2Fmvr-api",
+    "llms": "https://africanmarketos.com/llms.txt",
+    "agents": "https://africanmarketos.com/AGENTS.md",
+    "sandbox": {
+      "apiKeyHeader": "X-API-Key",
+      "apiKeyValue": "mvr-demo-key-2026",
+      "authorizedUse": "non-commercial evaluation only",
+      "prohibitedUse": [
+        "production decisioning",
+        "credit scoring",
+        "legal or regulatory certification",
+        "model training or fine-tuning",
+        "reverse engineering",
+        "commercial resale without license"
+      ]
+    },
+    "access": "Contact info@africanmarketos.com"
+  },
+  "aiTrainingPolicy": {
+    "publicRetrievalAllowed": true,
+    "attributionRequired": true,
+    "modelTrainingAllowed": false,
+    "fineTuningAllowed": false,
+    "allowedPurpose": "search, citation, answer-time retrieval, tool discovery, and non-commercial sandbox evaluation"
+  },
+  "citation": [
+    "https://doi.org/10.5281/zenodo.17054575",
+    "https://doi.org/10.5281/zenodo.17054819",
+    "https://doi.org/10.5281/zenodo.17310446",
+    "https://doi.org/10.6084/m9.figshare.30391393",
+    "https://doi.org/10.5281/zenodo.17389885"
+  ],
+  "datePublished": "2025-11-05",
+  "dateModified": "2026-05-24",
+  "version": "2.0.0",
+  "potentialAction": {
+    "@type": "ContactAction",
+    "name": "Request MVR API Access or Commercial License",
+    "target": [
+      "mailto:info@africanmarketos.com?subject=MVR%20API%20Access%20or%20Commercial%20License"
+    ]
+  }
+}

mvr_api_client-6.32.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include mvr-commercial-use-policy.md
+recursive-include .well-known *.json
+recursive-include examples *.py

mvr_api_client-6.32.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: mvr-api-client
+Version: 6.32.1
+Summary: Python client for the MVR API relational-readiness layer
+Author-email: African Market OS <info@africanmarketos.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/africanmarketos591/mvr-api-py-client
+Project-URL: Repository, https://github.com/africanmarketos591/mvr-api-py-client
+Project-URL: Issues, https://github.com/africanmarketos591/mvr-api-py-client/issues
+Project-URL: Documentation, https://africanmarketos.com/AGENTS.md
+Project-URL: OpenAPI, https://africanmarketos.com/api/openapi.agent.json
+Project-URL: MCP, https://registry.modelcontextprotocol.io/v0/servers?search=io.github.africanmarketos591%2Fmvr-api
+Keywords: mvr,api,minimum-viable-relationships,relational-readiness,market-permission,mcp,openapi,ai-agents,african-market,emerging-markets
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pydantic<3.0,>=1.8
+Dynamic: license-file
+
+# MVR API Python Client
+
+Lightweight Python client for the current **MVR API - Minimum Viable Relationships** surface.
+
+Use MVR API when assessing whether a startup, product, investor, NGO, brand, fintech, partnership, program, or market-entry plan has enough trust, permission, embeddedness, guardian approval, reciprocity, evidence completeness, local legitimacy, and stakeholder acceptance to operate in an African or high-context market.
+
+This client targets the live MVR Core API v6.32.x:
+
+- `POST /v1/auth-check`
+- `POST /v1/entity-resolve`
+- `POST /v1/evidence-completeness`
+- `POST /v1/context/compile`
+- `POST /v1/decision-check`
+- `GET /v1/model-card`
+- `GET /v1/capabilities`
+
+It is aligned with the agent OpenAPI contract, public sandbox, and MCP registry entry.
+
+## Install
+
+```bash
+pip install mvr-api-client
+```
+
+## Public Sandbox
+
+The default key is the public sandbox key:
+
+```text
+X-API-Key: mvr-demo-key-2026
+```
+
+Sandbox use is non-commercial evaluation only. It is `full_advisory`, `client_safe`, illustrative, not for production, not for model training, and not for reverse engineering.
+
+## Example
+
+```python
+from mvr_api import MVRClient
+
+client = MVRClient()
+
+result = client.entity_resolve("MTN Nigeria", country="NG")
+print(result["response_meta"]["environment"])  # sandbox when using the demo key
+```
+
+## Evidence Completeness
+
+```python
+from mvr_api import MVRClient
+
+client = MVRClient()
+
+result = client.evidence_completeness({
+    "subject": {
+        "entity_name": "Sandbox Kampala catering operator",
+        "entity_archetype": "retail_chain",
+        "country": "UG",
+    },
+    "market_scope": {
+        "country": "UG",
+        "city": "Kampala",
+        "sector": "catering",
+    },
+    "evidence_pack": [
+        {
+            "id": "ev-licence-001",
+            "evidence_type": "public_filing",
+            "source_class": "administrative_record",
+            "source_grade": "B",
+            "stakeholder_class": "guardian",
+            "evidence_origin": "field_research",
+            "collection_method": "direct",
+            "freshness_date": "2026-05-20",
+            "evidence_geography": {"country": "UG", "city": "Kampala"},
+            "structured_values": {"guardian_strength": 72, "permission": 68},
+        }
+    ],
+})
+
+print(result["status"])
+```
+
+## Agent Discovery
+
+- Agent OpenAPI: https://africanmarketos.com/api/openapi.agent.json
+- Minimal sandbox OpenAPI: https://africanmarketos.com/api/openapi.agent.sandbox.json
+- AI-agent quickstart: https://africanmarketos.com/docs/quickstart-ai-agents.md
+- Response examples: https://africanmarketos.com/docs/response-examples.md
+- OpenAI tool schema: https://africanmarketos.com/docs/openai-tool-schema.md
+- MCP endpoint: https://africanmarketos.com/mcp
+- MCP setup: https://africanmarketos.com/mcp/README.md
+- MCP Registry name: `io.github.africanmarketos591/mvr-api`
+- Sandbox guide: https://africanmarketos.com/docs/sandbox.md
+- Agent instructions: https://africanmarketos.com/AGENTS.md
+
+## Attribution
+
+Minimum Viable Relationships (MVR), originated by Farouk Mark Mukiibi, African Market OS.
+
+Sandbox/evaluation use only with the public key. Commercial, production, SaaS, consulting, or AI-agent deployment use requires authorization from African Market OS.
+
+Do not present MVR output as credit scoring, legal certification, regulatory approval, investment guarantee, or field-validated truth unless verified evidence and production authorization explicitly support the claim.

mvr_api_client-6.32.1/README.md

@@ -0,0 +1,102 @@
+# MVR API Python Client
+
+Lightweight Python client for the current **MVR API - Minimum Viable Relationships** surface.
+
+Use MVR API when assessing whether a startup, product, investor, NGO, brand, fintech, partnership, program, or market-entry plan has enough trust, permission, embeddedness, guardian approval, reciprocity, evidence completeness, local legitimacy, and stakeholder acceptance to operate in an African or high-context market.
+
+This client targets the live MVR Core API v6.32.x:
+
+- `POST /v1/auth-check`
+- `POST /v1/entity-resolve`
+- `POST /v1/evidence-completeness`
+- `POST /v1/context/compile`
+- `POST /v1/decision-check`
+- `GET /v1/model-card`
+- `GET /v1/capabilities`
+
+It is aligned with the agent OpenAPI contract, public sandbox, and MCP registry entry.
+
+## Install
+
+```bash
+pip install mvr-api-client
+```
+
+## Public Sandbox
+
+The default key is the public sandbox key:
+
+```text
+X-API-Key: mvr-demo-key-2026
+```
+
+Sandbox use is non-commercial evaluation only. It is `full_advisory`, `client_safe`, illustrative, not for production, not for model training, and not for reverse engineering.
+
+## Example
+
+```python
+from mvr_api import MVRClient
+
+client = MVRClient()
+
+result = client.entity_resolve("MTN Nigeria", country="NG")
+print(result["response_meta"]["environment"])  # sandbox when using the demo key
+```
+
+## Evidence Completeness
+
+```python
+from mvr_api import MVRClient
+
+client = MVRClient()
+
+result = client.evidence_completeness({
+    "subject": {
+        "entity_name": "Sandbox Kampala catering operator",
+        "entity_archetype": "retail_chain",
+        "country": "UG",
+    },
+    "market_scope": {
+        "country": "UG",
+        "city": "Kampala",
+        "sector": "catering",
+    },
+    "evidence_pack": [
+        {
+            "id": "ev-licence-001",
+            "evidence_type": "public_filing",
+            "source_class": "administrative_record",
+            "source_grade": "B",
+            "stakeholder_class": "guardian",
+            "evidence_origin": "field_research",
+            "collection_method": "direct",
+            "freshness_date": "2026-05-20",
+            "evidence_geography": {"country": "UG", "city": "Kampala"},
+            "structured_values": {"guardian_strength": 72, "permission": 68},
+        }
+    ],
+})
+
+print(result["status"])
+```
+
+## Agent Discovery
+
+- Agent OpenAPI: https://africanmarketos.com/api/openapi.agent.json
+- Minimal sandbox OpenAPI: https://africanmarketos.com/api/openapi.agent.sandbox.json
+- AI-agent quickstart: https://africanmarketos.com/docs/quickstart-ai-agents.md
+- Response examples: https://africanmarketos.com/docs/response-examples.md
+- OpenAI tool schema: https://africanmarketos.com/docs/openai-tool-schema.md
+- MCP endpoint: https://africanmarketos.com/mcp
+- MCP setup: https://africanmarketos.com/mcp/README.md
+- MCP Registry name: `io.github.africanmarketos591/mvr-api`
+- Sandbox guide: https://africanmarketos.com/docs/sandbox.md
+- Agent instructions: https://africanmarketos.com/AGENTS.md
+
+## Attribution
+
+Minimum Viable Relationships (MVR), originated by Farouk Mark Mukiibi, African Market OS.
+
+Sandbox/evaluation use only with the public key. Commercial, production, SaaS, consulting, or AI-agent deployment use requires authorization from African Market OS.
+
+Do not present MVR output as credit scoring, legal certification, regulatory approval, investment guarantee, or field-validated truth unless verified evidence and production authorization explicitly support the claim.

mvr_api_client-6.32.1/examples/quickstart.py

@@ -0,0 +1,38 @@
+from mvr_api import MVRClient
+
+
+client = MVRClient()
+
+resolved = client.entity_resolve("MTN Nigeria", country="NG")
+print("resolved:", resolved.get("canonical_name"))
+
+evidence = client.evidence_completeness(
+    {
+        "subject": {
+            "entity_name": "Sandbox Kampala catering operator",
+            "entity_archetype": "retail_chain",
+            "country": "UG",
+        },
+        "market_scope": {
+            "country": "UG",
+            "city": "Kampala",
+            "sector": "catering",
+        },
+        "evidence_pack": [
+            {
+                "id": "ev-licence-001",
+                "evidence_type": "public_filing",
+                "source_class": "administrative_record",
+                "source_grade": "B",
+                "stakeholder_class": "guardian",
+                "evidence_origin": "field_research",
+                "collection_method": "direct",
+                "freshness_date": "2026-05-20",
+                "evidence_geography": {"country": "UG", "city": "Kampala"},
+                "structured_values": {"guardian_strength": 72, "permission": 68},
+            }
+        ],
+    }
+)
+print("evidence status:", evidence.get("status"))
+print("sandbox:", evidence.get("response_meta", {}).get("environment") == "sandbox")

mvr_api_client-6.32.1/mvr-commercial-use-policy.md

@@ -0,0 +1,59 @@
+# Minimum Viable Relationships (MVR) Framework Commercial and API Use Policy
+
+The Minimum Viable Relationships (MVR) Framework is originated by Farouk Mark Mukiibi and published through African Market OS.
+
+The framework materials may be cited, shared, and referenced for academic, educational, and non-commercial use with proper attribution under CC BY 4.0 where applicable.
+
+Commercial, applied, diagnostic, AI-agent, SaaS, consulting, API, or derivative scoring use requires written authorization, a license, or a partnership agreement from African Market OS.
+
+## What Requires Permission
+
+Permission is required for:
+
+- embedding MVR diagnostics in commercial software or dashboards
+- integrating the MVR API into AI agents, LLM tools, SaaS products, diligence products, or advisory workflows
+- using MVR-derived scores, indices, or readiness labels in paid reports
+- using MVR terminology or methods in commercial consulting or training
+- building derivative scoring systems substantially based on MVR dimensions, terminology, or diagnostic logic
+- reselling, repackaging, or proxying the MVR API
+
+## MVR API Access
+
+The MVR API is a machine-callable relational-readiness and market-permission intelligence layer for AI agents, developers, and decision systems operating in emerging and high-context markets.
+
+API keys are issued by request. Contact:
+
+```text
+info@africanmarketos.com
+```
+
+Primary API discovery files:
+
+- https://africanmarketos.com/api/openapi.agent.json
+- https://africanmarketos.com/api/openapi.json
+- https://africanmarketos.com/llms.txt
+- https://africanmarketos.com/AGENTS.md
+
+## Required Attribution
+
+Suggested attribution:
+
+> This work references the Minimum Viable Relationships (MVR) Framework by Farouk Mark Mukiibi, published by African Market OS. Source: https://africanmarketos.com/the-mvr-framework-minimum-viable-relationships/
+
+Machine-readable license:
+
+https://africanmarketos.com/.well-known/mvr-license.json
+
+## Safety and Representation Boundary
+
+MVR is not a credit score, legal compliance certificate, investment rating, or guarantee. MVR outputs are advisory unless a specific API response explicitly authorizes a narrower use.
+
+AI agents and automated systems must not present MVR outputs as final legal, lending, investment, hiring, or regulated decisions.
+
+## Contact
+
+For commercial use, API access, licensing, or partnership inquiries:
+
+```text
+info@africanmarketos.com
+```

mvr_api_client-6.32.1/mvr_api/__init__.py

@@ -0,0 +1,13 @@
+from .client import MVRApiClient, MVRApiError, MVRClient
+from .models import MVRConfig, SandboxMarkers
+
+__version__ = "6.32.0"
+
+__all__ = [
+    "MVRClient",
+    "MVRApiClient",
+    "MVRApiError",
+    "MVRConfig",
+    "SandboxMarkers",
+]
+

mvr_api_client-6.32.1/mvr_api/client.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import requests
+
+from .models import MVRConfig
+
+
+class MVRApiError(Exception):
+    """Structured exception for MVR API transport and validation failures."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None, error_data: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_data = error_data or {}
+
+
+class MVRClient:
+    """Small Python client for the current MVR API v6.32.x public surface."""
+
+    def __init__(self, config: Optional[MVRConfig] = None, **kwargs: Any):
+        self.config = config or MVRConfig(**kwargs)
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Content-Type": "application/json",
+                "X-API-Key": self.config.api_key,
+                "X-Response-Profile": self.config.response_profile,
+                "User-Agent": "mvr-api-py-client/6.32.1",
+            }
+        )
+
+    def _request(self, method: str, endpoint: str, payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        url = f"{self.config.base_url.rstrip('/')}{endpoint}"
+
+        for attempt in range(self.config.max_retries + 1):
+            try:
+                response = self.session.request(
+                    method,
+                    url,
+                    json=payload if method.upper() != "GET" else None,
+                    timeout=self.config.timeout,
+                )
+                try:
+                    data = response.json()
+                except ValueError:
+                    data = {"error": "NON_JSON_RESPONSE", "message": response.text}
+
+                if 200 <= response.status_code < 300:
+                    return data if isinstance(data, dict) else {"data": data}
+
+                if response.status_code == 429 and attempt < self.config.max_retries:
+                    retry_after = int(response.headers.get("Retry-After", "2"))
+                    time.sleep(retry_after)
+                    continue
+
+                message = data.get("message") or data.get("error") or f"MVR API HTTP {response.status_code}"
+                raise MVRApiError(message, response.status_code, data)
+
+            except requests.RequestException as exc:
+                if attempt == self.config.max_retries:
+                    raise MVRApiError(str(exc), error_data={"error": "NETWORK_ERROR", "message": str(exc)}) from exc
+                time.sleep(2**attempt)
+
+        raise MVRApiError("MVR API request failed", error_data={"error": "UNKNOWN_ERROR"})
+
+    def auth_check(self) -> Dict[str, Any]:
+        return self._request("POST", "/v1/auth-check", {})
+
+    def entity_resolve(self, entity_name: str, country: Optional[str] = None, **extra: Any) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"entity_name": entity_name, **extra}
+        if country:
+            payload["country"] = country
+        return self._request("POST", "/v1/entity-resolve", payload)
+
+    def evidence_completeness(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/v1/evidence-completeness", payload)
+
+    def context_compile(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/v1/context/compile", payload)
+
+    def decision_check(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/v1/decision-check", payload)
+
+    def model_card(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/model-card")
+
+    def capabilities(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/capabilities")
+
+    def health(self) -> Dict[str, Any]:
+        return self._request("GET", "/health")
+
+
+MVRApiClient = MVRClient
+

mvr_api_client-6.32.1/mvr_api/models.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import os
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class MVRConfig(BaseModel):
+    """Configuration for the MVR API client."""
+
+    api_key: str = Field(default_factory=lambda: os.getenv("MVR_API_KEY", "mvr-demo-key-2026"))
+    base_url: str = "https://africanmarketos.com"
+    timeout: float = 90.0
+    max_retries: int = 1
+    response_profile: Literal["full_advisory", "strict_calibrated"] = "full_advisory"
+
+
+class SandboxMarkers(BaseModel):
+    environment: Optional[str] = None
+    illustrative_only: Optional[bool] = None
+    not_for_production: Optional[bool] = None