audit_ai_bom_completeness

Instructions

Implementation Reference

• server.py:245-318 (handler)

  The core handler function that audits an AI-BOM JSON document against the 10 required field categories defined in AI_BOM_REQUIRED_FIELDS. It parses input JSON, checks each category's fields via substring matching (accounting for underscores/spaces), returns per-category COMPLETE/PARTIAL/MISSING status, overall score, and a recommendation.

  @mcp.tool()
  def audit_ai_bom_completeness(ai_bom_json: str, api_key: str = "") -> str:
      """Audit an existing AI-BOM for completeness against the 10 required field categories.
      Returns per-category pass/fail + gap list.
  
      Behavior:
          This tool is read-only and stateless — it produces analysis output
          without modifying any external systems, databases, or files.
          Safe to call repeatedly with identical inputs (idempotent).
          Free tier: 10/day rate limit. Pro tier: unlimited.
          No authentication required for basic usage.
  
      When to use:
          Use this tool when you need structured analysis or classification
          of inputs against established frameworks or standards.
  
      When NOT to use:
          Not suitable for real-time production decision-making without
          human review of results.
  
      Args:
          ai_bom_json (str): The ai bom json to analyze or process.
          api_key (str): The api key to analyze or process.
  
      Behavioral Transparency:
          - Side Effects: This tool is read-only and produces no side effects. It does not modify
            any external state, databases, or files. All output is computed in-memory and returned
            directly to the caller.
          - Authentication: No authentication required for basic usage. Pro/Enterprise tiers
            require a valid MEOK API key passed via the MEOK_API_KEY environment variable.
          - Rate Limits: Free tier: 10 calls/day. Pro tier: unlimited. Rate limit headers are
            included in responses (X-RateLimit-Remaining, X-RateLimit-Reset).
          - Error Handling: Returns structured error objects with 'error' key on failure.
            Never raises unhandled exceptions. Invalid inputs return descriptive validation errors.
          - Idempotency: Fully idempotent — calling with the same inputs always produces the
            same output. Safe to retry on timeout or transient failure.
          - Data Privacy: No input data is stored, logged, or transmitted to external services.
            All processing happens locally within the MCP server process.
      """
      allowed, msg, tier = check_access(api_key)
      if not allowed:
          return json.dumps({"error": msg, "upgrade_url": STRIPE_199})
      if err := _rl(tier):
          return json.dumps({"error": err, "upgrade_url": STRIPE_199})
  
      try:
          doc = json.loads(ai_bom_json) if isinstance(ai_bom_json, str) else ai_bom_json
      except Exception as e:
          return json.dumps({"error": f"Invalid JSON: {e}"})
  
      blob = json.dumps(doc).lower()
      results = []
      passed = 0
      for cat, fields in AI_BOM_REQUIRED_FIELDS.items():
          missing = []
          for f in fields:
              if f.lower() not in blob and f.replace("_", "").lower() not in blob and f.replace("_", " ").lower() not in blob:
                  missing.append(f)
          full = len(missing) == 0
          partial = len(missing) < len(fields)
          if full:
              passed += 1
          results.append({
              "category": cat,
              "status": "COMPLETE" if full else "PARTIAL" if partial else "MISSING",
              "missing_fields": missing,
          })
      total = len(AI_BOM_REQUIRED_FIELDS)
      return json.dumps({
          "overall_score_percent": round(passed / total * 100, 1),
          "categories_complete": f"{passed}/{total}",
          "categories_detail": results,
          "recommendation": "Review 'MISSING' and 'PARTIAL' categories. Federal procurement reviewers reject AI-BOMs missing any of the 10 categories." if passed < total else "AI-BOM is complete. Sign with Pro tier for auditor-ready export.",
      }, indent=2)

• server.py:69-80 (schema)

  The schema defining the 10 required AI-BOM categories and their expected fields. This is the reference data against which audit_ai_bom_completeness validates.

  AI_BOM_REQUIRED_FIELDS = {
      "model_identity": ["name", "version", "organisation", "licence", "release_date", "model_id_hash"],
      "model_architecture": ["architecture_type", "parameter_count", "context_window", "framework", "training_compute_flops"],
      "training_data": ["dataset_sources", "dataset_sizes", "data_provenance", "filtering_applied", "synthetic_data_percent", "copyright_status"],
      "fine_tuning": ["base_model", "fine_tune_method", "fine_tune_dataset", "fine_tune_steps", "rlhf_applied"],
      "evaluation": ["benchmarks_run", "benchmark_scores", "bias_testing_results", "red_team_findings", "eval_dataset_hash"],
      "dependencies": ["inference_engines", "tokenisers", "safety_filters", "retrieval_systems", "tools_registered"],
      "security_controls": ["prompt_injection_defence", "output_filtering", "pii_scrubbing", "adversarial_robustness_rating"],
      "governance": ["risk_classification", "regulations_applicable", "human_oversight_mechanism", "incident_reporting_contact"],
      "usage_restrictions": ["acceptable_use_policy", "prohibited_use_cases", "export_control_status", "region_restrictions"],
      "distribution": ["distribution_channels", "access_controls", "update_cadence", "decommissioning_policy"],
  }

• server.py:245-246 (registration)

  The tool is registered as an MCP tool via the @mcp.tool() decorator on line 245, binding it to the FastMCP 'ai-bom' server instance.

  @mcp.tool()
  def audit_ai_bom_completeness(ai_bom_json: str, api_key: str = "") -> str: