chore: further wip of scarleet cli

Author: scarowar

.gitignore

@@ -28,6 +28,7 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
+.env
 
 # Installer logs
 pip-log.txt

INSTALL.md

@@ -0,0 +1,92 @@
+# Scarleet CLI Installation (Local, Editable)
+
+You can install Scarleet as a CLI tool locally, so you can run `scarleet` from anywhere on your system.
+
+## 1. Install in Editable Mode
+
+From the root of your project, run:
+
+```sh
+pip install --editable .
+```
+
+This will make the `scarleet` command available globally (in your environment).
+
+## 2. Install dependencies
+
+You can install all required dependencies for Scarleet using either:
+
+```sh
+pip install -r requirements.txt
+```
+
+or, for modern Python packaging:
+
+```sh
+pip install .
+```
+
+Both methods will set up everything needed for the CLI.
+
+## 3. Usage
+
+After installation, you can run:
+
+```sh
+scarleet --help
+```
+
+or any subcommand, e.g.:
+
+```sh
+scarleet new <problem-slug>
+scarleet setup
+scarleet docgen <problem-slug>
+scarleet flashcards <problem-slug>
+scarleet status
+```
+
+## 4. Uninstall
+
+To remove the CLI:
+
+```sh
+pip uninstall scarleet
+```
+
+---
+
+**Note:** This does not publish your package to PyPI. It only makes it available on your local machine for development and use.
+
+
+## OpenAI or Azure OpenAI Usage (Optional)
+
+Scarleet can use either OpenAI or Azure OpenAI models for flashcard and docgen generation. Set the following environment variables in a `.env` file (recommended, and git-ignored):
+
+### For OpenAI:
+```
+OPENAI_API_KEY=sk-...your-key...
+OPENAI_API_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4o
+OPENAI_API_VERSION=2024-06-01
+```
+
+### For Azure OpenAI:
+```
+AZURE_API_KEY=your-azure-key
+AZURE_API_BASE=https://your-resource.openai.azure.com
+AZURE_DEPLOYMENT_NAME=your-deployment
+AZURE_API_VERSION=2024-06-01
+```
+
+- Scarleet will auto-detect which provider to use based on your `.env`.
+- If neither is set, Scarleet will use your local SLM endpoint as a fallback.
+- Install dependencies for .env support:
+  ```sh
+  pip install python-dotenv
+  ```
+- The `openai` Python package is required (see `requirements.txt`).
+
+**Never commit your `.env` file or API keys to version control.**
+
+---

README.md

@@ -21,6 +21,7 @@
 * [File & Folder Structure](#file--folder-structure)
 * [Contributing & Support](#contributing--support)
 * [License](#license)
+* [OpenAI API Usage (Optional)](#openai-api-usage-optional)
 
 ## Overview
 
@@ -67,27 +68,45 @@ This project is for anyone who wants to build a deep, recallable understanding o
     python main.py setup
     ```
 
+## Installation (Local CLI)
+
+You can install all dependencies with either:
+
+```sh
+pip install -r requirements.txt
+```
+
+or, if you prefer PEP 621/modern Python packaging:
+
+```sh
+pip install .
+```
+
+Both methods will install all required packages for Scarleet.
+
+See [INSTALL.md](INSTALL.md) for more details.
+
 ## The Workflow: A Quick Start
 
 The entire process is designed to be simple and flow naturally with your practice.
 
 1.  **Create a New Problem:**
     ```sh
-    python main.py new <problem-slug>
-    # Example: python main.py new two-sum
+    scarleet new <problem-slug>
+    # Example: scarleet new two-sum
     ```
 2.  **Solve It:** Navigate to the new `problems/[id]-[slug]` directory and write your solution in `solution.py`.
 3.  **Generate Docs:** After your solution is accepted on LeetCode, let Scarleet document it for you.
     ```sh
-    python main.py docgen <problem-slug>
+    scarleet docgen <problem-slug>
     ```
 4.  **Create Flashcards:** Turn your documented solution into study material.
     ```sh
-    python main.py flashcards <problem-slug>
+    scarleet flashcards <problem-slug>
     ```
 5.  **Track Your Progress:** View a summary of all your solved problems and update the master `README.md`.
     ```sh
-    python main.py status --update-readme
+    scarleet status --update-readme
     ```
 
 ## Command Usage
@@ -123,6 +142,39 @@ All configuration is managed in the `scarleet.toml` file, which is created by th
         └── neetcode150.json     # NeetCode 150 list
 ```
 
+
+## OpenAI or Azure OpenAI Usage (Optional)
+
+Scarleet can use either OpenAI or Azure OpenAI models (like GPT-4, GPT-3.5, etc.) for generating flashcards and documentation. To enable this, set the following environment variables in a `.env` file (which should NOT be committed to version control):
+
+### For OpenAI:
+```
+OPENAI_API_KEY=sk-...your-key...
+OPENAI_API_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4o
+OPENAI_API_VERSION=2024-06-01
+```
+
+### For Azure OpenAI:
+```
+AZURE_API_KEY=your-azure-key
+AZURE_API_BASE=https://your-resource.openai.azure.com
+AZURE_DEPLOYMENT_NAME=your-deployment
+AZURE_API_VERSION=2024-06-01
+```
+
+- Scarleet will auto-detect which provider to use based on your `.env`.
+- If neither is set, Scarleet will use your local SLM endpoint as a fallback.
+- Install dependencies for .env support:
+  ```sh
+  pip install python-dotenv
+  ```
+- The `openai` Python package is required (see `requirements.txt`).
+
+**Never commit your `.env` file or API keys to version control.**
+
+---
+
 ## Contributing & Support
 
 Contributions, suggestions, and improvements are welcome! Please open an issue or PR. By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.0.

problems/1-two-sum/README.md

@@ -0,0 +1,19 @@
+# Problem 1: Two Sum
+
+## Link
+- [Two Sum](https://leetcode.com/problems/two-sum/)
+
+## Intuition
+By using a hash map to store previously seen numbers and their indices, we can efficiently check if the complement (target - current number) exists.
+
+## Approach
+Iterate through the list, calculate the complement for each number, check if the complement is already in the hash map, and if so, return the indices; otherwise, store the current number and its index in the hash map.
+
+## Complexity
+- Time: `O(n)`
+- Space: `O(n)`
+
+## Notes
+- Utilizes a hash map for constant time look-ups.
+- Returns indices as soon as the pair is found, ensuring only one valid pair is returned.
+- Handles edge cases where no valid pair exists by implicit assumption that input guarantees a solution.

problems/1-two-sum/metadata.json

@@ -0,0 +1,17 @@
+{
+  "title": "Two Sum",
+  "slug": "two-sum",
+  "frontend_id": "1",
+  "url": "https://leetcode.com/problems/two-sum/",
+  "difficulty": "Easy",
+  "tags": [
+    "Array",
+    "Hash Table"
+  ],
+  "lists": [
+    "NeetCode 150",
+    "Blind 75"
+  ],
+  "status": "documented",
+  "last_updated": "2025-06-14T19:54:27.246799Z"
+}

problems/1-two-sum/solution.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+
+# LeetCode Problem: Two Sum
+# URL: https://leetcode.com/problems/two-sum/
+
+from typing import List
+
+
+class Solution:
+    def twoSum(self, nums: List[int], target: int) -> List[int]:
+        val_to_index = {}
+
+        for i, num in enumerate(nums):
+            diff = target - num
+            if diff in val_to_index:
+                return [val_to_index[diff], i]
+            else:
+                val_to_index[num] = i

problems/1-two-sum/test_cases.py

@@ -0,0 +1,14 @@
+import unittest
+from solution import Solution
+
+
+class TestSolution(unittest.TestCase):
+    def setUp(self):
+        self.solution = Solution()
+
+    def test_example_1(self):
+        self.assertEqual(self.solution.twoSum([2, 7, 11, 15], 9), [0, 1])
+
+
+if __name__ == "__main__":
+    unittest.main()

pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "scarleet"
+version = "0.1.0"
+description = "Scarleet: CLI for LeetCode mastery and spaced repetition."
+authors = [
+    { name = "Scarowar" }
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "typer[all]",
+    "rich",
+    "toml",
+    "requests",
+    "openai",
+    "python-dotenv"
+]
+
+[project.scripts]
+scarleet = "scarleet.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

requirements.txt

@@ -0,0 +1,6 @@
+typer[all]
+rich
+toml
+requests
+openai>=1.0.0
+python-dotenv