Metadata-Version: 2.4
Name: luckydofficial-code
Version: 1.3.5
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: AGPL-3.0-only
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 :: GNU Affero General Public License v3
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: python-dotenv>=1.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: detect-secrets>=1.4; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.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: game
Requires-Dist: pygame>=2.5.0; extra == 'game'
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

**The AI coding assistant that thinks before it ships.**
Terminal-native · Browser-ready · DeepSeek-powered · Multi-Agent · v1.3.5

<p align="center">
  <a href="https://github.com/Dylanchess0320/LuckyD-Code/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Dylanchess0320/LuckyD-Code/ci.yml?style=flat-square&label=CI&logo=github" alt="CI"></a>
  <a href="https://codecov.io/gh/Dylanchess0320/LuckyD-Code"><img src="https://img.shields.io/codecov/c/github/Dylanchess0320/LuckyD-Code?style=flat-square&logo=codecov&label=Coverage" alt="Coverage"></a>
  <a href="https://pypi.org/project/luckydofficial-code/"><img src="https://img.shields.io/pypi/v/luckydofficial-code?style=flat-square&logo=pypi&label=PyPI&color=3775A9" alt="PyPI"></a>
  <a href="https://pypi.org/project/luckydofficial-code/"><img src="https://img.shields.io/pypi/pyversions/luckydofficial-code?style=flat-square&logo=python&label=Python&color=3776AB" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL%20v3-blue?style=flat-square&logo=opensourceinitiative" alt="License"></a>
  <a href="https://github.com/Dylanchess0320/LuckyD-Code"><img src="https://img.shields.io/github/stars/Dylanchess0320/LuckyD-Code?style=flat-square&logo=github&color=FCD34D" alt="Stars"></a>
  <a href="https://discord.gg/ApEKKUuKd"><img src="https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
</p>

---

## ✨ Why LuckyD Code?

| | LuckyD Code | Other Assistants |
|---|---|---|
| 🧠 **Reasoning-first** | Self-verifies every write/edit automatically | Hope the LLM gets it right |
| 🔀 **Smart routing** | Picks the right model tier per prompt | Same model for everything |
| 🐝 **Multi-Agent Swarms** | Spawn parallel specialist agents that coordinate via shared tasks | Single-agent only |
| 🗺️ **Code Knowledge Graph** | Indexes your codebase; semantic + keyword search | Blind to your project |
| 🕸️ **Web + Terminal** | Full CLI *and* browser UI from the same binary | CLI-only or browser-only |
| 🔒 **Sandboxed** | Docker-isolated command execution | Raw shell access |
| 🔭 **LSP integration** | Go-to-definition, references, rename across files via pylsp/pyright | None |
| 📊 **Analytics** | Built-in code health, smell detection, trend tracking | None |
| 🔧 **Autonomous Fixer** | Diagnoses bugs → generates patches → validates → opens PR | Manual triage |
| 📓 **Notebook editing** | Cell-level Jupyter `.ipynb` read/write with execution-count clearing | None |
| 📋 **Plan Mode** | Read-only exploration & design phase before writing any code | Blind edits |
| 🧩 **Plugin system** | Drop a `.py` file, auto-loads as an AI tool — no restart | Limited or no extensibility |

---

## 🚀 Quick Start

### Prerequisites

- **Python 3.10+** – [python.org](https://www.python.org/downloads/) or `brew install python@3.12`
- **Rust** – only needed if `pip` can't find a pre‑built wheel for your platform (uncommon)

### Installation

```bash
# Install from PyPI (recommended)
pip install luckydofficial-code

# With optional RAG support (semantic code search & knowledge graph)
pip install luckydofficial-code[rag-full]

# Browser automation (Playwright-powered web scraping / testing)
pip install luckydofficial-code[browser]

# Game generation (Pygame)
pip install luckydofficial-code[game]
```

Or clone and install in editable mode for development:

```bash
git clone https://github.com/Dylanchess0320/LuckyD-Code
cd LuckyD-Code
pip install -e ".[dev]"
```

### Usage

```bash
# Start the interactive CLI
luckyd-code

# Launch the web UI (FastAPI + WebSocket)
luckyd-code --web

# Show help
luckyd-code --help

# Quick alias (same as luckyd-code)
ldc
```

From source:

```bash
python main.py                    # CLI
python main.py --web              # Web UI
```

---

## 🔑 Configuration

Create a `.env` file in the project root or set the environment variable:

```env
# DeepSeek API key (required)
DEEPSEEK_API_KEY=sk-your-deepseek-key-here
```

Get your key at [platform.deepseek.com](https://platform.deepseek.com).

Optional settings (see `config.py` for all options):

| Variable | Description |
|----------|-------------|
| `DEEPSEEK_API_KEY` | Primary API key |
| `OPENAI_API_KEY` | Fallback/alternative provider |
| `LUCKYD_CONFIG_DIR` | Custom config directory |
| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |

Settings are resolved in this order: environment variable → config file → defaults.

---

## 🌟 Features

### Core Agent Loop
- **Think → Act → Verify** – The model generates code, tools execute it, and verification checks syntax, lint, and tests automatically.
- **Stuck-loop detection** – Identical tool-call batches are detected and broken automatically with a nudge message.
- **Smart model routing** – Four tiers (T1–T4) from lightweight chat to deep reasoning; heuristic + LLM classifier for sub‑400ms selection.
- **Mid-loop model escalation** – Automatically upgrades to a stronger model tier when verification keeps failing.
- **Verification nudge** – Warns the model when it makes multiple consecutive write batches without running any tests or lint.
- **Streaming responses** – Real-time SSE streaming in both CLI and web UI.
- **Cost tracking** – Token usage and cost estimation per session.

### Multi-Agent & Orchestration
- **Swarm Teams** (`TeamCreate`/`TeamStatus`/`TeamDelete`) – Spawn up to 8 parallel specialist agents with shared tasks. Each agent runs its own full agent loop with independent tool access.
- **Agent Handoff** – Chain specialist agents: `researcher → coder → reviewer → tester`. Each role gets its own context and tools.
- **Sub-Agents** – Fork an isolated agent for a self-contained subtask without polluting the main conversation.
- **Smart Orchestrator** – An agentic coordinator that decides which workers to spawn, collects their results, and synthesizes findings.
- **Task System** – Persistent cross-session tasks with status tracking (`pending → in_progress → completed → blocked`), dependencies, tags, and priority levels.
- **Forked Skills** – Run built-in skills (review, security, test-gen, docs, refactor) in isolated sub-agents with dedicated token budgets.

### Plan Mode
- **Read-only exploration phase** – Before writing any code, LuckyD explores your codebase, identifies patterns, considers trade-offs, and designs a concrete implementation strategy.
- **User approval gate** – Plans are presented for review before any file is modified.
- **Structured questions** – Clarify ambiguous requirements with multiple-choice prompts during planning.

### 🛠️ 50+ Built-in Tools

#### File & Code Operations
| Tool | Description |
|------|-------------|
| `Read` | Read files with line offsets and limits |
| `Write` | Create or overwrite files with dry-run diff preview |
| `Edit` | Exact-string replacement with replace-all support |
| `Diff` | Unified diff — file vs proposed, file vs file, string vs string |
| `Glob` | Recursive file pattern matching (e.g. `src/**/*.ts`) |
| `Grep` | Regex search via ripgrep with file/content/count modes |
| `Brief` | AI-powered file/directory/text summaries |

#### Git & Version Control
| Tool | Description |
|------|-------------|
| `GitStatus` | Working tree status |
| `GitDiff` | Staged/unstaged diffs |
| `GitLog` | Recent commit history |
| `GitCommit` | Create commits |
| `GitAdd` | Stage files |
| `GitBranch` | List and manage branches |
| `GitPush` | Push to remote |
| `GitPR` | Push + create draft PR |
| `GitWorktree` | Isolated git worktrees for safe experimentation |

#### LSP / Code Intelligence
| Tool | Description |
|------|-------------|
| `LspDefinition` | Go-to-definition |
| `LspReferences` | Find all references across project |
| `LspHover` | Type info and docstrings |
| `LspRename` | Safe symbol rename (all references) |
| `LspDocumentSymbols` | File outline (classes, functions, variables) |
| `LspWorkspaceSymbols` | Project-wide symbol search |
| `LspImplementation` | Find concrete implementations of abstract methods |
| `LspIncomingCalls` | Who calls this function? |
| `LspOutgoingCalls` | What does this function call? |

#### Browser & Web
| Tool | Description |
|------|-------------|
| `BrowserNavigate` | Navigate to URL |
| `BrowserClick` | Click elements via CSS selector |
| `BrowserType` | Type text into inputs |
| `BrowserSnapshot` | Text snapshot of page elements |
| `BrowserScreenshot` | Capture screenshots (PNG) |
| `BrowserEvaluate` | Run JavaScript on page |
| `BrowserIntercept` | Mock/block network requests |
| `BrowserTrace` | Record screenshots + network + DOM traces |
| `BrowserEmulate` | Emulate mobile devices (iPhone, Pixel, iPad) |
| `WebFetch` | Fetch and extract text from URLs |
| `WebSearch` | Web search with result extraction |
| `Http` | HTTP client (GET/POST/PUT/PATCH/DELETE with JSON, forms, auth) |
| `OpenInBrowser` | Open URLs in user's system browser |
| `YouTubePlaylist` | Build YouTube playlists from video URLs |

#### Shell & Process
| Tool | Description |
|------|-------------|
| `Bash` | Execute shell commands |
| `PowerShell` | Execute PowerShell commands (Windows) |
| `Process` | Background process manager (start/read/status/kill) |
| `ShellHistory` | Read recent bash/zsh/fish/PowerShell history |
| `Watch` | Watch files for changes (exists/changed/contains/deleted) |

#### Data & Databases
| Tool | Description |
|------|-------------|
| `SQLite` | Query, execute, schema, tables on SQLite files |
| `NotebookRead` | Read Jupyter `.ipynb` cells |
| `NotebookEdit` | Cell-level edit (replace/insert/delete) on notebooks |
| `Repl` | Persistent Python REPL with namespace across calls |
| `ImageAnalyze` | Analyze images (JPEG/PNG/GIF/BMP/WebP) |

#### Memory & Knowledge
| Tool | Description |
|------|-------------|
| `Memory` | Persistent key-value store (set/get/list/delete/search) |
| `BrainSearch` | Semantic codebase search via FAISS + sentence-transformers |
| `BrainStatus` | Index stats and knowledge graph health |

#### Task & Team Coordination
| Tool | Description |
|------|-------------|
| `TaskCreate` | Create tracked tasks with dependencies and tags |
| `TaskUpdate` | Update task status and output |
| `TaskGet` | Retrieve full task details |
| `TaskList` | List tasks filtered by status/tag |
| `TaskOutput` | Read task output (blocking or non-blocking) |
| `TeamCreate` | Spawn parallel multi-agent swarm |
| `TeamStatus` | Poll live agent progress |
| `TeamDelete` | Shut down and clean up a team |
| `SendMessage` | Inter-agent messaging (broadcast or direct) |
| `ReceiveMessage` | Read pending messages from agent inbox |

#### Code Generation
| Tool | Description |
|------|-------------|
| `ProjectGen` | Generate full project scaffolds from plain English |
| `DockerfileGen` | Auto-detect stack → generate Dockerfile + docker-compose.yml |
| `ReadmeGen` | Scan project → generate professional README.md |
| `GameGen` | Generate runnable Pygame games from descriptions |

#### Automation & Scheduling
| Tool | Description |
|------|-------------|
| `CronCreate` | Schedule recurring or one-shot prompts |
| `CronList` | List active cron jobs |
| `CronDelete` | Cancel scheduled jobs |
| `AutoCommit` | Automatic git commits with generated messages |
| `Backup` | Session backup and restore |

#### Utilities
| Tool | Description |
|------|-------------|
| `Secrets` | Read `.env` keys or system keychain (never dumps all secrets) |
| `Notify` | Desktop toast notifications on task completion |
| `DateTime` | Current local date/time |
| `Sleep` | Pause agent (0.1–300s) |
| `SkillList` / `ForkedSkill` | List and run reusable skills in isolated agents |
| `ToolSearch` | Search available tools by keyword |
| `Config` | Read/write agent settings mid-session |
| `EnterPlanMode` / `ExitPlanMode` | Read-only design phase gate |
| `EnterWorktree` / `ExitWorktree` | Isolated git worktrees for risky changes |

### Interface
- **Full CLI** – Rich terminal UI with syntax highlighting, streaming responses, slash commands (`/help`, `/doctor`, `/share`, `/pr-comments`, `/plugins`, `/brain`, `/audit`, `/sessions`, `/budget`, `/config`, `/effort`, `/background`).
- **Web UI** – FastAPI + WebSocket server, same agent loop, accessible from any browser. Full session management, file browser, settings panel, cost dashboard.
- **Keybindings** – emacs-style navigation, Ctrl+R history search, multi-line editing.
- **Themes** – Configurable Rich color themes for terminal output.

### Security & Quality
- **Docker‑sandboxed bash** – All shell commands run isolated by default (configurable).
- **Permission system** – Granular control over file read/write, network, and tool access.
- **Secrets scanning** – Built-in gitleaks integration for pre-commit secret detection.
- **96% test coverage** – Strict coverage threshold enforced in CI.
- **Full mypy type coverage** – All core modules are fully typed and mypy-clean.
- **Pre-commit hooks** – Ruff formatting, type checking, secret scanning on every commit.

### Analytics & Self-Improvement
- **Code analytics** – Smell detection, trend tracking, and health reporting.
- **Autonomous fixer** – Error detection → patch generation → validation → PR creation.
- **Feedback analyzer** – Learns from corrections and adjusts behavior.
- **Self-improve** – Internal self-critique and improvement loop.
- **Audit daemon** – Background watcher for codebase health.

### Extensibility
- **Plugin system** – Drop a `.py` file into `~/.luckyd-code/plugins/`, run `/plugins reload`, and it auto-loads as a new AI tool. No restart needed.
- **Lifecycle hooks** – Run custom scripts before/after actions; integrate with CI/CD pipelines.
- **MCP client** – Model Context Protocol support for connecting external tools.
- **Custom skills** – Add `.md` files to `.luckyd-code/skills/` for reusable agent behaviors.

---

## 📚 Documentation

| Document | Description |
|----------|-------------|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Full system architecture and data flow |
| [SKILLS.md](docs/SKILLS.md) | Built-in skills: review, security analysis |
| [PLUGINS.md](docs/PLUGINS.md) | Plugin development guide |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor setup and guidelines |
| [TODO.md](TODO.md) | Roadmap and improvement tracker |

---

## 🧪 Development & Testing

```bash
# Run all tests
pytest

# With coverage (threshold ≥96%)
pytest --cov=luckyd_code

# Type checking
mypy luckyd_code

# Lint with pre‑commit hooks
pre-commit run --all-files

# Scan for accidentally committed secrets
make secrets-scan   # requires gitleaks
```

---

## 🤝 Contributing

We welcome contributions! Please read the [Contributing Guide](CONTRIBUTING.md) for setup instructions, coding standards, and the PR process.

By contributing, you agree that your contributions will be licensed under AGPL v3. For alternative licensing, contact the maintainer.

---

## 📄 License

This project is licensed under the **GNU Affero General Public License v3**. See [LICENSE](LICENSE) for the full text.

---

## 📦 Roadmap

See [TODO.md](TODO.md) for the full roadmap. Short-term priorities:

- Multi-provider support (OpenAI, Groq, Together natively alongside DeepSeek)
- VS Code and JetBrains extension
- Test coverage for the new v1.3.5 tool suite
- Plugin marketplace for third-party tools

---

*Built with ❤️ by [Dylan Kaye](https://github.com/Dylanchess0320).*
