Metadata-Version: 2.4
Name: aidecl
Version: 0.3.0
Summary: Validate AI Declaration (aidecl) files
Author-email: Faruk Diblen <faruk.diblen@resoftlabs.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/ai-declaration/cli
Project-URL: Repository, https://github.com/ai-declaration/cli
Project-URL: Bug Tracker, https://github.com/ai-declaration/cli/issues
Project-URL: Documentation, https://github.com/ai-declaration/cli#readme
Keywords: ai,disclosure,validation,compliance,transparency
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: jsonschema>=4.23
Requires-Dist: referencing>=0.35
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# aidecl

Command-line tool for validating, converting, and creating AI Declaration (aidecl) files.

AI Declaration files describe how AI tools were used in the creation of software, datasets, documents, and other digital work. This CLI validates them against the [schema](https://github.com/ai-declaration/schema) with both structural (JSON Schema) and semantic checks.

## Installation

```bash
pip install aidecl
```

For development:

```bash
git clone https://github.com/ai-declaration/cli.git
cd cli
pip install -e ".[dev]"
```

## Quick Start

```bash
# Create a new declaration file
aidecl init --format yaml

# Edit aidecl.yaml with your project details

# Validate it
aidecl validate aidecl.yaml
```

## Usage

### validate

Check one or more declaration files against the schema:

```bash
aidecl validate aidecl.yaml
aidecl validate aidecl.json another.yaml
aidecl validate --verbose aidecl.yaml
aidecl validate --output-format json aidecl.yaml
aidecl validate --strict aidecl.yaml  # warnings become errors
aidecl validate --quiet aidecl.yaml    # only exit code, no output
```

Sample output:

```
PASS [yaml]: aidecl.yaml
```

```
FAIL [yaml]: aidecl.yaml
    Schema error at 'ai_usage.level': 'high' is not valid. Allowed values: 'none', 'minimal', 'moderate', 'significant', 'extensive'
```

### convert

Convert between YAML and JSON:

```bash
aidecl convert aidecl.yaml -f json
aidecl convert aidecl.json -f yaml -o output.yaml
```

### init

Create a template declaration file:

```bash
aidecl init
aidecl init --format json
aidecl init --output my-project.yaml
```

The init command auto-detects your project name and git config for sensible defaults.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All files valid |
| 1 | Semantic errors found |
| 2 | Schema validation errors |
| 3 | File errors (not found, binary, too large) |

## Output Formats

**text** (default): Human-readable colored output.

**json**: Machine-readable output per file:
```json
{
  "file": "aidecl.yaml",
  "passed": true,
  "schema_errors": [],
  "semantic_errors": [],
  "warnings": ["declaration date is in the future: 2099-01-01"]
}
```

**github-actions**: Annotation format for CI:
```
::error file=aidecl.yaml::used is false but tools are listed
::warning file=aidecl.yaml::declaration date is in the future
```

## Validation Rules

### Schema checks

Validates structure against JSON Schema Draft 2020-12: required fields, types, enum values, string formats, conditional requirements (e.g. `summary` required when `used: true`).

### Semantic checks

| # | Level | Rule |
|---|-------|------|
| 1 | warn | AI usage declared but no tools listed |
| 2 | error | `used: false` but tools present |
| 3 | error | `used: false` but level is not `none` |
| 4 | warn | `code_proportion` percentages don't sum to ~100 |
| 5 | warn | Declaration date is in the future |
| 6 | warn | Review date is after declaration date |
| 7 | warn | Security review performed but no review type |
| 8 | warn | Personal data sent without DPA |
| 9 | warn | Level is `extensive` but no proportion data |
| 10 | warn | Component references tool not in tools list |
| 11 | warn | Schema version newer than supported |
| 12 | error | Tool period end before start |
| 13 | warn | Tool trains on data but no data handling section |
| 14 | warn | Next review date is in the past |

## Integration

### GitHub Actions

```yaml
- name: Validate AI Declaration Format
  run: |
    pip install aidecl
    aidecl validate --output-format github-actions aidecl.yaml
```

### Pre-commit framework

Add to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/ai-declaration/cli
    rev: v0.1.0
    hooks:
      - id: aidecl
```

### Git pre-commit hook

```bash
#!/bin/sh
aidecl validate aidecl.yaml --quiet
```

## Related Standards

| Standard | Relationship |
|----------|-------------|
| codemeta.json | Project metadata; aidecl adds AI transparency |
| CITATION.cff | Citation metadata; complementary |
| SPDX 3.0 AI Profile | License + AI BOM; aidecl is lighter for declarations |
| CycloneDX ML-BOM | ML component inventory; different scope |
| C2PA | Content authenticity; media-focused |
| W3C PROV | Provenance ontology; aidecl JSON-LD maps to PROV-O |

## Related Projects

- [schema](https://github.com/ai-declaration/schema): schema definition and examples
- [web](https://github.com/ai-declaration/web): web-based generator and validator

## Shell Completions

Bash:
```bash
eval "$(register-python-argcomplete aidecl)"
```

Or add to your `.bashrc` for persistent completions.

Fish and Zsh: use `argcomplete` or generate completions manually from the `--help` output.

## Privacy Note

The `declared_by` field identifies who made the declaration. For public repositories, consider using team names or roles instead of individual names.

## Compatibility

| aidecl version | Supported schema versions |
|------------------------|--------------------------|
| 0.1.x | 1.0.0 |

## Development

```bash
pip install -e ".[dev]"
pytest
pytest --cov
```

## License

Apache-2.0. The bundled `schema.json` is from [schema](https://github.com/ai-declaration/schema) (CC BY-SA 4.0).
