Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GingerlyData247/SOTeam4-P2/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Trustworthy Model Registry (TMR) is a cloud-native system for ingesting, evaluating, storing, and serving machine learning artifacts with explicit, machine-verifiable trust signals. This guide will help you get up and running quickly.
The API is live at: https://c1r52eygxi.execute-api.us-east-2.amazonaws.com/docs

​
Installation

1

Clone the repository

First, clone the repository to your local machine:
git clone <repository-url>
cd trustworthy-model-registry
2

Install dependencies

The project requires Python 3.12. Install all dependencies using the provided script:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
./run install
This installs all required packages from requirements.txt:
requests>=2.0.0
huggingface_hub
beautifulsoup4
gitpython
pytest
coverage
fastapi>=0.115
uvicorn>=0.30
pydantic>=2.8
mangum>=0.17
boto3>=1.34
python-multipart>=0.0.9
3

Configure environment variables

Set up the required environment variables for AWS and authentication:
export AWS_REGION=us-east-2
export S3_BUCKET=<your-s3-bucket>
export AUTH_TOKEN=<default-admin-token>
export HUGGINGFACE_HUB_TOKEN=<optional-hf-token>
export GITHUB_TOKEN=<optional-github-token>
For local development, you can set LOCAL_STORAGE=1 to use filesystem storage instead of S3.
4

Start the server

Launch the FastAPI server locally:
uvicorn src.run:app --reload
The API will be available at:

​
Your first API call

Now that the server is running, let’s make your first API call to check system health and ingest a model.

​
Check system health

Verify the API is running correctly: 
curl http://localhost:8000/api/health

{
  "status": "ok",
  "uptime_s": 42,
  "models": 0
}

​
Ingest a HuggingFace model

Ingest a model from HuggingFace. The system will automatically compute trust metrics: 
curl -X POST "http://localhost:8000/api/artifact/model" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://huggingface.co/google-bert/bert-base-uncased",
    "name": "bert-base-uncased"
  }'

{
  "metadata": {
    "name": "bert-base-uncased",
    "id": "1",
    "type": "model"
  },
  "data": {
    "url": "https://huggingface.co/google-bert/bert-base-uncased",
    "download_url": "https://s3.amazonaws.com/..."
  }
}
Models are only ingested if they pass the reviewedness threshold (≥ 0.5). Models with low review coverage will be rejected with a 424 status code.

​
Get model ratings

Retrieve the computed trust metrics for an ingested model: 
curl http://localhost:8000/api/artifact/model/1/rate

{
  "name": "bert-base-uncased",
  "category": "model",
  "net_score": 0.7234,
  "net_score_latency": 1523.45,
  "ramp_up_time": 0.8,
  "ramp_up_time_latency": 234.12,
  "bus_factor": 0.9,
  "bus_factor_latency": 156.78,
  "performance_claims": 0.6,
  "performance_claims_latency": 89.23,
  "license": 1.0,
  "license_latency": 45.67,
  "dataset_and_code_score": 0.75,
  "dataset_and_code_score_latency": 312.45,
  "dataset_quality": 0.8,
  "dataset_quality_latency": 198.34,
  "code_quality": 0.85,
  "code_quality_latency": 423.56,
  "reproducibility": 0.9,
  "reproducibility_latency": 67.89,
  "reviewedness": 0.75,
  "reviewedness_latency": 289.12,
  "tree_score": 0.5,
  "tree_score_latency": 134.67,
  "size_score": {
    "raspberry_pi": 0.2,
    "jetson_nano": 0.4,
    "desktop_pc": 0.8,
    "aws_server": 1.0
  },
  "size_score_latency": 23.45
}

​
Retrieve an artifact

Get details about a specific artifact: 
curl http://localhost:8000/api/artifacts/model/1

{
  "metadata": {
    "name": "bert-base-uncased",
    "id": "1",
    "type": "model"
  },
  "data": {
    "url": "https://huggingface.co/google-bert/bert-base-uncased",
    "download_url": "https://s3.amazonaws.com/..."
  }
}

​
List all artifacts

Enumerate all artifacts in the registry: 
curl -X POST "http://localhost:8000/api/artifacts" \
  -H "Content-Type: application/json" \
  -d '[{
    "name": "*",
    "types": ["model"]
  }]'

[
  {
    "name": "bert-base-uncased",
    "id": "1",
    "type": "model"
  },
  {
    "name": "gpt2-small",
    "id": "2",
    "type": "model"
  }
]

​
Next steps

Architecture

Learn about the system architecture and components

API Reference

Explore the full OpenAPI specification

​
Common operations

curl -X DELETE http://localhost:8000/api/artifacts/model/1
Expected response:
{
  "status": "deleted",
  "id": "1"
}

curl -X POST "http://localhost:8000/api/artifact/byRegEx" \
  -H "Content-Type: application/json" \
  -d '{
    "regex": "bert.*"
  }'
Returns all artifacts matching the pattern in their name or model card.
curl -X POST "http://localhost:8000/api/artifact/model/1/license-check" \
  -H "Content-Type: application/json" \
  -d '{
    "github_url": "https://github.com/huggingface/transformers"
  }'
Returns true or false based on license compatibility.
curl http://localhost:8000/api/artifact/model/1/lineage
Returns a graph of parent models and dependencies:
{
  "nodes": [
    {
      "artifact_id": "1",
      "name": "bert-fine-tuned",
      "source": "config_json",
      "metadata": {}
    },
    {
      "artifact_id": "external:bert-base-uncased",
      "name": "bert-base-uncased",
      "source": "config_json",
      "metadata": {"external": true}
    }
  ],
  "edges": [
    {
      "from_node_artifact_id": "external:bert-base-uncased",
      "to_node_artifact_id": "1",
      "relationship": "base_model"
    }
  ]
}
Use the /docs endpoint to explore the interactive Swagger UI and test all API endpoints directly in your browser.

Build docs developers (and LLMs) love

Get started for freeTalk to us