qt-llm-template

PySide6 LLM Template Repository

This directory contains documentation for creating a PySide6 Qt GUI template repository optimized for LLM coding agents (Claude, GPT-4, etc.).

Goals

1. Fast Scaffolding: Enable LLM agents to quickly create new PySide6 desktop apps
2. Clean Architecture: Provide well-defined patterns that LLMs can follow consistently
3. LLM-Friendly APIs: Design interfaces that are easy for LLMs to understand and use correctly
4. Testing Support: Built-in testing infrastructure including MCP-based E2E testing
5. VSCode-Style UX: Modern IDE-like interface patterns out of the box

Documentation Index

Key Principles

1. Explicit Over Implicit

LLMs work better with explicit, well-documented patterns than implicit conventions they need to infer.

2. Declarative Configuration

Use declarative config (Pydantic models, dataclasses) over imperative setup code.

3. Single Source of Truth

One place for each concern - no scattered configuration.

4. Progressive Disclosure

Simple things should be simple; complex things should be possible.

5. Testability First

Every component should be testable in isolation.

Template Structure (Proposed)

pyside6-llm-template/
├── app/
│   ├── __init__.py
│   ├── main.py                    # Entry point
│   ├── main_window.py             # Main window
│   ├── config.py                  # App configuration (Pydantic)
│   ├── theme.py                   # Theming system
│   ├── core/
│   │   ├── di.py                  # Dependency injection
│   │   ├── events.py              # Event bus + event types
│   │   ├── state.py               # State management
│   │   └── shortcuts.py           # Keyboard shortcuts
│   ├── components/                # Reusable UI components
│   │   ├── base.py               # Base component classes
│   │   ├── icons.py              # Icon system
│   │   ├── palette.py            # Command palette
│   │   └── toast.py              # Notifications
│   ├── panels/                    # Panel system
│   │   ├── registry.py           # Panel registry
│   │   └── base.py               # Base panel
│   ├── services/                  # Service layer
│   │   ├── protocols.py          # Service protocols
│   │   └── testing.py            # Mock services
│   └── viewmodels/               # MVVM viewmodels
│       └── base.py               # Base viewmodel
├── tests/
│   ├── conftest.py               # Shared fixtures
│   ├── unit/                     # Unit tests
│   └── e2e/                      # E2E tests
├── mcp/                          # MCP server for testing
│   ├── server.py
│   └── tools/
├── resources/
│   └── fonts/
├── scripts/
│   └── claude-setup.sh           # Environment setup
├── CLAUDE.md                     # Instructions for Claude
├── AGENTS.md                     # Architecture documentation
├── pyproject.toml
└── app.py                        # UV shebang entry