Patra Knowledge Base

The Patra Knowledge Base is a system designed to manage and track AI/ML models, with the objective of making them more accountable and trustworthy. It's a key part of the Patra ModelCards framework, which aims to improve transparency and accountability in AI/ML models throughout their entire lifecycle. This includes the model's initial training phase, subsequent deployments, and ongoing usage, whether by the same or different individuals.

Tags: CI4AI, PADI

For guidance on what How-To Guides and Explanation content covers, see Diátaxis.

License

The Patra Knowledge Base is copyrighted by Plale Lab at The University of Oregon and distributed under the BSD 3-Clause License. See the LICENSE file for more details.

References

Acknowledgements

This work has been funded by grants from the National Science Foundation, and in part through Plale Lab at The University of Oregon.

National Science Foundation (NSF) funded AI institute for Intelligent Cyberinfrastructure with Computational Learning in the Environment (ICICLE) (OAC 2112606)

Issue reporting

Report issues via GitHub Issues.

How-To Guides

Prerequisites

System Requirements

Docker and Docker Compose installed and running.
Open network access to the following ports:
- 8000 (Primary REST API)
- 5002 (legacy Flask server, suspended)
- 8050 (legacy MCP server, suspended)

Dependencies

PostgreSQL: Required for the active FastAPI backend.
Neo4j: Legacy-only dependency retained for archived code paths; not required for new backend work.
[Optional] OpenAI API Key: If the system needs to support Model Card similarities, you need to obtain a valid Open AI API key. Refer to the OpenAI documentation for instructions. This is disabled by default.

1. Set up Environment Variables

Model Similarity (Optional)
To enable model similarity detection using OpenAI embeddings, set ENABLE_MC_SIMILARITY to True and provide your OpenAI API key:

export ENABLE_MC_SIMILARITY=True
export OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>

Hugging Face Integration (Optional)
To upload models and artifacts to Hugging Face, create a repository and generate an access token. Then, set the following environment variables:

export HF_HUB_USERNAME=<your-hf-username>
export HF_HUB_TOKEN=<your-hf-access-token>

Requires write access to the target Hugging Face repo.

GitHub Integration (Optional)
To upload models and artifacts to GitHub, create a repository and generate an access token. Then, set the following environment variables:

export GH_HUB_USERNAME=<your-github-username>
export GH_HUB_TOKEN=<your-github-personal-access-token>

Requires repo scope enabled on the GitHub token.

2. Clone the repository and start services

git clone https://github.com/Plale-Lab/patra-knowledge-base.git
cd patra-knowledge-base
docker compose -f docker-compose.backend.yml up --build

The supported service stack is the PostgreSQL-backed FastAPI app under rest_server/, started with docker-compose.backend.yml. Legacy Neo4j compose assets remain in the repository for archival reference only and should not be treated as the supported deployment path.

To shut down services, use:

docker compose -f docker-compose.backend.yml down

3. Creating Model Cards and Datasheets (Asset Ingest API)

External systems and partner organizations publish and manage model cards and datasheets through the protected asset ingest API on the primary REST server, mounted under /v1/assets:

Endpoint	Method	Description
`/v1/assets/model-cards`	POST	Create a model card.
`/v1/assets/datasheets`	POST	Create a datasheet.
`/v1/assets/model-cards/bulk`	POST	Create up to 25 model cards in one request.
`/v1/assets/datasheets/bulk`	POST	Create up to 25 datasheets in one request.
`/v1/assets/model-cards/{asset_id}`	PATCH	Update an existing model card.
`/v1/assets/datasheets/{asset_id}`	PATCH	Update an existing datasheet.
`/v1/assets/records`	GET	List/search model cards and datasheets available for editing.

Authentication: send one of the following on every request:

X-Asset-Org: <org> + X-Asset-Api-Key: <secret> (or Authorization: Bearer <secret>) — org/secret pairs are configured via the PATRA_ASSET_INGEST_KEYS_JSON environment variable.
X-Tapis-Token: <token> — used by the Patra frontend for logged-in user submissions.

For brevity, the examples below set the org/key headers once as shell variables:

export PATRA_URL=http://localhost:8000
export ASSET_ORG=<your-org>
export ASSET_KEY=<your-secret>

Create a model card:

curl -X POST "$PATRA_URL/v1/assets/model-cards" \
  -H "X-Asset-Org: $ASSET_ORG" \
  -H "X-Asset-Api-Key: $ASSET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External Model",
    "version": "1.0",
    "short_description": "Injected model card",
    "author": "Org A",
    "ai_model": {
      "name": "External Model Binary",
      "version": "1.0",
      "framework": "PyTorch",
      "model_type": "cnn",
      "model_metrics": {"top_1_accuracy": 0.92}
    }
  }'

Returns 201 Created with {"asset_type": "model_card", "asset_id": <int>, "asset_uuid": <uuid>, "organization": "...", "created": true}. A duplicate (same name/version/author) returns 409 Conflict.

Create a datasheet:

curl -X POST "$PATRA_URL/v1/assets/datasheets" \
  -H "X-Asset-Org: $ASSET_ORG" \
  -H "X-Asset-Api-Key: $ASSET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publication_year": 2025,
    "version": "1.0",
    "titles": [{"title": "Partner Dataset"}],
    "creators": [{"creator_name": "Org A"}]
  }'

Returns 201 Created with {"asset_type": "datasheet", "asset_id": <int>, ...}, or 409 Conflict on a duplicate.

Bulk create model cards (up to 25 per request; each item is validated and inserted independently, so partial success is possible):

curl -X POST "$PATRA_URL/v1/assets/model-cards/bulk" \
  -H "X-Asset-Org: $ASSET_ORG" \
  -H "X-Asset-Api-Key: $ASSET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {"name": "Model One", "version": "1.0"},
      {"name": "Model Two", "version": "2.0"}
    ]
  }'

Returns 200 OK with {"total", "created", "duplicates", "failed", "results": [...]}, one result entry per input item (with an error message for any that failed). POST /v1/assets/datasheets/bulk takes the same shape with "assets" as a list of datasheet payloads.

Update a model card or datasheet (PATCH, full replacement of the asset's editable fields — send the complete payload, not a partial diff):

curl -X PATCH "$PATRA_URL/v1/assets/model-cards/123" \
  -H "X-Asset-Org: $ASSET_ORG" \
  -H "X-Asset-Api-Key: $ASSET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External Model",
    "version": "1.1",
    "short_description": "Updated description",
    "author": "Org A"
  }'

curl -X PATCH "$PATRA_URL/v1/assets/datasheets/456" \
  -H "X-Asset-Org: $ASSET_ORG" \
  -H "X-Asset-Api-Key: $ASSET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publication_year": 2025,
    "version": "1.1",
    "titles": [{"title": "Partner Dataset (revised)"}],
    "creators": [{"creator_name": "Org A"}]
  }'

Returns 200 OK with {"asset_type", "asset_id", "organization", "updated": true}.

List/search editable records:

curl -G "$PATRA_URL/v1/assets/records" \
  -H "X-Asset-Org: $ASSET_ORG" \
  -H "X-Asset-Api-Key: $ASSET_KEY" \
  --data-urlencode "q=titanic" \
  --data-urlencode "limit=20"

Returns 200 OK with a JSON array of {"asset_type", "asset_id", "title", "subtitle", "description", "kind_label", "updated_at"}, covering both model cards and approved datasheets, newest-updated first. q is optional (omit it to list recent records) and limit defaults to 20 (max 100).

See rest_server/asset_create_models.py for the full set of optional fields (e.g. bias_analysis, xai_analysis, DataCite-style datasheet fields like subjects, dates, funding_references), and examples/model_cards/ / examples/datasheets/ for larger sample payloads.

4. Using the MCP Server (Optional)

This section describes the suspended in-repo Neo4j-based MCP server for archival/reference purposes only. It is not part of the active PostgreSQL backend and should not be used for new integrations.

The legacy MCP server provides:

4 Resources for reading model card data by identifier
10 Tools for operations, queries, and state modifications

For Claude Desktop:

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

For the legacy archived MCP server:

{
  "mcpServers": {
    "patra-kg": {
      "url": "http://localhost:8050/sse"
    }
  }
}

For Custom AI Agents: Connect to the MCP server endpoint:

MCP Server: http://localhost:8050/sse (legacy archived endpoint)

Historical Example Usage:

With MCP Server:

User: "Upload this model card and then search for similar models"
AI Assistant: [Uses upload_modelcard tool, then search_modelcards tool]
Result: Model card uploaded and similar models found

Reading model card data:

User: "Get information about model card test-mc-123"
AI Assistant: [Reads modelcard://test-mc-123 resource]
Result: Returns complete model card data

Explanation

Status Notice

Patra's active backend is now the FastAPI + PostgreSQL service under rest_server/.

The following Neo4j-based components are retained only for archive/reference compatibility and are no longer part of the active backend path:

legacy/legacy_server/
mcp_server/
legacy/ingester/neo4j_ingester.py
legacy/reconstructor/mc_reconstructor.py
Neo4j-oriented Docker/Make targets

For all new development, deployment, integration, and operational work, use the PostgreSQL-backed REST API only.

At the heart of the Patra Knowledge Base is the concept of Model Cards. These cards are essentially detailed records that provide essential information about each AI/ML model. This information includes technical details like the model's accuracy and latency, but it goes beyond that to include non-technical aspects such as fairness, explainability, and the model's behavior in various deployment environments. This holistic approach is intended to create a comprehensive understanding of the model's strengths and weaknesses, enabling more informed decisions about its use and deployment

Key features and capabilities of the Patra ModelCards Framework include:

Semi-automated information capture: Patra reduces the burden of manual documentation by automatically capturing information about model fairness, explainability, and performance in different deployment environments. This automation is facilitated by the Model Card Toolkit , which invokes analysis tools and integrates the results directly into the Model Cards.
Relational system of record: Patra's active backend now uses PostgreSQL as the system of record for model cards, datasheets, and protected asset ingestion APIs. Neo4j-era graph components are preserved only as legacy reference code and are no longer the supported runtime path.
Provenance tracking: Patra leverages the concepts of forward and backward provenance to comprehensively track the relationships between models, datasets, and deployment instances. This makes it possible to understand the lineage of models, trace their origins, and analyze their usage patterns.
Real-time deployment information: Patra integrates with the CKN Edge AI Framework to capture real-time information about model execution in edge environments. This includes data on performance, resource usage, and other relevant metrics, which can be used to optimize deployments and gain insights into model behavior in real-world settings.
Machine-actionable API: Patra provides a machine-actionable API that allows intelligent systems in the edge-cloud continuum to query the knowledge base and make informed decisions about model selection. This enables automated model selection based on various criteria, including fairness, explainability, and performance metrics, further enhancing accountability and transparency.
Versioning and Similarity Analysis: Patra infers relationships between model cards such as "alternateOf," "revisionOf," and "transformativeUseOf" by leveraging embedding vectors and cosine similarity comparisons. This capability is essential for tracking model evolution, identifying different versions, and understanding how models are adapted and reused over time.

By combining these capabilities, the Patra Knowledge Base provides a robust foundation for trustworthy and accountable AI/ML model management within the edge-cloud continuum. This framework addresses crucial aspects of transparency, provenance tracking, and performance monitoring, ultimately contributing to more responsible and reliable AI deployments.

For more information, please refer to the Patra ModelCards paper.

Patra Servers

Patra provides multiple server implementations for different use cases.

1. Primary REST API (FastAPI + PostgreSQL)

The primary REST API is implemented with FastAPI and backed by PostgreSQL. It is intended for new integrations and powers the privacy-aware model card and datasheet APIs.

Code location: rest_server/
Default port: 8000
Example endpoints (non-exhaustive):
- GET / – Simple health/info endpoint.
- GET /modelcards – List model cards (public-only by default; private when authorized).
- GET /modelcard/{id} – Retrieve a single model card.
- PUT /modelcard/{id} – Update a model card and its linked AI model (authenticated).
- GET /datasheets – List datasheets (public-only by default; private when authorized).
- GET /datasheet/{identifier} – Retrieve a single datasheet with normalized DataCite-style metadata.
- PUT /datasheet/{identifier} – Update a datasheet, including title and description (authenticated).
- POST /v1/assets/model-cards – Create a model card (protected asset ingest API, see below).
- POST /v1/assets/datasheets – Create a datasheet (protected asset ingest API, see below).

The FastAPI app is exposed via the rest_server package (see rest_server/main.py) and is built into the Docker image plalelab/patra-backend:latest using rest_server/Dockerfile (see scripts/build-push-backend.sh).

2. Legacy REST Server (Flask + Neo4j)

The legacy REST server is built using Flask and exposes a RESTful API for interaction with the Patra Knowledge Graph (KG) stored in Neo4j. It is retained in-repo for archive/reference purposes only and is not part of the active backend going forward.

Code location: legacy/legacy_server/
Default port: 5002

Key endpoints include:

Endpoint	Method	Description
`/modelcard`	POST	Create (upload) a model card.
`/modelcard/{id}`	GET	Retrieve a model card.
`/modelcard/{id}`	HEAD	Return linkset relations via HTTP Link headers.
`/modelcard/{id}`	PUT	Update an existing model card.
`/datasheet`	POST	Upload a datasheet.
`/modelcards/search?q=...`	GET	Full-text search for model cards.
`/modelcard/{id}/download_url`	GET	Retrieve the download URL for a model artifact.
`/modelcards`	GET	List all model cards.
`/modelcard/{id}/deployments`	GET	Retrieve deployments for a model.
`/modelcard/{id}/location`	PUT	Update the model's location.
`/modelcard/id`	POST	Generate a persistent model ID (PID) for author, name, version.
`/modelcard/{id}/huggingface_credentials`	GET	Get Hugging Face credentials (if configured).
`/modelcard/{id}/github_credentials`	GET	Get GitHub credentials (if configured).
`/modelcard/{id}/linkset`	GET	Retrieve linkset relations (same output as HEAD but with empty body & Link headers).
`/device`	POST	Register an edge device.
`/user`	POST	Register a user.

For more information on the legacy REST endpoints, please refer to the API documentation.

3. MCP (Model Context Protocol) Server, Suspended

The in-repo MCP server is Neo4j-backed legacy code retained for reference. It is not part of the active PostgreSQL backend path.

Endpoint	Type	Description
`modelcard://{id}`	Resource	Retrieve a model card by ID.
`modelcard://{id}/download_url`	Resource	Retrieve the download URL for a model artifact.
`modelcard://{id}/deployments`	Resource	Retrieve deployments for a model.
`modelcard://{id}/linkset`	Resource	Retrieve linkset relations for a model card.
`create_edge`	Tool	Create an edge between two nodes in the Patra Knowledge graph.
`search_modelcards`	Tool	Full-text search for model cards.
`list_modelcards`	Tool	List all model cards.
`upload_modelcard`	Tool	Upload a model card.
`update_modelcard`	Tool	Update an existing model card.
`upload_datasheet`	Tool	Upload a datasheet.
`update_model_location`	Tool	Update the model's location.
`register_device`	Tool	Register an edge device.
`register_user`	Tool	Register a user.

The MCP server runs on port 8050 and uses Server-Sent Events (SSE) transport for communication.

Name		Name	Last commit message	Last commit date
Latest commit History 226 Commits
.github		.github
db		db
docs		docs
examples		examples
k8s		k8s
mcp_server		mcp_server
poc		poc
rest_server		rest_server
scripts		scripts
shared		shared
tests		tests
.coveragerc		.coveragerc
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
ci-component.yml		ci-component.yml
docker-compose.backend.yml		docker-compose.backend.yml

Navigation Menu

Uh oh!

Repository files navigation

Patra Knowledge Base

License

References

Acknowledgements

Issue reporting

How-To Guides

Prerequisites

System Requirements

Dependencies

1. Set up Environment Variables

2. Clone the repository and start services

3. Creating Model Cards and Datasheets (Asset Ingest API)

4. Using the MCP Server (Optional)

Explanation

Status Notice

Patra Servers

1. Primary REST API (FastAPI + PostgreSQL)

2. Legacy REST Server (Flask + Neo4j)

3. MCP (Model Context Protocol) Server, Suspended

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Patra Knowledge Base

License

References

Acknowledgements

Issue reporting

How-To Guides

Prerequisites

System Requirements

Dependencies

1. Set up Environment Variables

2. Clone the repository and start services

3. Creating Model Cards and Datasheets (Asset Ingest API)

4. Using the MCP Server (Optional)

Explanation

Status Notice

Patra Servers

1. Primary REST API (FastAPI + PostgreSQL)

2. Legacy REST Server (Flask + Neo4j)

3. MCP (Model Context Protocol) Server, Suspended

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages