Configuration¶

Aniwa supports reusable configuration files for simplifying profiling workflows.

Configuration files allow teams and developers to define default profiling behavior without repeatedly passing CLI arguments.

This improves:

reproducibility
developer experience
automation
CI/CD workflows
consistency across teams

Supported Configuration Formats¶

Aniwa currently supports:

YAML
TOML
JSON

Supported filenames:

aniwa.yaml
aniwa.yml
aniwa.toml
aniwa.json

Automatic Configuration Discovery¶

Aniwa automatically searches the current working directory for configuration files.

Example:

aniwa examples/customers.csv

If a supported config file exists, Aniwa automatically loads it.

Configuration Priority¶

Aniwa resolves configuration using the following priority order:

CLI arguments > Config file > Defaults

This means command-line arguments always override configuration values.

YAML Example¶

aniwa.yaml

mode: deep

report:
  format: html
  template: dark
  output_dir: reports/

sections:
  include:
    - summary
    - statistics
    - insights

TOML Example¶

aniwa.toml

mode = "deep"

[report]
format = "html"
template = "dark"
output_dir = "reports/"

[sections]
include = ["summary", "statistics", "insights"]

JSON Example¶

aniwa.json

{
  "mode": "deep",
  "report": {
    "format": "html",
    "template": "dark",
    "output_dir": "reports/"
  },
  "sections": {
    "include": [
      "summary",
      "statistics",
      "insights"
    ]
  }
}

Using Custom Config Files¶

You can specify a custom config file using:

aniwa examples/customers.csv \
  --config examples/config_sample.yaml

This is useful for:

multiple environments
reusable presets
testing workflows
CI pipelines

Supported Configuration Fields¶

Profiling Mode¶

mode: deep

Supported values:

fast
deep

Report Format¶

report:
  format: html

Supported values:

console
json
html
excel
markdown
pdf

Report Template¶

report:
  template: dark

Supported values:

default
clean
compact
enterprise
dark

Output Directory¶

report:
  output_dir: reports/

Aniwa automatically:

creates directories
generates filenames
applies extensions

Included Sections¶

sections:
  include:
    - summary
    - statistics

Excluded Sections¶

sections:
  exclude:
    - charts

CLI Override Examples¶

Override Mode¶

Config:

mode: deep

CLI:

aniwa dataset.csv --mode fast

Result:

fast mode is used

Override Template¶

Config:

report:
  template: dark

CLI:

aniwa dataset.csv --template enterprise

Result:

enterprise template is used

Internal Configuration Flow¶

Aniwa internally performs:

config discovery
config parsing
validation
flattening
merging with CLI arguments
final runtime resolution

Configuration Architecture¶

Configuration handling is primarily implemented in:

aniwa/config.py
aniwa/config_loader.py
aniwa/cli.py

Responsibilities:

config_loader.py¶

Responsible for:

reading YAML
reading TOML
reading JSON
parsing config structures
flattening nested config values

cli.py¶

Responsible for:

discovering config files
loading configs
merging CLI overrides
validating runtime configuration

Config Validation¶

Aniwa validates:

report format
profiling mode
report sections
template names

Invalid configs raise helpful errors.

Example:

Invalid mode in config: ultra

Missing Config Files¶

Missing config files do not crash Aniwa.

Example:

Warning: Configuration file not found.
Using defaults.

Recommended Workflow¶

Recommended project setup:

project/
├── datasets/
├── reports/
├── aniwa.yaml

Example:

mode: deep

report:
  format: html
  template: enterprise
  output_dir: reports/

Then simply run:

aniwa datasets/customers.csv

CI/CD Example¶

Example GitHub Actions workflow:

- name: Run Aniwa
  run: |
    aniwa datasets/customers.csv

Since config is auto-discovered, workflows remain clean and reproducible.

Future Configuration Roadmap¶

Future planned features include:

environment configs
user-level configs
global configs
remote configs
validation schemas
project presets
profile inheritance
encrypted configs
plugin configs

Design Philosophy¶

Aniwa configuration is designed to be:

lightweight
explicit
reproducible
automation-friendly
developer-first

Best Practices¶

Recommended practices:

commit config files to repositories
standardize team presets
separate environment configs
use CLI overrides sparingly
keep configs minimal and readable

Next Steps¶

Continue with:

examples.md
cli-reference.md
report-formats.md
profiling-modes.md