nvaldez 4365f291ae test: add comprehensive tests for wiki/graph_generator.py to achieve 100% coverage
Added tests for all uncovered code paths in graph_generator.py:
- TestLoadGraphSettings: tests for loading settings from fiona-settings.json
- MarkdownLinkParser: tests for fragment handling, wikilinks, external URLs,
  file parsing error handling, and link validation
- WikiGraphMain: tests for directory validation, settings override, output
  directory creation, file writability checks, max_files limit, overwrite
  behavior, and exception handling

This increases coverage from 85% to 100% for wiki/graph_generator.py (315/315 statements).

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-09-28 21:32:46 +02:00
2026-09-27 20:08:55 +02:00
2026-09-28 10:47:07 +02:00
2026-09-27 20:08:55 +02:00

Fiona-Assistant

LLM Wiki Tool Helper for LLM Agents/Hives

Fiona-Assistant is a command-line toolkit designed to manage, organize, and maintain LLM wiki content with minimal AI token dependence. It combines script-based automation with structured workflows to help LLM Agents and Hives efficiently manage documentation, markdown files, and code quality.


Overview

Purpose

Fiona-Assistant serves as a standalone MD/scripts/docs organizer and LLM wiki management helper that:

  • Reduces AI Token Usage: Uses deterministic scripts and tools to handle wiki management tasks that don't require LLM intelligence
  • Maintains Wiki Structure: Enforces consistent organization of markdown files, concepts, and raw source materials
  • Validates Content Quality: Provides linting and diagnosis tools for markdown and Python code
  • Enables Script-Based Workflows: Automates repetitive wiki maintenance tasks through CLI commands

Core Philosophy

Use scripts for deterministic tasks, reserve AI tokens for creative and analytical work

The toolkit is designed to be AI-friendly - outputs are formatted in consistent, parseable structures that LLMs can easily read and process.


Features

Tool Suite

Tool Purpose Key Capabilities
Librarian Wiki content management List files, scan directories, organize MD content
MDoctor Markdown diagnosis Lint markdown files using PyMarkdown, detect formatting issues
Python-Ruff Code quality Lint Python files using Ruff, enforce code standards
Generate-TOC Table of contents Auto-generate nested TOC from markdown headers

Wiki Structure Support

Fiona-Assistant understands and maintains the LLM Wiki directory structure:

llm-wiki/
├── ingest/          # Input zone: files to be processed
├── raw/             # Archived source materials (read-only)
│   ├── articles/
│   ├── papers/
│   ├── transcripts/
│   └── assets/
├── wiki/            # Processed content
│   └── concepts/    # Synthesized concept notes
├── personal/        # User notes (read-only for agents)
└── utils/           # Utility scripts

Installation

Quick Install (Production)

python -m pip install fiona-assistant

Development Setup

  • Clone the repository:

    git clone <repository-url>
    cd fiona-assistant
    
  • Create and activate the virtual environment:

  source bootstrap --env fiona_env -c

Make sure fiona_env is activated as pyenv before proceeding


Usage

Main CLI

Fiona-Assistant provides a unified CLI with multiple subcommands:

# Show all available commands
fiona-assistant --help

# Run via Python module
python -m fiona --help

Available Commands

# Run tests
fiona-assistant test

# Manage wiki content with Librarian
fiona-assistant librarian [directory]

# Generate an in-file table of contents below the H1
fiona-assistant librarian toc file <path_to_file>

# Force section numbering on for the run
fiona-assistant librarian toc file <path_to_file> --sectionized

# Generate in-file TOCs for every md file in the current directory / wiki root
fiona-assistant librarian toc file '*'

# Diagnose markdown files with MDoctor
fiona-assistant mdoctor [chklint] [directory]

# Lint Python code with Ruff
fiona-assistant python-ruff [chklint] [directory]

Direct Tool Access

Each tool can also be called directly:

# Librarian - List all files in a directory
librarian [directory]

# MDoctor - Check markdown lint violations
mdoctor chklint [directory]

# MDoctor - List all files

# Python-Ruff - Check Python code quality
python-ruff chklint [directory]

# Generate table of contents for markdown files
generate-toc [directory] [options]

Workflow Examples

Wiki Ingestion Workflow

# 1. Drop raw files into ingest directory
# (Manual or automated process)

# 2. List files ready for processing
librarian llm-wiki/ingest

# 3. Validate markdown quality before processing
mdoctor chklint llm-wiki/ingest

# 4. Move processed files to raw archive
# (Agent/orchestration task)

Content Maintenance Workflow

# Check all markdown files in wiki for lint violations
mdoctor chklint llm-wiki/wiki

# Generate table of contents for concept notes
generate-toc llm-wiki/wiki/concepts --recursive-toc

# Validate Python code in the project
python-ruff chklint src/

# List all markdown files for inventory
librarian llm-wiki/

Standalone Document Organization

# Organize any directory of markdown files
librarian /path/to/docs/

# Validate markdown formatting
mdoctor chklint /path/to/docs/

# Create nested table of contents
generate-toc /path/to/docs/ --recursive-toc

Output Format

All tools produce AI-friendly output with consistent formatting:

MDoctor Output Format

PyMarkdownLint Violations
TARGET: /path/to/directory

- DEFINITIONS:
  - md001: Heading levels should only increment by one, Heading levels should only increment by one level at a time
  - md013: Line length, Line length

- FILE: file1.md
  - 10:5 md013
  - 20:3 md001

- SUMMARY:
  - Total files with violations: 1
  - Total violations: 2

Python-Ruff Output Format

Ruff Violations
TARGET: /path/to/directory

Definitions:
  - F401: `*` import used, but not imported
  - E501: Line too long

- FILE: script.py
  - 15:10 F401
  - 25:80 E501

- SUMMARY:
  - Total files with violations: 1
  - Total violations: 2

Project Structure

fiona-assistant/
├── llm-wiki/                  # Wiki content and structure definition
│   ├── AGENTS.md              # Agent rules and directory permissions
│   ├── ingest/                # Input zone for new content
│   ├── raw/                   # Archived source materials
│   ├── wiki/                  # Processed concept notes
│   └── utils/                 # Utility scripts
│
├── src/
│   ├── fiona/                 # Main CLI entry point
│   │   └── __main__.py        # Unified command dispatcher
│   │
│   ├── librarian/             # Wiki content management
│   │   ├── __init__.py
│   │   ├── librarian.py       # File scanning and listing
│   │   └── toc_generator.py    # Table of contents generator
│   │
│   ├── mdoctor/               # Markdown diagnosis
│   │   ├── __init__.py
│   │   └── mdoctor.py         # PyMarkdown lint wrapper
│   │
│   ├── python_ruff/           # Python code linting
│   │   ├── __init__.py
│   │   └── python_ruff.py     # Ruff lint wrapper
│   │
│   ├── tests/                 # Unit tests
│   │   ├── test_fiona_main.py
│   │   ├── test_librarian.py
│   │   ├── test_mdoctor.py
│   │   └── test_python_ruff.py
│   │
│   ├── run_tests.py           # Test runner
│   └── README.md              # Development documentation
│
├── pyproject.toml             # Project configuration
├── bootstrap                  # Environment setup script
├── LICENSE                    # GPL-3.0-only
└── README.md                  # This file

Testing

Run Tests

# Run all tests
python src/run_tests.py

# Or use pytest directly
python -m pytest

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

License

GPL-3.0-only


Key Concepts

For LLM Agents

  • Deterministic Operations: Use Fiona-Assistant for file listing, linting, and organization
  • Token Efficiency: Reserve LLM context for synthesis, analysis, and creative tasks
  • Structured Output: All tool outputs are formatted for easy parsing by LLMs

For Human Users

  • CLI-First: All functionality available through command-line interface
  • Composable Tools: Combine tools in scripts for automated workflows
  • Clear Structure: Maintains consistent wiki organization standards


Quick Reference Card

Task Command
Show help fiona-assistant --help
List files fiona-assistant librarian /path/to/dir
Check MD lint fiona-assistant mdoctor chklint /path/to/dir
Check Python lint fiona-assistant python-ruff chklint /path/to/dir
Generate TOC generate-toc /path/to/dir --recursive-toc
Generate file TOC fiona-assistant librarian toc file /path/to/file.md --sectionized
Run tests python src/run_tests.py
Install pip install fiona-assistant
Dev install pip install -e .

Note

: All paths are relative to the current working directory unless specified as absolute paths.

S
Description
Template for starting an LLM-Wiki
Readme 7.4 MiB
Languages
Python 90.5%
JavaScript 5.6%
Shell 1.6%
HTML 1.5%
PowerShell 0.8%