Metadata-Version: 2.4
Name: luckyd-code
Version: 1.2.2
Summary: LuckyD Code — AI coding assistant powered by DeepSeek
Project-URL: Homepage, https://github.com/Dylanchess0320/LuckyD-Code
Project-URL: BugTracker, https://github.com/Dylanchess0320/LuckyD-Code/issues
Author-email: Dylan Kaye <dylanchess0320@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: ai,assistant,cli,coding,luckyd
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: nest-asyncio>=1.5.0
Requires-Dist: openai>=1.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: websockets>=11.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == 'browser'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: types-aiofiles; extra == 'dev'
Requires-Dist: types-beautifulsoup4; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: rag
Requires-Dist: numpy>=1.24.0; extra == 'rag'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'rag'
Provides-Extra: rag-full
Requires-Dist: faiss-cpu>=1.7.0; extra == 'rag-full'
Requires-Dist: numpy>=1.24.0; extra == 'rag-full'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'rag-full'
Requires-Dist: watchdog>=3.0.0; extra == 'rag-full'
Description-Content-Type: text/markdown

# LuckyD Code

[![CI](https://github.com/Dylanchess0320/LuckyD-Code/actions/workflows/ci.yml/badge.svg)](https://github.com/Dylanchess0320/LuckyD-Code/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/luckyd-code)](https://pypi.org/project/luckyd-code/)

A full-featured AI coding assistant for your terminal and browser, powered by the DeepSeek API. Features 35+ built-in tools, a semantic knowledge graph, Playwright browser automation, multi-agent orchestration, Docker sandboxing, and a live Web UI.

---

## Features

- **AI Chat** — Conversational coding assistant with streaming responses and thinking/reasoning mode
- **Smart Model Routing** — Auto-classifies prompt complexity into 4 tiers, escalating from cheap/fast to powerful/reasoning models
- **Knowledge Graph** — Automatically indexes your codebase into a searchable vector graph; falls back to a keyword graph if vector dependencies aren't installed
- **Memory System** — Persistent memory across sessions with auto-save and relevance search
- **Cost Tracking** — Per-session and cumulative cost tracking across models
- **Web UI** — Browser-based interface with cost panel, memory management, and model routing info
- **35+ Built-in Tools** — File operations, search, code analysis, shell commands, and more
- **MCP Support** — Model Context Protocol for extending with custom tools
- **Plugin System** — Drop Python files into `~/.claude/plugins/` to register additional tools at runtime
- **Context Management** — Auto-compaction with summarization to stay within context windows
- **Background Agents** — Run tasks asynchronously while continuing to chat
- **Orchestrator** — Researcher → Coder → Reviewer pipeline for complex tasks
- **Hooks System** — Pre/post tool use, pre/post chat, and session lifecycle hooks
- **Sandboxing** — Docker-based secure command execution
- **Session Management** — Save and load conversations
- **Undo** — Revert file writes and edits
- **Export** — Export conversations to Markdown or HTML
- **Shell Detection** — Auto-detects Git Bash → WSL → cmd.exe on Windows; rewrites interactive commands so the correct shell is always used
- **Analytics** — Code health scoring, code smell detection, and trend tracking

---

## Prerequisites

- **Python 3.10+**
- **DeepSeek API key** — Get one free at [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)

---

## Quick Start — No setup required

**Windows** — double-click one of these:
- `Install and Run - Windows.bat` — CLI mode
- `Install and Run Web UI - Windows.bat` — browser UI

**Mac** — double-click `Install and Run - Mac.command`
*(first time: right-click → Open to bypass Gatekeeper)*

**Linux** — run in terminal:
```bash
chmod +x "Install and Run - Linux.sh"
"./Install and Run - Linux.sh"
```

The launcher automatically creates a virtual environment, installs dependencies, and prompts for your API key on first run.

---

## Installation

### From PyPI

```bash
pip install luckyd-code
```

### From source

```bash
git clone https://github.com/Dylanchess0320/LuckyD-Code
cd luckyd-code
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .
```

### Optional dependencies

```bash
# RAG support (semantic memory search)
pip install -e ".[rag]"

# Full RAG with FAISS vector search and file watching
pip install -e ".[rag-full]"

# Browser automation (Playwright)
pip install -e ".[browser]"

# Development dependencies
pip install -e ".[dev]"
```

---

## Usage

### CLI mode

```bash
luckyd-code
# or
ldc
# or
python main.py
```

### Web UI mode

```bash
luckyd-code --web
# or
python main.py --web
```

Then open `http://localhost:8000` in your browser.

### Commands

Once in the CLI, use slash commands:

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/model` | Switch model or view current model |
| `/cost` | Show session cost |
| `/memory` | View or search memory |
| `/session` | Save, load, or list sessions |
| `/export` | Export conversation |
| `/undo` | Undo last file write/edit |
| `/orchestrate` | Run multi-agent pipeline |
| `/analytics` | Run code health analysis |
| `/clear` | Clear conversation |
| `/quit` | Exit |

### Environment variables

Copy `.env.example` to `.env` and set your API key:

```bash
cp .env.example .env
```

Then edit `.env`:

```
DEEPSEEK_API_KEY=sk-your-deepseek-key-here
```

---

## Built-in Tools

LuckyD Code includes 35+ tools for interacting with your codebase:

- **File operations**: Read, Write, Edit, Glob, Grep, Delete, Move, Copy
- **Code analysis**: Lint, TypeCheck, Complexity, Coverage
- **Search**: Semantic search, keyword search, file search
- **Shell**: Bash execution, PowerShell, Git operations
- **Web**: Playwright browser automation, HTTP requests
- **Knowledge**: Knowledge graph query, memory search
- **Project**: Project scan, dependency analysis, code smell detection
- **Utility**: Undo, Export, Session management

---

## Project Structure

```
luckyd_code/
├── cli.py               # Terminal UI and REPL
├── cli_commands/        # Slash-command handlers
├── web_app.py           # Web UI server (FastAPI)
├── web_routes/          # Web UI route handlers
├── api.py               # API streaming client
├── router.py            # Model routing
├── config.py            # Configuration
├── context.py           # Conversation context
├── cost_tracker.py      # Cost tracking
├── hooks.py             # Lifecycle hooks
├── model_registry.py    # Model definitions
├── memory/              # Persistent memory
├── brain/               # Knowledge graph & RAG
├── tools/               # Tool registry (35+ tools)
├── mcp/                 # MCP client
├── permissions/         # Permission system
├── skills/              # Review & security
├── analytics/           # Usage analytics
├── templates/           # Web UI assets
└── background/          # Background agents
```

---

## Development

```bash
# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# With coverage
pytest --cov=luckyd_code --cov-report=term

# Type checking
mypy luckyd_code

# Build distribution
make build
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

1. Fork the repository
2. Create a feature branch from `main`
3. Write tests for new functionality
4. Ensure all existing tests pass
5. Submit a pull request

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Security

See [SECURITY.md](SECURITY.md) for supported versions and how to report vulnerabilities.

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a history of changes.