solid-cli 1.1.0
A small SOLID-inspired CLI framework for easily adding commands.
Requires Python: >=3.9

# solid-cli `v1.1.0`

A **SOLID-inspired** Python CLI toolkit for autonomous research,
multimodal AI review (text / image / video / audio), and self-organising
knowledge management. Built the way Uncle Bob would build it.

## Quick Start

```bash
# Install in editable mode
python -m pip install -e .

# See all commands
python -m solid_cli --help

# Check version
solid-cli --version

# Agent onboarding — comprehensive guide for humans and AI agents
python -m solid_cli onboard
python -m solid_cli onboard --json   # machine-readable for agents
```

## Commands

| Command    | What it does                                                    |
| ---------- | --------------------------------------------------------------- |
| `research` | Web-search via OpenAI → Markdown report in `knowledge_base/`    |
| `review`   | Upload file or text to Gemini → quality feedback in `feedback/` |
| `download` | Fetch sample image/video/audio for testing into `samples/`      |
| `read`     | Display a saved knowledge-base document                         |
| `onboard`  | Full help guide for humans and AI agents                        |
| `hello`    | Greeting example (`--name Alice`)                               |
| `sum`      | Sum integers example (`sum 1 2 3`)                              |

### research — autonomous web search

```bash
solid-cli research "OpenAI Responses API best practices 2025" --tag openai_api
solid-cli research --list              # catalogue
solid-cli research --search apple      # filter by keyword
solid-cli research --batch queries.txt # bulk from file (tag|query format)
solid-cli research --stats             # aggregate library stats
solid-cli research --delete 3          # remove document #3
solid-cli research "topic" --force     # save even with 0 sources
solid-cli read 1                       # display document #1
```

Queries that return **0 sources** are **skipped** by default to keep the
library clean. Use `--force` to override.

### review — multimodal Gemini quality review

```bash
solid-cli review photo.png "Check composition and quality"
solid-cli review clip.mp4  "Summarise content, assess quality"
solid-cli review song.wav  "Transcribe and assess audio quality"
solid-cli review code.py   "Code review for SOLID adherence"
solid-cli review --text "Some text with erors" "Check spelling"
solid-cli review --list              # catalogue
solid-cli review --read 1            # display feedback #1
```

### download — fetch test assets

```bash
solid-cli download all               # image + video + audio
solid-cli download --url URL --name my_file.png
solid-cli download --list
```

### Environment variables

| Variable         | Purpose                                                        |
| ---------------- | -------------------------------------------------------------- |
| `OPENAI_API_KEY` | Required for `research` (web search via OpenAI)                |
| `GEMINI_API_KEY` | Required for `review` (multimodal AI via Gemini)               |
| `KB_DIR`         | Override knowledge-base directory (default `./knowledge_base`) |
| `FEEDBACK_DIR`   | Override feedback directory (default `./feedback`)             |

Place these in a `.env` file — `python-dotenv` loads it automatically.

## Architecture (SOLID + Clean)

```
solid_cli/
├── command.py              ← Abstract Command interface (DIP)
├── registry.py             ← Auto-discovers commands (OCP)
├── cli.py / __main__.py    ← Thin entry points
├── services/
│   ├── search_service.py   ← SearchService ABC + OpenAI impl (SRP, LSP)
│   ├── review_service.py   ← ReviewService ABC + Gemini impl (SRP, LSP)
│   ├── storage_service.py  ← KnowledgeBaseStorage (SRP)
│   └── feedback_storage.py ← FeedbackStorage (SRP)
└── commands/
    ├── research.py         ← Web-search → knowledge_base/
    ├── review.py           ← Gemini multimodal → feedback/
    ├── download.py         ← Fetch test media → samples/
    ├── read.py             ← KB reader
    ├── onboard.py          ← Agent/human help system
    ├── hello.py            ← Example
    └── sum.py              ← Example
```

### Output directories

```
knowledge_base/             ← research output
    index.json
    <date>/<topic>.md

feedback/                   ← Gemini review output
    index.json
    <date>/
        images/ video/ audio/ text/ documents/
            <review>.md

samples/                    ← downloaded test assets
```

### Adding a new command

1. Create `solid_cli/commands/my_cmd.py`
2. Subclass `Command` and implement `name`, `add_arguments`, `run`
3. Done — the registry auto-discovers it, no wiring needed

External packages can also register commands via the `solid_cli.commands`
entry-point group in their own `pyproject.toml`.