Metadata-Version: 2.4
Name: fiona-assistant
Version: 0.40.5
Summary: Tools for managing the LLM wiki.
Author: nvaldeziii
License-Expression: GPL-3.0-only
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymarkdownlnt>=0.9.0
Requires-Dist: ruff>=0.16.8
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: pylint
Requires-Dist: GitPython>=3.1.0
Requires-Dist: html5validator>=0.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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/AGENTS.md):

```text
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)

```bash
python -m pip install fiona-assistant
```

### Development Setup

- **Clone the repository:**

   ```bash
   git clone <repository-url>
   cd fiona-assistant
   ```

- **Create and activate the virtual environment:**

   Linux / macOS:

   ```bash
   source bootstrap --env fiona_env -c
   ```

   Windows (PowerShell):

   ```powershell
   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   . .\bootstrap.ps1 --env fiona_env -c
   ```

   > Make sure `fiona_env` is activated before proceeding. On Windows the
   > environment lives in `.venvs\fiona_env`.

---

## Usage

### Main CLI

Fiona-Assistant provides a unified CLI with multiple subcommands:

```bash
# Show all available commands
fiona-assistant --help

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

#### Available Commands

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```text
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

```text
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

```text
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 (bash)
├── bootstrap.ps1              # Environment setup script (PowerShell)
├── LICENSE                    # GPL-3.0-only
└── README.md                  # This file
```

---

## Testing

### Run Tests

```bash
# 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

---

## Related Documentation

- [LLM Wiki Agent Rules](./llm-wiki/AGENTS.md) - Directory permissions and workflow rules
- [Development Setup](./src/README.md) - Detailed development information
- [Project Specification](./SPEC.md) - Feature spec sheet with requirements and acceptance criteria
- [Project TODO](./todo.md) - Roadmap and planned features

---

## 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.
