Metadata-Version: 2.4
Name: fairguard
Version: 0.10.0
Summary: FAIR4RS compliance checker for research software
License: AGPL-3.0-only WITH Commons-Clause-exception-1.0
Project-URL: Homepage, https://github.com/resoft-labs/FAIRGuard
Project-URL: Source, https://github.com/resoft-labs/FAIRGuard
Project-URL: Issues, https://github.com/resoft-labs/FAIRGuard/issues
Project-URL: Changelog, https://github.com/resoft-labs/FAIRGuard/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
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: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.11,<3.14
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: typer<1,>=0.12
Requires-Dist: rich<15,>=13.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: jinja2<4,>=3.1
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FAIRGuard

[![PyPI](https://img.shields.io/pypi/v/fairguard)](https://pypi.org/project/fairguard/)
[![Python](https://img.shields.io/pypi/pyversions/fairguard)](https://pypi.org/project/fairguard/)
[![CI](https://github.com/resoft-labs/FAIRGuard/actions/workflows/ci.yml/badge.svg)](https://github.com/resoft-labs/FAIRGuard/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

FAIR4RS compliance checker for research software.

Checks your software project against the 17 FAIR4RS principles (Findable, Accessible, Interoperable, Reusable) and gives you a compliance score.

Work in progress.

## How it works

FAIRGuard uses a plugin system to check each FAIR4RS principle. Built-in plugins cover all 17 principles:

- **Findable**: persistent identifiers, metadata, searchability
- **Accessible**: retrieval protocols, access documentation
- **Interoperable**: standard data formats, qualified references
- **Reusable**: license, provenance, community standards

## Install

```
pip install fairguard
```

For development:

```
pip install -e ".[dev]"
```

## Usage

### Basic assessment

```bash
# assess the current directory
fairguard assess

# assess a specific repository
fairguard assess /path/to/repo

# assess a remote repository
fairguard assess https://github.com/org/repo

# shorthand for GitHub repos
fairguard assess org/repo

# Codeberg / Gitea / Forgejo repos work the same way
fairguard assess https://codeberg.org/owner/repo

# verbose output with evidence details
fairguard assess . -v

# quiet mode (exit code only, no output)
fairguard assess . -q
```

### Forge support

| Forge | Token env var | CLI flag | Notes |
|---|---|---|---|
| GitHub | `GITHUB_TOKEN` or `GH_TOKEN` | `--github-token` | github.com and self-hosted GHE |
| GitLab | `GITLAB_TOKEN` | `--gitlab-token` | gitlab.com and self-hosted (set `GITLAB_URL`) |
| Codeberg | `CODEBERG_TOKEN` | `--gitea-token` | codeberg.org |
| Gitea / Forgejo | `GITEA_TOKEN` | `--gitea-token` | self-hosted (set `GITEA_URL` if needed) |

Tokens are only required for higher rate limits or to read private repositories.
Public repos on any supported forge can be assessed anonymously.

### Output formats

FAIRGuard supports three output formats: `text` (default), `json`, and `markdown`.

```bash
# print json to terminal
fairguard assess . --format json

# print markdown to terminal
fairguard assess . --format markdown
```

### Saving reports to file

Use `--output` (`-o`) to write the report to a file. The format is determined by `--format`:

```bash
# save as markdown
fairguard assess . --format markdown --output report.md

# save as json
fairguard assess . --format json --output results.json

# save as plain text
fairguard assess . --output report.txt
```

If you pass a directory instead of a file, FAIRGuard auto-names the file:

```bash
# creates ./reports/fairguard-report.md
fairguard assess . --format markdown --output ./reports/
```

### Publishing to a FAIRGuard backend

One-step assess + upload, no JSON file in between:

```bash
export FAIRGUARD_BACKEND_URL=https://fairguard.example.org
export FAIRGUARD_API_KEY=fg_xxxxxxxxxxxxxxxx

fairguard assess . --publish
```

The two-step flow still works if you need the JSON for something else:

```bash
fairguard assess . --format json --output report.json
fairguard publish report.json
```

`fairguard publish -` reads JSON from stdin, so this also works:

```bash
fairguard assess . --format json | fairguard publish -
```

Resolution order for `--backend-url` and `--api-key`: CLI flag, then
`FAIRGUARD_BACKEND_URL` / `FAIRGUARD_API_KEY` env vars, then `backend_url`
and `api_key` in `.fairguard.yml`, then default `http://localhost:8000`.
Avoid committing `api_key` to the config file -- the CLI warns when it
loads one from disk.

### Profiles

```bash
# use a specific profile
fairguard assess . --profile minimal

# list available profiles
fairguard profile list

# show profile details
fairguard profile show strict
```

### Skip indicators

```bash
# skip an indicator
fairguard assess . --skip persistent_identifier

# skip with a reason
fairguard assess . --skip "persistent_identifier:no DOI yet"

# skip multiple
fairguard assess . --skip persistent_identifier --skip metadata_persistence
```

### Other commands

```bash
# list plugins and their indicators
fairguard plugin list
fairguard plugin info license_check

# list FAIR4RS indicators
fairguard indicator list
fairguard indicator list -v             # with descriptions
fairguard indicator list --unimplemented

# initialize a config file
fairguard init

# validate config
fairguard validate

# check plugin dependencies
fairguard deps
```

### Exit codes

| Code | Meaning |
|------|---------|
| 0    | All indicators pass |
| 1    | One or more indicators failed |
| 2    | Error or quality gate failed |

## Configuration

FAIRGuard looks for a `.fairguard.yml` file in the repository root (or any parent directory). You can also pass a config file explicitly with `--config`. Run `fairguard init` to create one.

Example `.fairguard.yml`:

```yaml
profile: default
skip_indicators:
  - metadata_persistence

quality_gate:
  min_compliance: bronze
  min_score: 4.0
  required_indicators:
    - clear_license

quality_goals:
  target_compliance: gold
  target_score: 7.0
```

### Profiles

Three built-in profiles are available:

- **default** -- all 17 indicators, threshold 5.0
- **minimal** -- only the 4 Bronze-essential indicators (persistent_identifier, clear_license, open_access_protocol, community_standards)
- **strict** -- all 17 indicators at Platinum threshold (8.0)

Select a profile via `--profile` flag or the `profile` key in `.fairguard.yml`.

### Quality Gates

Quality gates enforce minimum requirements. The assessment will report PASSED or FAILED:

- `min_compliance`: minimum compliance level (none/bronze/silver/gold/platinum)
- `min_score`: minimum overall score
- `required_indicators`: list of indicators that must pass

### Quality Goals

Quality goals are aspirational targets for tracking progress. They are non-blocking -- the assessment always completes, but shows whether each goal is met.

## Extra Features

For detailed HTML reports, assessment trends, team dashboards, batch/organization scanning, and more, visit [fairguard.io](https://fairguard.io).

## License

AGPL-3.0 with Commons Clause
