mvr-api-client 6.32.0__tar.gz → 6.32.3__tar.gz

{mvr_api_client-6.32.0/mvr_api_client.egg-info → mvr_api_client-6.32.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mvr-api-client
-Version: 6.32.0
+Version: 6.32.3
 Summary: Python client for the MVR API relational-readiness layer
 Author-email: African Market OS <info@africanmarketos.com>
 License-Expression: MIT
@@ -16,18 +16,32 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.25.0
 Requires-Dist: pydantic<3.0,>=1.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: mypy<1.18,>=1.11.0; extra == "dev"
 Dynamic: license-file
 
 # MVR API Python Client
 
+[![PyPI](https://img.shields.io/pypi/v/mvr-api-client)](https://pypi.org/project/mvr-api-client/)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0f6b45)](https://registry.modelcontextprotocol.io/?search=mvr)
+[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-6ba539)](https://africanmarketos.com/api/openapi.json)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/africanmarketos591/mvr-api-py-client/blob/main/LICENSE)
+
 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/first-call`
 - `POST /v1/entity-resolve`
 - `POST /v1/evidence-completeness`
+- `POST /v1/context/compile`
 - `POST /v1/decision-check`
+- `POST /v1/recommended-inputs`
+- `POST /v1/remediation-path`
 - `GET /v1/model-card`
 - `GET /v1/capabilities`
 
@@ -56,10 +70,19 @@ from mvr_api import MVRClient
 
 client = MVRClient()
 
+activation = client.first_call({
+    "entity_name": "Example Kampala supplier-finance venture",
+    "country": "UG",
+    "decision": "Assess whether to proceed beyond bounded discovery",
+})
+print(activation["not_a_verdict"])  # True
+
 result = client.entity_resolve("MTN Nigeria", country="NG")
 print(result["response_meta"]["environment"])  # sandbox when using the demo key
 ```
 
+`first_call` intentionally accepts free-form discovery labels such as `generic_startup`; canonical `EntityArchetype` values become mandatory on `recommended_inputs` and evidence-scoring routes. Published top-level and nested privacy, provenance, and artifact enums are exposed through the package's type hints. Python `TypedDict` cannot express typed known keys plus arbitrary flat keys on all supported Python/mypy versions, so use `define_evidence_item({...})` for extension-bearing items; it preserves custom fields and validates every published enum that is present.
+
 ## Evidence Completeness
 
 ```python
@@ -100,7 +123,13 @@ print(result["status"])
 ## Agent Discovery
 
 - Agent OpenAPI: https://africanmarketos.com/api/openapi.agent.json
-- MCP endpoint: https://africanmarketos.com/mcp
+- 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
+- Canonical public MCP preflight: https://africanmarketos.com/mcp/preflight
+- Compatibility 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
@@ -109,4 +138,6 @@ print(result["status"])
 
 Minimum Viable Relationships (MVR), originated by Farouk Mark Mukiibi, African Market OS.
 
-Commercial, production, SaaS, consulting, or AI-agent deployment use requires authorization from 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.3/README.md

@@ -0,0 +1,120 @@
+# MVR API Python Client
+
+[![PyPI](https://img.shields.io/pypi/v/mvr-api-client)](https://pypi.org/project/mvr-api-client/)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0f6b45)](https://registry.modelcontextprotocol.io/?search=mvr)
+[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-6ba539)](https://africanmarketos.com/api/openapi.json)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/africanmarketos591/mvr-api-py-client/blob/main/LICENSE)
+
+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/first-call`
+- `POST /v1/entity-resolve`
+- `POST /v1/evidence-completeness`
+- `POST /v1/context/compile`
+- `POST /v1/decision-check`
+- `POST /v1/recommended-inputs`
+- `POST /v1/remediation-path`
+- `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()
+
+activation = client.first_call({
+    "entity_name": "Example Kampala supplier-finance venture",
+    "country": "UG",
+    "decision": "Assess whether to proceed beyond bounded discovery",
+})
+print(activation["not_a_verdict"])  # True
+
+result = client.entity_resolve("MTN Nigeria", country="NG")
+print(result["response_meta"]["environment"])  # sandbox when using the demo key
+```
+
+`first_call` intentionally accepts free-form discovery labels such as `generic_startup`; canonical `EntityArchetype` values become mandatory on `recommended_inputs` and evidence-scoring routes. Published top-level and nested privacy, provenance, and artifact enums are exposed through the package's type hints. Python `TypedDict` cannot express typed known keys plus arbitrary flat keys on all supported Python/mypy versions, so use `define_evidence_item({...})` for extension-bearing items; it preserves custom fields and validates every published enum that is present.
+
+## 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
+- Canonical public MCP preflight: https://africanmarketos.com/mcp/preflight
+- Compatibility 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.3/mvr_api/__init__.py

@@ -0,0 +1,76 @@
+from .client import MVRApiClient, MVRApiError, MVRClient
+from .models import (
+    CompiledPack,
+    CollectionMethod,
+    ContextCompileRequest,
+    DecisionCheckRequest,
+    EntityArchetype,
+    EvidenceCompletenessRequest,
+    EvidenceItem,
+    EvidenceOrigin,
+    EvidenceType,
+    GuardianTier,
+    FirstCallRequest,
+    MVRConfig,
+    MVRMarketScope,
+    MVRSubject,
+    MVRVerdict,
+    PublicMetricScope,
+    PrivacyConsentBasis,
+    PrivacyEnvelope,
+    PrivacyRedactionStatus,
+    PrivacyRetentionClass,
+    ProvenanceExtractionMethod,
+    ProvenanceLedger,
+    RecommendedInputsRequest,
+    RemediationPathRequest,
+    ReviewStatus,
+    SandboxMarkers,
+    SourceClass,
+    SourceConfidence,
+    SourceGrade,
+    StakeholderClass,
+    SourceArtifact,
+    define_evidence_item,
+)
+
+__version__ = "6.32.3"
+
+__all__ = [
+    "MVRClient",
+    "MVRApiClient",
+    "MVRApiError",
+    "MVRConfig",
+    "CompiledPack",
+    "CollectionMethod",
+    "ContextCompileRequest",
+    "DecisionCheckRequest",
+    "EntityArchetype",
+    "EvidenceCompletenessRequest",
+    "EvidenceItem",
+    "EvidenceOrigin",
+    "EvidenceType",
+    "GuardianTier",
+    "FirstCallRequest",
+    "MVRMarketScope",
+    "MVRSubject",
+    "MVRVerdict",
+    "PublicMetricScope",
+    "PrivacyConsentBasis",
+    "PrivacyEnvelope",
+    "PrivacyRedactionStatus",
+    "PrivacyRetentionClass",
+    "ProvenanceExtractionMethod",
+    "ProvenanceLedger",
+    "RecommendedInputsRequest",
+    "RemediationPathRequest",
+    "ReviewStatus",
+    "SandboxMarkers",
+    "SourceClass",
+    "SourceConfidence",
+    "SourceGrade",
+    "StakeholderClass",
+    "SourceArtifact",
+    "define_evidence_item",
+]
+

{mvr_api_client-6.32.0 → mvr_api_client-6.32.3}/mvr_api/client.py

@@ -1,11 +1,19 @@
 from __future__ import annotations
 
 import time
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Mapping, Optional
 
 import requests
 
-from .models import MVRConfig
+from .models import (
+    ContextCompileRequest,
+    DecisionCheckRequest,
+    EvidenceCompletenessRequest,
+    FirstCallRequest,
+    MVRConfig,
+    RecommendedInputsRequest,
+    RemediationPathRequest,
+)
 
 
 class MVRApiError(Exception):
@@ -28,11 +36,11 @@ class MVRClient:
                 "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.0",
+                "User-Agent": "mvr-api-py-client/6.32.3",
             }
         )
 
-    def _request(self, method: str, endpoint: str, payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    def _request(self, method: str, endpoint: str, payload: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
         url = f"{self.config.base_url.rstrip('/')}{endpoint}"
 
         for attempt in range(self.config.max_retries + 1):
@@ -69,18 +77,31 @@ class MVRClient:
     def auth_check(self) -> Dict[str, Any]:
         return self._request("POST", "/v1/auth-check", {})
 
+    def first_call(self, payload: Optional[FirstCallRequest] = None) -> Dict[str, Any]:
+        """Start the bounded MVR workflow; this response is never a verdict."""
+        return self._request("POST", "/v1/first-call", payload or {})
+
     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]:
+    def evidence_completeness(self, payload: EvidenceCompletenessRequest) -> Dict[str, Any]:
         return self._request("POST", "/v1/evidence-completeness", payload)
 
-    def decision_check(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+    def context_compile(self, payload: ContextCompileRequest) -> Dict[str, Any]:
+        return self._request("POST", "/v1/context/compile", payload)
+
+    def decision_check(self, payload: DecisionCheckRequest) -> Dict[str, Any]:
         return self._request("POST", "/v1/decision-check", payload)
 
+    def recommended_inputs(self, payload: Optional[RecommendedInputsRequest] = None) -> Dict[str, Any]:
+        return self._request("POST", "/v1/recommended-inputs", payload or {})
+
+    def remediation_path(self, payload: Optional[RemediationPathRequest] = None) -> Dict[str, Any]:
+        return self._request("POST", "/v1/remediation-path", payload or {})
+
     def model_card(self) -> Dict[str, Any]:
         return self._request("GET", "/v1/model-card")
 

mvr_api_client-6.32.3/mvr_api/models.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Literal, Mapping, Optional, TypedDict, Union, cast, get_args
+
+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
+
+
+EntityArchetype = Literal[
+    "telecom_operator", "mobile_money_operator", "fintech_platform", "financial_services_bank",
+    "fintech_lending", "logistics_platform", "energy_utility", "extractives_operator",
+    "real_estate_construction", "education_provider", "passenger_mobility", "b2b_saas_platform",
+    "healthtech_platform", "insurance_platform", "fmcg_brand", "retail_chain", "ecommerce_platform",
+    "manufacturer", "distributor_network", "ngo", "development_program", "public_institution",
+    "survey_dataset", "solo_entrepreneur", "family_business", "cooperative_sacco",
+    "cross_border_trader", "university_spinout", "diaspora_venture", "creator_economy_individual",
+    "agritech_aggregator", "impact_enterprise", "religious_institution", "chama_savings_group",
+]
+
+MVRVerdict = Literal["permission_not_yet_earned", "pilot_only", "pilot_ready", "ready_to_scale"]
+StringOrStringList = Union[str, List[str]]
+
+EvidenceType = Literal[
+    "public_filing", "survey", "interview", "observation", "telemetry", "admin_data",
+    "evaluation", "retail_audit", "social_listening", "partner_network", "program_monitoring",
+]
+EvidenceOrigin = Literal["public_osint", "field_research", "mixed", "corporate_telemetry", "platform_telemetry"]
+SourceGrade = Literal["A", "B", "C", "D"]
+SourceClass = Literal[
+    "entity_reported", "independently_audited", "regulator_published", "administrative_record",
+    "probability_sample_survey", "nonprobability_survey", "structured_field_research",
+    "third_party_evaluation", "retail_audit", "telemetry_internal", "media_reported", "model_inferred",
+]
+StakeholderClass = Literal[
+    "agent", "anchor_customer", "bank_lender", "beneficiary", "board", "board_member", "chama_member",
+    "channel_gatekeeper", "chief", "civil_society_org", "clinic", "community_guardian", "community_leader",
+    "competitor", "competitors", "consumer", "cooperative_member", "court", "courts", "creditor", "creditors",
+    "customary_land_authority", "customer", "customs", "customs_authority", "distributor", "donor",
+    "donor_guardian", "enumerator", "farmer", "field_agent", "field_supervisor", "gatekeeper", "guarantor",
+    "guardian", "guardian_node", "implementing_partner", "incumbent", "incumbent_competitor", "incumbents",
+    "influencer", "informal_logistics", "informal_logistics_partner", "institutional_guardian",
+    "internal_operations", "internal_operator", "investor", "investor_board", "investors", "journalist",
+    "journalists", "judiciary", "judiciary_court", "labor_union", "labour_union", "land_custodian",
+    "land_owner", "landlord", "landowner", "lender", "lender_creditor", "lenders", "market_queen", "media",
+    "media_press", "member", "micro_logistics", "mobile_money_agent", "organized_labour", "platform_partner",
+    "political_guardian", "press", "public_official", "regulator", "regulatory_body", "religious_leader",
+    "research_respondent_group", "retail_partner", "retailer", "retailer_partner", "revenue_authority",
+    "sacco_member", "school", "service_provider", "shareholder", "shareholders", "supplier", "suppliers",
+    "tax_authority", "tax_revenue_authority", "teacher", "traditional_chief", "union", "upstream_supplier",
+    "upstream_vendor", "vc", "vendor", "vendors", "venture_capital", "worker_association", "works_council",
+]
+CollectionMethod = Literal[
+    "structured_interview_protocol", "expert_ethnographic_observation", "field_observation",
+    "survey_platform_verified", "survey_paper_based", "key_informant_interview", "team_consensus_estimate",
+    "founder_intuition", "inferred_from_secondary", "direct", "inferred", "secondary_source",
+    "corporate_telemetry", "database_aggregation", "expert_opinion", "intercept_interview",
+]
+GuardianTier = Literal["macro_regulator", "meso_community", "micro_street"]
+SourceConfidence = Literal["high", "medium", "low"]
+ReviewStatus = Literal["pending", "approved", "accepted", "verified", "reviewed", "rejected"]
+PublicMetricScope = Literal["entity_scale", "country_scale", "regional_scale", "city_scale", "site_scale"]
+ProvenanceExtractionMethod = Literal["human", "deterministic_parser", "llm_inferred", "automated_query"]
+PrivacyConsentBasis = Literal[
+    "consent", "contract", "legitimate_interest", "public_interest", "legal_obligation", "not_applicable",
+]
+PrivacyRetentionClass = Literal["session_only", "30d", "90d", "1y", "7y", "contractual"]
+PrivacyRedactionStatus = Literal["raw", "minimized", "redacted", "aggregated"]
+
+
+class MVRSubject(TypedDict, total=False):
+    entity_name: str
+    name: str
+    country: str
+    entity_archetype: EntityArchetype
+    category: str
+
+
+class MVRMarketScope(TypedDict, total=False):
+    country: str
+    sector: str
+    city: str
+    town_or_zone: str
+    region: str
+    analysis_date: str
+    evaluation_date: str
+
+
+class PrivacyEnvelope(TypedDict, total=False):
+    contains_pii: bool
+    contains_sensitive_personal_data: bool
+    consent_basis: PrivacyConsentBasis
+    retention_class: PrivacyRetentionClass
+    redaction_status: PrivacyRedactionStatus
+    safe_for_modeling: bool
+
+
+class ProvenanceLedger(TypedDict, total=False):
+    source_family: str
+    source_doc_id: str
+    source_locator: str
+    extraction_method: ProvenanceExtractionMethod
+    extraction_confidence: float
+    compiler_stage: str
+    data_integrity: Dict[str, Any]
+
+
+class SourceArtifact(TypedDict, total=False):
+    artifact_id: str
+    media_type: str
+    storage_uri: str
+    sha256: str
+    extraction_method: ProvenanceExtractionMethod
+    extractor_version: str
+    extracted_at: str
+    human_reviewed: bool
+
+
+class EvidenceItem(TypedDict, total=False):
+    id: str
+    evidence_id: str
+    evidence_type: EvidenceType
+    evidence_origin: EvidenceOrigin
+    source_grade: SourceGrade
+    source_class: SourceClass
+    entity_archetype: EntityArchetype
+    stakeholder_class: StakeholderClass
+    guardian_tier: GuardianTier
+    collection_method: CollectionMethod
+    source_confidence: SourceConfidence
+    freshness_date: str
+    evidence_geography: MVRMarketScope
+    geography: MVRMarketScope
+    temporal: Dict[str, Any]
+    public_metric_scope: PublicMetricScope
+    public_metrics: Dict[str, Any]
+    structured_values: Dict[str, float]
+    structured_values_scale: str
+    behavioral_values: Dict[str, Any]
+    structured_values_provenance: Dict[str, Any]
+    human_reviewed: bool
+    review_status: ReviewStatus
+    reviewed_by: str
+    reviewed_at: str
+    human_review: Dict[str, Any]
+    organ_attestation: Dict[str, Any]
+    _verifier_attestation: Dict[str, Any]
+    privacy_envelope: PrivacyEnvelope
+    uncertainty_envelope: Dict[str, Any]
+    provenance_ledger: ProvenanceLedger
+    survey_payload: Dict[str, Any]
+    program_payload: Dict[str, Any]
+    admin_data_payload: Dict[str, Any]
+    retail_audit_payload: Dict[str, Any]
+    source_artifacts: List[SourceArtifact]
+
+
+_EVIDENCE_ENUMS = {
+    "evidence_type": set(get_args(EvidenceType)),
+    "evidence_origin": set(get_args(EvidenceOrigin)),
+    "source_grade": set(get_args(SourceGrade)),
+    "source_class": set(get_args(SourceClass)),
+    "entity_archetype": set(get_args(EntityArchetype)),
+    "stakeholder_class": set(get_args(StakeholderClass)),
+    "guardian_tier": set(get_args(GuardianTier)),
+    "collection_method": set(get_args(CollectionMethod)),
+    "source_confidence": set(get_args(SourceConfidence)),
+    "review_status": set(get_args(ReviewStatus)),
+    "public_metric_scope": set(get_args(PublicMetricScope)),
+}
+_PROVENANCE_METHODS = set(get_args(ProvenanceExtractionMethod))
+_PRIVACY_ENUMS = {
+    "consent_basis": set(get_args(PrivacyConsentBasis)),
+    "retention_class": set(get_args(PrivacyRetentionClass)),
+    "redaction_status": set(get_args(PrivacyRedactionStatus)),
+}
+
+
+def define_evidence_item(item: Mapping[str, Any]) -> EvidenceItem:
+    """Preserve extension fields while validating every published enum present in the item."""
+
+    result = dict(item)
+    for field, allowed in _EVIDENCE_ENUMS.items():
+        if field in result and result[field] not in allowed:
+            raise ValueError(f"{field} must be one of: {', '.join(sorted(allowed))}")
+
+    privacy = result.get("privacy_envelope")
+    if privacy is not None:
+        if not isinstance(privacy, Mapping):
+            raise ValueError("privacy_envelope must be a mapping")
+        for field, allowed in _PRIVACY_ENUMS.items():
+            if field in privacy and privacy[field] not in allowed:
+                raise ValueError(f"privacy_envelope.{field} must be one of: {', '.join(sorted(allowed))}")
+
+    provenance = result.get("provenance_ledger")
+    if provenance is not None:
+        if not isinstance(provenance, Mapping):
+            raise ValueError("provenance_ledger must be a mapping")
+        if "extraction_method" in provenance and provenance["extraction_method"] not in _PROVENANCE_METHODS:
+            raise ValueError("provenance_ledger.extraction_method must use the published extraction-method enum")
+
+    artifacts = result.get("source_artifacts")
+    if artifacts is not None:
+        if not isinstance(artifacts, list):
+            raise ValueError("source_artifacts must be a list")
+        for index, artifact in enumerate(artifacts):
+            if not isinstance(artifact, Mapping):
+                raise ValueError(f"source_artifacts[{index}] must be a mapping")
+            if "extraction_method" in artifact and artifact["extraction_method"] not in _PROVENANCE_METHODS:
+                raise ValueError(f"source_artifacts[{index}].extraction_method must use the published extraction-method enum")
+
+    return cast(EvidenceItem, result)
+
+
+class CompiledPack(TypedDict, total=False):
+    public_reality_pack: List[EvidenceItem]
+    telemetry_proxy_pack: List[EvidenceItem]
+    localized_observed_pack: List[EvidenceItem]
+    survey_pack: List[EvidenceItem]
+    retail_audit_pack: List[EvidenceItem]
+    ngo_program_pack: List[EvidenceItem]
+    administrative_data_pack: List[EvidenceItem]
+    evaluation_pack: List[EvidenceItem]
+    partner_network_pack: List[EvidenceItem]
+    social_listening_pack: List[EvidenceItem]
+
+
+class FirstCallRequest(TypedDict, total=False):
+    subject: Dict[str, Any]
+    market_scope: MVRMarketScope
+    entity: str
+    entity_name: str
+    company_name: str
+    company: str
+    name: str
+    query: str
+    country: str
+    sector: str
+    industry: str
+    entity_archetype: str
+    use_case: str
+    question: str
+    intent: str
+    decision: str
+    intended_action: str
+    decision_context: str
+    stage: str
+    target_users: str
+    evidence_available: StringOrStringList
+    evidence_types: StringOrStringList
+    sources: StringOrStringList
+    known_partners: StringOrStringList
+    partners: StringOrStringList
+    channels: StringOrStringList
+    evidence_pack: List[Dict[str, Any]]
+    evidence_items: List[Dict[str, Any]]
+    city: str
+    town_or_zone: str
+
+
+class RecommendedInputsRequest(TypedDict, total=False):
+    endpoint: str
+    route: str
+    path: str
+    entity_archetype: EntityArchetype
+    category: str
+    subject: MVRSubject
+    country: str
+    goal: str
+    evidence_maturity: str
+
+
+class RemediationPathRequest(TypedDict, total=False):
+    decision_result: Dict[str, Any]
+    subject: MVRSubject
+    market_scope: MVRMarketScope
+    evidence_pack: List[EvidenceItem]
+    compiled_pack: CompiledPack
+    target_verdict: MVRVerdict
+    audience: str
+    gap_plan: Dict[str, Any]
+    evidence_run: Dict[str, Any]
+    evidence_recruitment_plan: Dict[str, Any]
+    mvr_result: Dict[str, Any]
+    decision_room: Dict[str, Any]
+    red_team: Dict[str, Any]
+    release_check: Dict[str, Any]
+    project_id: str
+
+
+class EvidenceCompletenessRequest(TypedDict, total=False):
+    subject: MVRSubject
+    market_scope: MVRMarketScope
+    evidence_pack: List[EvidenceItem]
+    compiled_pack: CompiledPack
+    stakeholder_scope: List[str]
+    target_verdict: MVRVerdict
+
+
+class ContextCompileRequest(TypedDict, total=False):
+    subject: MVRSubject
+    market_scope: MVRMarketScope
+    evidence_pack: List[EvidenceItem]
+    compiled_pack: CompiledPack
+    analysis_date: str
+    requested_use: str
+
+
+class DecisionCheckRequest(TypedDict, total=False):
+    mode: Literal["exploratory", "evidence_backed", "compiled_evidence"]
+    subject: MVRSubject
+    market_scope: MVRMarketScope
+    evidence_pack: List[EvidenceItem]
+    compiled_pack: CompiledPack

{mvr_api_client-6.32.0 → mvr_api_client-6.32.3/mvr_api_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mvr-api-client
-Version: 6.32.0
+Version: 6.32.3
 Summary: Python client for the MVR API relational-readiness layer
 Author-email: African Market OS <info@africanmarketos.com>
 License-Expression: MIT
@@ -16,18 +16,32 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.25.0
 Requires-Dist: pydantic<3.0,>=1.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: mypy<1.18,>=1.11.0; extra == "dev"
 Dynamic: license-file
 
 # MVR API Python Client
 
+[![PyPI](https://img.shields.io/pypi/v/mvr-api-client)](https://pypi.org/project/mvr-api-client/)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0f6b45)](https://registry.modelcontextprotocol.io/?search=mvr)
+[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-6ba539)](https://africanmarketos.com/api/openapi.json)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/africanmarketos591/mvr-api-py-client/blob/main/LICENSE)
+
 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/first-call`
 - `POST /v1/entity-resolve`
 - `POST /v1/evidence-completeness`
+- `POST /v1/context/compile`
 - `POST /v1/decision-check`
+- `POST /v1/recommended-inputs`
+- `POST /v1/remediation-path`
 - `GET /v1/model-card`
 - `GET /v1/capabilities`
 
@@ -56,10 +70,19 @@ from mvr_api import MVRClient
 
 client = MVRClient()
 
+activation = client.first_call({
+    "entity_name": "Example Kampala supplier-finance venture",
+    "country": "UG",
+    "decision": "Assess whether to proceed beyond bounded discovery",
+})
+print(activation["not_a_verdict"])  # True
+
 result = client.entity_resolve("MTN Nigeria", country="NG")
 print(result["response_meta"]["environment"])  # sandbox when using the demo key
 ```
 
+`first_call` intentionally accepts free-form discovery labels such as `generic_startup`; canonical `EntityArchetype` values become mandatory on `recommended_inputs` and evidence-scoring routes. Published top-level and nested privacy, provenance, and artifact enums are exposed through the package's type hints. Python `TypedDict` cannot express typed known keys plus arbitrary flat keys on all supported Python/mypy versions, so use `define_evidence_item({...})` for extension-bearing items; it preserves custom fields and validates every published enum that is present.
+
 ## Evidence Completeness
 
 ```python
@@ -100,7 +123,13 @@ print(result["status"])
 ## Agent Discovery
 
 - Agent OpenAPI: https://africanmarketos.com/api/openapi.agent.json
-- MCP endpoint: https://africanmarketos.com/mcp
+- 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
+- Canonical public MCP preflight: https://africanmarketos.com/mcp/preflight
+- Compatibility 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
@@ -109,4 +138,6 @@ print(result["status"])
 
 Minimum Viable Relationships (MVR), originated by Farouk Mark Mukiibi, African Market OS.
 
-Commercial, production, SaaS, consulting, or AI-agent deployment use requires authorization from 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.0 → mvr_api_client-6.32.3}/mvr_api_client.egg-info/SOURCES.txt

@@ -13,4 +13,5 @@ mvr_api_client.egg-info/PKG-INFO
 mvr_api_client.egg-info/SOURCES.txt
 mvr_api_client.egg-info/dependency_links.txt
 mvr_api_client.egg-info/requires.txt
-mvr_api_client.egg-info/top_level.txt
+mvr_api_client.egg-info/top_level.txt
+tests/test_client.py

mvr_api_client-6.32.3/mvr_api_client.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.25.0
+pydantic<3.0,>=1.8
+
+[dev]
+build>=1.2.0
+mypy<1.18,>=1.11.0

{mvr_api_client-6.32.0 → mvr_api_client-6.32.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mvr-api-client"
-version = "6.32.0"
+version = "6.32.3"
 description = "Python client for the MVR API relational-readiness layer"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -32,6 +32,12 @@ dependencies = [
   "pydantic>=1.8,<3.0"
 ]
 
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.0",
+  "mypy>=1.11.0,<1.18"
+]
+
 [project.urls]
 Homepage = "https://github.com/africanmarketos591/mvr-api-py-client"
 Repository = "https://github.com/africanmarketos591/mvr-api-py-client"
@@ -44,3 +50,7 @@ MCP = "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.afri
 where = ["."]
 include = ["mvr_api*"]
 
+[tool.mypy]
+python_version = "3.9"
+warn_unused_ignores = true
+

mvr_api_client-6.32.3/tests/test_client.py

@@ -0,0 +1,75 @@
+import unittest
+from unittest.mock import Mock
+
+from mvr_api import MVRApiError, MVRClient, MVRConfig, define_evidence_item
+
+
+class ClientContractTests(unittest.TestCase):
+    def setUp(self):
+        self.client = MVRClient(MVRConfig(base_url="https://example.test", api_key="test-key", max_retries=0))
+        self.request = Mock()
+        self.client.session.request = self.request
+
+    @staticmethod
+    def response(status_code=200, payload=None, headers=None):
+        result = Mock()
+        result.status_code = status_code
+        result.headers = headers or {}
+        result.json.return_value = payload or {"status": "ok"}
+        result.text = ""
+        return result
+
+    def test_certified_helpers_preserve_route_body_and_headers(self):
+        self.request.side_effect = [self.response(), self.response(), self.response()]
+
+        self.client.first_call({"entity": "Example", "country": "UG", "question": "Should it launch?"})
+        self.client.recommended_inputs({"endpoint": "/v1/decision-check", "entity_archetype": "distributor_network"})
+        self.client.remediation_path({"decision_result": {"status": "abstained"}, "target_verdict": "pilot_only"})
+
+        calls = self.request.call_args_list
+        self.assertEqual([call.args[1] for call in calls], [
+            "https://example.test/v1/first-call",
+            "https://example.test/v1/recommended-inputs",
+            "https://example.test/v1/remediation-path",
+        ])
+        self.assertEqual(calls[0].kwargs["json"]["question"], "Should it launch?")
+        self.assertEqual(calls[1].kwargs["json"]["entity_archetype"], "distributor_network")
+        self.assertEqual(calls[2].kwargs["json"]["target_verdict"], "pilot_only")
+        self.assertEqual(self.client.session.headers["X-API-Key"], "test-key")
+        self.assertEqual(self.client.session.headers["X-Response-Profile"], "full_advisory")
+        self.assertTrue(self.client.session.headers["User-Agent"].endswith("6.32.3"))
+
+    def test_structured_http_error_is_preserved(self):
+        self.request.return_value = self.response(
+            422,
+            {"error": "Utility validation failed", "details": ["target_verdict must be canonical"]},
+        )
+
+        with self.assertRaises(MVRApiError) as caught:
+            self.client.remediation_path({"decision_result": {}, "target_verdict": "pilot_only"})
+
+        self.assertEqual(caught.exception.status_code, 422)
+        self.assertEqual(caught.exception.error_data["error"], "Utility validation failed")
+
+    def test_extension_helper_preserves_custom_fields_and_rejects_invalid_known_enums(self):
+        item = define_evidence_item({
+            "id": "EV-EXT-1",
+            "evidence_type": "public_filing",
+            "custom_signal": {"registry_match": True},
+        })
+        self.assertEqual(item["custom_signal"], {"registry_match": True})
+
+        with self.assertRaisesRegex(ValueError, "privacy_envelope.consent_basis"):
+            define_evidence_item({"privacy_envelope": {"consent_basis": "assumed"}})
+        with self.assertRaisesRegex(ValueError, "provenance_ledger.extraction_method"):
+            define_evidence_item({"provenance_ledger": {"extraction_method": "human_verified"}})
+        with self.assertRaisesRegex(ValueError, r"source_artifacts\[0\].extraction_method"):
+            define_evidence_item({"source_artifacts": [{"extraction_method": "ocr_magic"}]})
+        with self.assertRaisesRegex(ValueError, "evidence_type"):
+            define_evidence_item({"evidence_type": None})
+        with self.assertRaisesRegex(ValueError, "privacy_envelope.consent_basis"):
+            define_evidence_item({"privacy_envelope": {"consent_basis": None}})
+
+
+if __name__ == "__main__":
+    unittest.main()

mvr_api_client-6.32.0/README.md

@@ -1,92 +0,0 @@
-# MVR API Python Client
-
-Lightweight Python client for the current **MVR API - Minimum Viable Relationships** surface.
-
-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/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
-- MCP endpoint: https://africanmarketos.com/mcp
-- 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.
-
-Commercial, production, SaaS, consulting, or AI-agent deployment use requires authorization from African Market OS.

mvr_api_client-6.32.0/mvr_api/__init__.py

@@ -1,13 +0,0 @@
-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.0/mvr_api/models.py

@@ -1,22 +0,0 @@
-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

mvr_api_client-6.32.0/mvr_api_client.egg-info/requires.txt

@@ -1,2 +0,0 @@
-requests>=2.25.0
-pydantic<3.0,>=1.8