Metadata-Version: 2.4
Name: cardforge-ai
Version: 1.3.0
Summary: Offline evidence-backed trust cards and release-readiness checks for AI repositories.
Author: CardForge Maintainers
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/cardforge/cardforge
Project-URL: Documentation, https://github.com/cardforge/cardforge/tree/main/docs
Project-URL: Issues, https://github.com/cardforge/cardforge/issues
Project-URL: Source, https://github.com/cardforge/cardforge
Keywords: ai,model-card,dataset-card,evaluation,open-source,governance,cli,responsible-ai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

# 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:

```text
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:

```bash
python -m pip install .
cardforge --version
```

After publishing to PyPI, users install it like this:

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

## Quick start in another AI project

```bash
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:

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

To regenerate cards after the repository changes:

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

To disable repo scanning and use generic deterministic text:

```bash
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.

```bash
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.

```bash
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.

```bash
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`

```bash
cardforge status
cardforge status --format json
```

### `cardforge suggest`

```bash
cardforge suggest
```

### `cardforge export`

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

### `cardforge doctor`

```bash
cardforge doctor
```

### `cardforge schema`

```bash
cardforge schema
```

## Configuration

CardForge uses `cardforge.toml`.

```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`:

```yaml
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

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

Build distributions:

```bash
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.
