Files
fiona-assistant/src

Fiona Assistant

A collection of tools for managing the LLM wiki and related operations.

Overview

The Fiona Assistant project provides command-line tools for:

  • Librarian: Managing LLM wiki content and operations
  • MDoctor: Markdown diagnosis (lint, list, and fix)

Installation

Development Setup

  1. Clone the repository:

    git clone <repository-url>
    cd fiona-assistant
    
  2. Set up the Python environment using the bootstrap script.

    Linux / macOS:

    source bootstrap --env fiona_env
    

    Or with a specific Python version:

    source bootstrap --env fiona_env --python 3.11.0
    

    Windows (PowerShell):

    Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
    . .\bootstrap.ps1 --env fiona_env --python 3.11.0
    

    Install this checkout as a normal package with --local. Skip the virtual environment with --no-env (PowerShell may use -File instead of dot-sourcing):

    powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env
    
  3. Install the package in development mode:

    pip install -e .
    

Install with Development Dependencies

pip install -e ".[dev]"

Usage

Librarian

See librarian/README.md for detailed usage.

librarian --help

MDoctor

See mdoctor/README.md for detailed usage.

mdoctor --help

Project Structure

src/fiona/
├── __main__.py       # CLI entry point
├── librarian/        # Wiki content management
├── mdoctor/          # Markdown diagnosis
├── customlinter/     # Frontmatter, markdown, Python, and JSON linters
├── python_ruff/      # Ruff wrapper
├── gittool/          # Git operations
├── sanity_runner/    # Shared sanity engine
├── wiki/             # Wiki init, update, sanity, and graph
├── data/llm_wiki/    # Packaged wiki template
├── run_tests.py      # Test runner
└── run_sanity.py     # Sanity runner
tests/                # Unit tests (repository root, not installed)
scripts/
├── run_tests.py
├── run_sanity.py
├── settings_dev.json
├── utils.sh
└── install_packages.sh

Running Tests

# Run all tests
python scripts/run_tests.py

# Or use pytest directly
python -m pytest

# Run with coverage
python -m pytest --cov=src/fiona

Development Tools

The project includes several development utilities:

  • bootstrap: Set up the Python development environment (bash)
  • bootstrap.ps1: Set up the Python development environment (PowerShell)
  • scripts/utils.sh: Shell utility functions
  • scripts/install_packages.sh: Install local Python packages
  • scripts/run_tests.py: Run the test suite
  • scripts/run_sanity.py: Run tests and linters

License

GPL-3.0-only

Contributing

Follow AGENTS.md: update SPEC.md first, add a failing test, then implement. Run python scripts/run_tests.py and python scripts/run_sanity.py --non-interactive before finishing.