cardforge-ai 1.3.0

Offline evidence-backed trust cards and release-readiness checks for AI repositories.

CardForge

CardForge is an offline, publishable Python CLI that turns AI repositories into reviewable, release-ready projects.

It scans a repository, detects evidence such as model providers, AI frameworks, data files, evaluation assets, tests, workflows, environment variable names, and deployment signals, then generates structured trust documentation for the project.

No API key is required. The "magic" is deterministic static analysis, not an LLM call.

What changed in 1.3

CardForge is now GitHub-to-PyPI release ready. The project includes a Trusted Publishing workflow, a release tag/version guard, distribution validation, and maintainer publishing documentation.

CardForge also produces more precise generated cards. cardforge analyze and cardforge init do not only list dependencies; they attach evidence to specific files and lines where possible. The scanner extracts provider imports, model names, environment variable names, routes, prompt/template signals, RAG/vector signals, tool-calling signals, dataset schema hints, and redacted secret-like findings.

The generated AI_PROJECT_CARD.md includes a Codebase Analysis section so reviewers can see why CardForge made each claim.

What CardForge creates

Depending on the project type, CardForge can generate:

cardforge.toml
AI_PROJECT_CARD.md
MODEL_CARD.md
DATASET_CARD.md
EVAL_CARD.md
docs/limitations.md
CITATION.cff
.github/workflows/cardforge.yml

Core features

• Evidence-backed cardforge init that drafts cards from repository signals.
• cardforge analyze to show what CardForge detected before writing files.
• cardforge lint to enforce required sections, non-empty content, placeholders, README, license, and workflow presence.
• cardforge status for a compact release-readiness summary.
• cardforge suggest for deterministic remediation guidance.
• cardforge export for Markdown or JSON reports.
• SARIF output for code scanning integrations.
• GitHub Action workflow generation for pull-request checks.
• No runtime dependencies outside the Python standard library.
• No AI provider API keys.

Install

From source:

python -m pip install .
cardforge --version

After publishing to PyPI, users install it like this:

python -m pip install cardforge-ai
cardforge --version

Quick start in another AI project

cd ~/Downloads/AIVA
cardforge analyze
cardforge init --type ai-application --name "AIVA" --yes
cardforge lint
cardforge status

init scans the repository by default. To see the scan without writing files:

cardforge analyze --format markdown --output cardforge-analysis.md

To regenerate cards after the repository changes:

cardforge init --type ai-application --name "AIVA" --yes --force

To disable repo scanning and use generic deterministic text:

cardforge init --type ai-application --name "AIVA" --yes --no-magic

Project types

Type	Purpose
ai-application	AI application, assistant, RAG system, or agentic workflow
model	Standalone model repository
dataset	Dataset repository
evaluation-benchmark	Evaluation benchmark or prompt/test suite
research-repo	Research/code repository with AI artifacts

Command reference

cardforge analyze

Scans the repository and prints evidence.

cardforge analyze
cardforge analyze --format json --output cardforge-analysis.json
cardforge analyze --format markdown --output cardforge-analysis.md

Detected evidence can include:

• README title and summary
• Python and Node package metadata
• dependency and import evidence with file/line references
• AI providers and frameworks
• model/deployment name strings
• prompt-template, system-instruction, RAG/vector, and tool-calling signals
• FastAPI/Flask/Express-style route surfaces
• environment variable names without exposing secret values
• secret-like committed values, reported with redacted snippets
• data-like files and CSV/JSON/JSONL schema hints
• test and evaluation paths
• GitHub workflows, Docker/deployment files, and lockfiles
• evidence-confidence and release-readiness scores
• risk signals tied to the detected codebase

cardforge init

Generates cards, config, and optionally a GitHub Actions workflow.

cardforge init --type ai-application --name "Note Assistant" --yes
cardforge init --type dataset --name "Receipt OCR Dataset" --yes
cardforge init --type model --name "Small Classifier" --model-name "distilbert-base" --yes

Useful options:

Option	Description
--magic / --no-magic	Enable or disable offline repository scan drafting
--type	Project type
--name	Project name
--description	Short project description
--license	SPDX license identifier or license name
--model / --no-model	Include or exclude model card
--dataset / --no-dataset	Include or exclude dataset card
--eval / --no-eval	Include or exclude evaluation card
--github-action / --no-github-action	Include or exclude workflow
--yes	Non-interactive defaults
--force	Overwrite existing generated files
--dry-run	Show actions without writing

cardforge lint

Validates configured cards.

cardforge lint
cardforge lint --format json
cardforge lint --format sarif --output cardforge.sarif
cardforge lint --fail-on-warnings

Default checks include:

• config shape and required project metadata
• configured cards exist
• required Markdown headings exist
• required sections are not empty
• placeholder text such as TO COMPLETE, TODO, or TBD is absent
• repository has a README
• repository has a license file
• configured GitHub workflow exists when enabled

cardforge status

cardforge status
cardforge status --format json

cardforge suggest

cardforge suggest

cardforge export

cardforge export --format markdown --output cardforge-report.md
cardforge export --format json --output cardforge-report.json

cardforge doctor

cardforge doctor

cardforge schema

cardforge schema

Configuration

CardForge uses cardforge.toml.

[project]
name = "AIVA"
type = "ai-application"
description = "An AI assistant project."
license = "Apache-2.0"
author = "Project Maintainer"
repository_url = "https://github.com/example/aiva"

[cards]
ai_project_card = "AI_PROJECT_CARD.md"
model_card = "MODEL_CARD.md"
eval_card = "EVAL_CARD.md"
limitations = "docs/limitations.md"

[requirements]
require_readme = true
require_license_file = true
fail_on_todos = true
require_non_empty_sections = true

[github]
action_enabled = true

CI usage in target repositories

Generated projects include .github/workflows/cardforge.yml:

name: CardForge

on:
  pull_request:
  push:
    branches: [main, master]

jobs:
  cardforge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"
      - run: python -m pip install cardforge-ai
      - run: cardforge lint --format text

Development

python -m pip install -e .[dev]
python -m unittest discover -s tests -v
cardforge analyze --root .
cardforge lint --root .

Build distributions:

python -m pip install --upgrade build twine
python -m build
twine check dist/*

Publishing to PyPI

This repository is already structured as a Python package:

• source package under src/cardforge
• CLI entry point under [project.scripts]
• package metadata in pyproject.toml
• package data configured for templates
• CI workflow for tests
• publish workflow for Trusted Publishing

See docs/PYPI_TRUSTED_PUBLISHING.md for the GitHub Actions Trusted Publishing path and docs/publishing.md for package build details.

Security model

CardForge core commands are offline. They do not send repository contents to external services. The scanner reads local text files, package metadata, and common repository paths. It intentionally records environment variable names, not secret values.

Design principles

• Offline first.
• Evidence-backed over blank templates.
• CI-friendly output.
• No required AI API keys.
• Maintainer review remains mandatory.
• Static analysis assists trust documentation; it does not prove runtime safety or legal compliance.