LC-AT — LeetCode Local Assistant (MVP)

A minimal CLI tool to:

• Pull LeetCode problems offline (Markdown + starter solution).
• Generate pytest tests via Gemini AI (or use a local stub).
• Run tests locally with pytest.
• Submit solutions to LeetCode via Playwright automation (stores auth state).

This README shows how to set up and use the tool as a complete beginner.

---

Prerequisites

• Python 3.10+ installed and on PATH
• Git (optional)
• Windows PowerShell (instructions assume PowerShell)
• A Google Gemini API key (optional — tool falls back to a stub if not provided)
• Optional: LeetCode credentials or Playwright auth state (for automated submit)

---

One-line bootstrap (remote)

PowerShell (Windows):

iwr -useb https://raw.githubusercontent.com/0xunLin/leetcode-cli-alpha/main/scripts/remote.ps1 | iex

Bash (Linux / macOS):

curl -sSL https://raw.githubusercontent.com/0xunLin/leetcode-cli-alpha/main/scripts/remote.sh | bash

Notes:

• The bootstrap scripts create a virtual environment (.venv), install Python dependencies, install Playwright browsers, and create a .env from .env.example if missing.
• Review the script before running a remote one-liner. Remote execution is convenient but has security risks.

---

Quick setup (PowerShell)

Open PowerShell in the project folder c:\Users\DELL\Desktop\LC_at and run:

# 1. Create & activate virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 2. Install Python dependencies
pip install -r requirements.txt
pip install beautifulsoup4 python-dotenv

# 3. Install Playwright browsers (required for submit automation)
python -m playwright install

---

Environment variables

Create .env from .env.example:

copy .env.example .env

Then open .env and set values:

• GEMINI_API_KEY — (optional) your Gemini / Google GenAI API key
• GEMINI_MODEL / GEMINI_ENDPOINT — only if you have a different model/endpoint
• LEETCODE_EMAIL / LEETCODE_PASSWORD — optional for first-time login (or use auth state)
• LEETCODE_AUTH_STATE — optional path to Playwright storage state JSON

Security: never commit .env, auth files, or API keys.

---

Create Playwright auth state (recommended for submit)

Run the helper to log in once and save auth state:

# activate venv first if not active
.\.venv\Scripts\Activate.ps1
python save_playwright_auth.py
# Follow the interactive instructions to sign in in the opened browser.
# This produces playwright_auth.json in the project root by default.

Set LEETCODE_AUTH_STATE in .env to the saved file path if desired.

---

Basic CLI usage

Activate the venv:

.\.venv\Scripts\Activate.ps1

Commands (run from project root):

• Pull a problem (uses cache by default):

  python cli.py pull two-sum

• Force-refresh from LeetCode GraphQL (ignore cache):

  python cli.py pull two-sum --force-refresh

• Run tests (pytest):

  python cli.py test two-sum

• Submit solution to LeetCode (uses Playwright; headless by default):

  python cli.py submit two-sum

Files created per problem:

problems/<slug>/
  README.md          # problem statement (markdown)
  solution.py        # starter / your code
  test_solution.py   # tests generated by AI or stub
.cache/<slug>.json   # cached GraphQL response
playwright_auth.json # Playwright auth state (if created)

---

How the AI test generation works

• If GEMINI_API_KEY is set, the tool sends the problem text to the configured Gemini REST endpoint and requests a JSON object with keys readme, starter, and tests. The tests content is written to test_solution.py.
• If no API key is provided or the request fails, a small fallback pytest stub is written so you can still run the flow locally.

Tip: inspect the raw AI output if tests fail or contain invalid imports and adjust utils/ai.py parsing logic.

---

Cache behavior

• GraphQL responses are cached to .cache/<slug>.json.
• Default pull uses cache. Use --force-refresh to fetch fresh and overwrite cache.
• To clear cache manually, remove .cache files.

---

Troubleshooting

• Pylance / VS Code import errors: ensure VS Code Python interpreter is set to .venv\Scripts\python.exe (Ctrl+Shift+P → Python: Select Interpreter).
• ImportError: playwright — run pip install playwright in the active environment and python -m playwright install.
• If submission fails due to UI changes, run submit headful (edit submit_solution(..., headless=False)) and debug selectors in the opened browser.
• If Gemini responses are not parsed correctly, enable debug prints in utils/ai.py to see raw response text.

---

Warnings & legal

• Do not commit API keys, auth state, or .env to source control.
• Automating submissions to LeetCode may violate LeetCode Terms of Service. Use the submit automation responsibly; consider manual submission if unsure.

---

Next improvements (ideas)

• Add cli cache-clear and cli cache-list.
• Improve AI prompt and validation of generated tests (ensure from solution import Solution).
• Add support for other languages (TypeScript / Java / C++).
• Add unit tests for CLI commands and parsing functions.

---

Getting help

If something breaks, open an issue or ask for help with:

• Exact error trace or terminal output
• The problem slug you tested with
• Whether Gemini key and Playwright auth were configured

Happy hacking — start by pulling two-sum and running the tooling.