Metadata-Version: 2.4
Name: grace-context-manager
Version: 4.0.1
Summary: GRACE Context Manager — Assemble high-quality context for LLM coding assistants
Author: GRACE Contributors
License: MIT
Project-URL: Homepage, https://github.com/VanUST/GRACE
Project-URL: Source, https://github.com/VanUST/GRACE
Project-URL: Tracker, https://github.com/VanUST/GRACE/issues
Keywords: llm,context,prompt,ai,coding,assistant
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyQt6>=6.5.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"

# GRACE Context Manager

[![PyPI version](https://badge.fury.io/py/grace-context-manager.svg)](https://pypi.org/project/grace-context-manager/)
[![Python versions](https://img.shields.io/pypi/pyversions/grace-context-manager.svg)](https://pypi.org/project/grace-context-manager/)
[![License](https://img.shields.io/pypi/l/grace-context-manager.svg)](https://pypi.org/project/grace-context-manager/)

A modern GUI tool for assembling high-quality context for LLM coding assistants. Built with PyQt6.

```bash
pip install grace-context-manager
grace
```

### Upgrading

```bash
pip install --upgrade grace-context-manager
```

**Your data is safe.** All settings, context blocks, extension presets, and recent projects are stored in `~/.grace_manager/` — they persist across upgrades.

## Key Features

- **Context Blocks**: Reusable text snippets organized by category (tech stack, constraints, rules). Toggle on/off as needed.
- **Smart File Selection**: Tree view with checkboxes, file size display, and quick select/deselect.
- **Advanced Filtering**: Filter by extension (typed manually or by checkboxes with two-way binding), keyword filename filter, and built-in ignore rules (dot-files, `node_modules`, `__pycache__`, `venv`).
- **Dynamic Extension Detection**: Auto-detect all file extensions in your project with select/deselect all for quick filtering.
- **Typed Extension Filter**: Extensions can be typed directly as comma-separated values (`.py, .json, .yaml`) or selected via checkboxes — both stay in sync.
- **Extension Presets**: Save frequently used extension combinations (e.g., `python_ml`, `web_dev`) and reload them across sessions.
- **Live Preview**: See assembled context with token count estimation before copying.
- **Preview Modes**: Full context, structure only, or files only.
- **Dynamic Context Refresh**: Refresh selected file contents when files change on disk without re-selecting.
- **Scalable UI**: Adjustable interface scaling (75%-200%) for different screen sizes and devices.
- **Manual Directory Entry**: Type the project root path directly or use Browse/Recent selectors.
- **Keyboard Shortcuts**: Ctrl+C copy, Ctrl+N new block, Ctrl+R refresh, Ctrl+O browse, Ctrl+A/D select all/none.

## One-Click Installers (no Python required)

For users without Python, download and run the platform installer which bundles everything:

| Platform | Installer |
|----------|-----------|
| Windows  | **[install.bat](install.bat)** (right-click → "Run") |
| Linux / macOS | `./install.sh` |

### Manual Install (from source)

```bash
git clone https://github.com/VanUST/GRACE.git
cd grace-context-manager
pip install -e .
```

## Workflow

1. **Select Project**: Click **Browse** to choose your project directory, select from **Recent**, or type the path directly.
2. **Add Context Blocks**: Create reusable blocks for tech stack, coding rules, etc.
3. **Filter Extensions**: Click **Detect** to auto-discover all file extensions, then:
   - Click checkboxes to toggle individual extensions
   - Type extensions directly in the text field (`.py, .json, .yaml`)
   - Use **All**/**None** for quick toggle
   - Save/Load **presets** for reuse across projects
4. **Keyword Filter**: Set a keyword to only show files matching that keyword in their filename.
5. **Select Files**: Check files/directories to include in context.
6. **Add Instruction**: Write your task in the instruction box.
7. **Refresh**: Click **Refresh Context** to reload changed files from disk.
8. **Copy**: Click **Copy Context** and paste into your LLM.

## Extension Presets

Save and load extension filter combinations:

1. Select your desired extensions (via checkboxes or typing)
2. Click **Save** to store as a named preset (e.g., `python_ml`)
3. Click **Load▾** to apply a previously saved preset
4. Presets persist globally in `~/.grace_manager/extension_presets.json`

Built-in defaults: `python_ml`, `web_dev`, `data_science`, `rust`, `golang`, `python`, `all`.

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+C` | Copy context to clipboard |
| `Ctrl+N` | New context block |
| `Ctrl+R` | Refresh context |
| `Ctrl+O` | Browse directory |
| `Ctrl+A` | Select all files |
| `Ctrl+D` | Deselect all files |

## Running Tests

```bash
# Install test dependencies
pip install -e ".[test]"

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_engine.py -v
pytest tests/test_tree_model.py -v
pytest tests/test_config.py -v

# Quick smoke test (no pytest required)
python -m pytest tests/
```

Tests run headless (virtual display) and cover:
- **Engine**: Token estimation, file scanning with extension/keyword filters, context assembly across all modes
- **Tree model**: Check/uncheck propagation, partial uncheck (Bug 1+2 fix), eager loading, extension & keyword filters, nested directory handling, dot-file exclusion
- **Config**: Built-in constants, ignore rules, extension presets

## Context Blocks

Context blocks are saved in `~/.grace_manager/profiles.json`. They persist across sessions.

Organize blocks by category:
- `tech` - Technology stack info
- `constraints` - Coding rules and constraints
- `context` - Project-specific context
- Any custom category

## UI Scaling

Use the scale buttons in the sidebar to adjust the UI. Scaling preference is saved in `~/.grace_manager/settings.json` and persists across sessions.

## Configuration Files

| File | Purpose |
|------|---------|
| `~/.grace_manager/profiles.json` | Context blocks |
| `~/.grace_manager/recent_projects.json` | Recently opened projects |
| `~/.grace_manager/settings.json` | UI preferences (scaling, etc.) |
| `~/.grace_manager/extension_presets.json` | Saved extension presets |
