PrivacyForms AI

A Python CLI tool for interacting with Large Language Models (LLMs) via Simon Willison's llm library. Supports multiple providers including OpenAI, Anthropic, Moonshot, and Ollama.

Features

• 🔧 Simple CLI - Easy-to-use command-line interface with colored output
• 💬 Interactive Chat - Multi-turn conversations with context/memory
• 🚀 Multiple Providers - Works with OpenAI, Anthropic, Moonshot, Ollama, and more
• 🧪 Well Tested - Comprehensive test coverage
• ⚡ Fast - Built with modern Python tooling
• 🔍 Observable - Optional verbose logging (-v / -vv) to inspect prompt payloads

Installation

Using uv (recommended)

# Clone the repository
git clone https://github.com/zopyx/privacyforms.ai.git
cd privacyforms.ai

# Install with uv
uv sync

# Or install in development mode
uv sync --all-extras --dev

Using pip

pip install privacyforms-ai

Configuration

Set your API keys as environment variables:

# OpenAI
export OPENAI_API_KEY="your-key"

# Anthropic
export ANTHROPIC_API_KEY="your-key"

# Moonshot
export MOONSHOT_API_KEY="your-key"

For Ollama, make sure the Ollama server is running locally.

Usage

Global Options

# Show version
privacyforms-ai --version

# Show help
privacyforms-ai --help

# Enable verbose output (shows prompt logs on stderr)
privacyforms-ai -v models

# Enable debug output
privacyforms-ai -vv prompt gpt-4o-mini "Hello!"

List Available Models

privacyforms-ai models

# JSON output
privacyforms-ai models --json-output

Send a Single Prompt

# Basic prompt
privacyforms-ai prompt gpt-4o-mini "What is the capital of France?"

# With system prompt
privacyforms-ai prompt gpt-4o-mini "Explain recursion" --system "You are a computer science tutor"

Interactive Chat

Start an interactive chat session with conversation history:

# Basic chat
privacyforms-ai chat moonshot/kimi-k2.5

# With system prompt
privacyforms-ai chat gpt-4o-mini -s "You are a helpful coding assistant"

Chat Commands:

• /quit, /exit, /q - End the chat session
• /clear - Clear conversation history
• /model - Show current model

Example session:

Starting chat with model: moonshot/kimi-k2.5
Type /quit, /exit, or /q to end the session. Type /clear to reset history.
--------------------------------------------------

You: Hello!

AI: Hello! How can I help you today?

You: What can you do?

AI: I can help with a variety of tasks including...

You: /quit

Goodbye!

Development

Setup

# Clone and setup
git clone https://github.com/zopyx/privacyforms.ai.git
cd privacyforms.ai
uv sync --all-extras --dev
source .venv/bin/activate

Running Tests

# Run all tests
make test

# With coverage
make test-cov

# Verbose output
uv run pytest -v

Code Quality

# Format code
make format

# Check formatting
make format-check

# Lint
make lint

# Auto-fix linting issues
make fix

# Type check
make type-check

# Run the full local gate
make check

Build Package

# Build release artifacts into dist/
make dist

Upload Package

# Upload to PyPI using twine and your ~/.pypirc or TWINE_* credentials
make upload

# Upload to another configured repository, e.g. TestPyPI
make upload TWINE_REPOSITORY=testpypi

Create a Release

# 1. Update the version in pyproject.toml, src/privacyforms_ai/_version.py, README, and tests

# 2. Refresh the lockfile if needed
uv sync --all-extras --dev

# 3. Verify and build
make check
make dist

# 4. Upload
make upload

# 5. Commit and tag
git add pyproject.toml src/privacyforms_ai/_version.py src/privacyforms_ai/__init__.py tests/ uv.lock CHANGELOG.md .gitattributes LICENSE
git commit -m "Release X.Y.Z"
git tag vX.Y.Z
git push origin HEAD
git push origin vX.Y.Z

API Design

See API_DESIGN.md for the REST API and WebSocket design specification for multi-chat server functionality.

Project Structure

privacyforms.ai/
├── src/privacyforms_ai/
│   ├── __init__.py
│   ├── _version.py        # Package version
│   ├── ai.py              # AI class for LLM interactions
│   └── cli.py             # Click CLI commands
├── tests/
│   ├── conftest.py        # Pytest fixtures
│   ├── test_ai.py         # AI class tests
│   └── test_cli.py        # CLI tests
├── pyproject.toml         # Project configuration
├── uv.lock               # Locked dependencies
├── CHANGELOG.md          # Release notes
├── LICENSE               # MIT license
├── .gitattributes        # Line-ending configuration
└── README.md

CI/CD

GitHub Actions workflow runs on:

• Python 3.12, 3.13, 3.14, 3.14t (free-threaded)
• Ubuntu Linux

Jobs:

• test - Run pytest with coverage
• lint - ruff (formatting, linting) and ty (type checking)
• build - Build package artifacts and validate with twine

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all checks pass (make check)
5. Submit a pull request

Acknowledgments

• Built on top of Simon Willison's llm library
• Uses Astral's uv for fast Python package management