ichiran 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ichiran-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Utkarsh Kamat
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
ichiran-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,370 @@
1
+ Metadata-Version: 2.4
2
+ Name: ichiran
3
+ Version: 0.1.0
4
+ Summary: AI-powered README generator — interview your project, scan your codebase, generate a complete README
5
+ Author-email: Utkarsh Kamat <work.utkarshkamat@gmail.com>, Hruday <mscids2024.hruday@unigoa.ac.in>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ushiecodes/ichiran
8
+ Project-URL: Issues, https://github.com/ushiecodes/ichiran/issues
9
+ Keywords: readme,documentation,ai,gemini,cli,generator
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Topic :: Documentation
16
+ Classifier: Topic :: Software Development :: Documentation
17
+ Classifier: Topic :: Utilities
18
+ Requires-Python: >=3.12
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: google-genai>=1.67.0
22
+ Requires-Dist: python-dotenv>=1.2.2
23
+ Requires-Dist: rich>=14.3.3
24
+ Requires-Dist: pathspec>=1.0.4
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest>=8.0; extra == "test"
27
+ Requires-Dist: pytest-cov>=5.0; extra == "test"
28
+ Requires-Dist: pytest-mock>=3.14; extra == "test"
29
+ Requires-Dist: pip-audit>=2.10.0; extra == "test"
30
+ Dynamic: license-file
31
+
32
+ # Ichiran — AI-powered README generator
33
+
34
+ > Ichiran is an AI-powered CLI tool for developers who want to generate complete, production-grade README files without spending time writing them manually. It solves the problem of projects shipping with poor or missing documentation by interviewing the developer about their project, scanning the codebase, and using Google Gemini to generate a comprehensive README.md automatically.
35
+
36
+ ![Version](https://img.shields.io/badge/version-0.1.0-blue)
37
+ ![License](https://img.shields.io/badge/license-MIT-green)
38
+ ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)
39
+ ![Status](https://img.shields.io/badge/status-Alpha-orange)
40
+
41
+ ---
42
+
43
+ ## What This Does
44
+
45
+ Ichiran provides a comprehensive solution for generating high-quality READMEs for developer projects, offering a range of features to streamline the documentation process:
46
+
47
+ * **Progressive 3-phase interview** — Guides the user through 30 questions across 3 optional depth layers to capture full project context.
48
+ * **Codebase scanner** — Reads the entire project directory and feeds source code directly to Gemini for a more accurate README.
49
+ * **AI-powered generation** — Sends interview answers and codebase to Gemini 2.5 Flash with the system prompt to generate a production-grade README.
50
+ * **README writer** — Creates a new `README.md` or overwrites/appends an existing one with collision detection.
51
+ * **API key management** — Stores the Gemini API key securely in the user config directory, prompting once and never again.
52
+ * **Sensitive file protection** — Automatically skips `.env` files, keys, certificates, and credentials during codebase scanning.
53
+ * **Token budget management** — Truncates large files and prioritises key source files to stay within Gemini's context window.
54
+ * **Retry logic** — Automatically retries on 429 rate limit errors with exponential backoff.
55
+ * **SKIP keyword** — Skips a question entirely, sending no answer to Gemini for that question.
56
+ * **TLDR keyword** — Sends a generic answer to Gemini, allowing it to infer context from the codebase.
57
+ * **RTFM keyword** — Shows detailed help and examples for the current question.
58
+ * **QUIT keyword** — Exits the interview with confirmation, cancelling README generation.
59
+ * **`--reset` flag** — Clears the saved API key so the user can rotate credentials.
60
+ * **`--version` flag** — Prints the current installed version.
61
+ * **Rich terminal UI** — Features styled panels, colored output, and an ASCII logo banner for an improved user experience.
62
+
63
+ ## Requirements
64
+
65
+ To run Ichiran, ensure you have:
66
+
67
+ * **Python 3.12+**
68
+ * The following Python packages (automatically installed via `pip install ichiran`):
69
+ * `google-genai>=1.67.0`
70
+ * `python-dotenv>=1.2.2`
71
+ * `platformdirs>=4.0.0`
72
+ * `rich>=14.3.3`
73
+ * `pip-audit>=2.10.0`
74
+ * `pyasn1>=0.6.3`
75
+ * `pathspec>=1.0.4`
76
+
77
+ ## Quick Start
78
+
79
+ 1. Install the project dependencies using pip:
80
+ ```bash
81
+ pip install ichiran
82
+ ```
83
+ 2. Run the Ichiran CLI tool. On the first run, you will be prompted to enter your Google Gemini API key.
84
+ ```bash
85
+ ichiran
86
+ ```
87
+
88
+ ## Development and Tests
89
+
90
+ Install the project and its test tools in a local environment:
91
+
92
+ ```bash
93
+ uv sync --extra test
94
+ ```
95
+
96
+ Run the automated suite with the 85% coverage gate:
97
+
98
+ ```bash
99
+ uv run pytest -q --cov=cli --cov=config --cov=display --cov=gemini --cov=interview --cov=prompt --cov=scanner --cov=writer --cov-report=term-missing --cov-fail-under=85
100
+ ```
101
+
102
+ The test suite mocks Gemini API calls and redirects config writes to temporary paths. See [docs/](docs/README.md) for the V-Model deliverables and project reports.
103
+
104
+ ## Setup
105
+
106
+ Follow these steps to get Ichiran up and running from a clean slate:
107
+
108
+ 1. Clone the repository:
109
+ ```bash
110
+ git clone https://github.com/ushiecodes/ichiran.git
111
+ ```
112
+ 2. Navigate into the project directory:
113
+ ```bash
114
+ cd ichiran
115
+ ```
116
+ 3. Install the project dependencies using pip:
117
+ ```bash
118
+ pip install ichiran
119
+ ```
120
+ 4. Run the Ichiran CLI tool. On the first run, you will be prompted to enter your Google Gemini API key.
121
+ ```bash
122
+ ichiran
123
+ ```
124
+
125
+ ## Usage
126
+
127
+ The primary workflow for using Ichiran involves launching the CLI tool in your project directory, answering a series of questions, and then letting the AI generate your `README.md` file.
128
+
129
+ 1. User navigates to their project directory in the terminal.
130
+ 2. User runs `ichiran`.
131
+ 3. The tool displays a banner and an information panel.
132
+ 4. The tool checks for a saved Gemini API key in `~/.config/ichiran/config.json`.
133
+ 5. If no key exists, the user is prompted to enter their Gemini API key, which is then saved for future use.
134
+ 6. The Phase 1 interview begins, asking 5 initial questions about the project.
135
+ 7. The user answers questions; they can type `SKIP`, `TLDR`, `RTFM`, or `QUIT` at any time for specific interactions.
136
+ 8. A layer prompt appears, allowing the user to choose to complete "done" (finish), "layer 2" (add usage, config, architecture), "layer 3" (add security, deployment, changelog, contributing), or "more" (both layer 2 and 3).
137
+ 9. If Layer 2 is chosen, Batch A (Q6-Q11) and then Batch B (Q12-Q16) questions are asked.
138
+ 10. If Layer 3 is chosen, Groups A (Q17-Q22), B (Q23-Q25), and C (Q26-Q30) questions are asked.
139
+ 11. The interview completes, and the tool scans the project codebase.
140
+ 12. Sensitive files, binary files, and oversized files are automatically skipped.
141
+ 13. Interview answers and the codebase are assembled into a single prompt.
142
+ 14. The prompt is sent to Gemini 2.5 Flash with the system prompt as a system instruction.
143
+ 15. Gemini generates the `README.md` content and returns it.
144
+ 16. The tool strips any markdown code fences from the response.
145
+ 17. If `README.md` already exists in the current directory, the user is asked to overwrite, append, or cancel.
146
+ 18. The generated `README.md` is written to the current working directory.
147
+ 19. The user sees a final success message: "Done. Your README is ready."
148
+
149
+ ## Configuration Reference
150
+
151
+ Ichiran uses the following configuration options:
152
+
153
+ | Variable | Purpose | Default | Valid Values | Required |
154
+ | :----------------- | :------------------------------------------------------ | :--------------- | :------------------------------------------------ | :------- |
155
+ | `API_KEY` | 🔑 Gemini API key used to authenticate requests | `none` | any valid Gemini API key string | required |
156
+ | `MODEL` | Gemini model used for generation | `gemini-2.5-flash` | any model returned by `client.models.list()` | optional |
157
+ | `MAX_FILE_SIZE_KB` | maximum size of a single file the scanner will read | `150` | any positive integer | optional |
158
+ | `MAX_TOTAL_CHARS` | maximum total characters sent to Gemini from codebase scan | `400000` | any positive integer | optional |
159
+
160
+ These variables are loaded in the following order of precedence:
161
+ 1. **Config file:** `API_KEY` is primarily stored and loaded from a JSON file at `~/.config/ichiran/config.json`.
162
+ 2. **.env file:** A local `.env.local` file (for development only) can also provide `API_KEY` via `python-dotenv`.
163
+ 3. **Hardcoded defaults with environment override:** `MODEL`, `MAX_FILE_SIZE_KB`, and `MAX_TOTAL_CHARS` have hardcoded defaults in the source, but can be overridden by environment variables set before launch.
164
+
165
+ ## Architecture
166
+
167
+ ### Folder Tree
168
+
169
+ ```
170
+ .
171
+ ├── .gitignore # Specifies intentionally untracked files to ignore.
172
+ ├── cli.py # Entry point, argument parsing, orchestrates the full run sequence.
173
+ ├── config.py # API key storage, retrieval, and reset logic.
174
+ ├── display.py # All Rich terminal UI rendering, panels, banner, and styled output.
175
+ ├── gemini.py # Assembles the prompt and handles all Gemini API communication.
176
+ ├── interview.py # Runs the 3-phase question flow and formats answers for Gemini.
177
+ ├── LICENSE # Contains the project's open-source license.
178
+ ├── prompt.py # Stores the system prompt as a single string constant.
179
+ ├── pyproject.toml # Package metadata, dependencies, and CLI entry point definition.
180
+ ├── README.md # The project's primary documentation file.
181
+ ├── scanner.py # Walks the project directory, filters sensitive and binary files,
182
+ | enforces token budget, formats codebase for Gemini.
183
+ ├── writer.py # Writes or updates README.md with collision detection and output cleaning.
184
+ └── __init__.py # Marks the directory as a Python package.
185
+
186
+ ```
187
+
188
+ ### Critical Execution Path
189
+
190
+ This sequence describes the critical path from a user running `ichiran` to the final `README.md` being generated:
191
+
192
+ 1. User runs `ichiran` in terminal.
193
+ 2. `cli.main()` is called via the `pyproject.toml` entry point.
194
+ 3. `argparse` parses `--reset` or `--version` flags if present.
195
+ 4. `display.print_banner()` renders the ASCII logo panel.
196
+ 5. `config.load_api_key()` checks `~/.config/ichiran/config.json` for a saved key.
197
+ 6. `display.print_info_box()` renders the info panel with running directory and API key status.
198
+ 7. `config.get_api_key()` prompts for key if not found, saves via `config.save_api_key()`.
199
+ 8. `interview.run_interview()` starts the phase controller.
200
+ 9. `interview.run_phase_one()` asks Q1-Q5 via `input()` and collects answers into a dict.
201
+ 10. `interview._ask_layer_prompt()` shows the styled layer options panel.
202
+ 11. `interview._parse_layer_intent()` parses the user response.
203
+ 12. `interview.run_phase_two()` asks Q6-Q16 if layer 2 was chosen.
204
+ 13. `interview.run_phase_three()` asks Q17-Q30 if layer 3 was chosen.
205
+ 14. `run_interview()` returns the complete answers dict or `None` if user quit.
206
+ 15. `gemini.generate_readme()` is called with the answers dict.
207
+ 16. `config.get_api_key()` loads the saved API key.
208
+ 17. `genai.Client()` initialises the Gemini client.
209
+ 18. `scanner.scan_codebase()` walks the current directory with `os.walk()`.
210
+ 19. `scanner` applies `IGNORED_DIRS`, `ALWAYS_IGNORE`, `IGNORED_FILES`, `IGNORED_SUFFIXES`, `IGNORED_PREFIXES`, `TEXT_EXTENSIONS` whitelist, and `is_binary_file()` check.
211
+ 20. `scanner` reads each allowed file with `filepath.read_text()`.
212
+ 21. `scanner.format_codebase_for_prompt()` assembles priority files first then remaining files within token budget.
213
+ 22. `interview.format_answers()` converts the answers dict into a labeled plain text string.
214
+ 23. The full prompt is assembled combining `formatted_answers` and `codebase_context`.
215
+ 24. `gemini._call_with_retry()` sends the prompt to Gemini with the system prompt as system instruction.
216
+ 25. `client.models.generate_content()` makes the API call to Gemini 2.5 Flash.
217
+ 26. On 429 error, exponential backoff waits and retries up to 3 times.
218
+ 27. `response.text` is returned to `generate_readme()`.
219
+ 28. `writer.write_readme()` receives the generated markdown.
220
+ 29. `writer._clean_output()` finds the first top-level heading and strips everything before it.
221
+ 30. If `README.md` exists, user is prompted to overwrite, append, or cancel.
222
+ 31. `Path.write_text()` writes the final `README.md` to the current directory.
223
+ 32. `cli.main()` calls `display.print_success()` with "Done. Your README is ready."
224
+
225
+ ### Component Communication Model
226
+
227
+ All modules communicate via direct Python function calls and return values. The only external communication is an outbound HTTPS call to the Gemini API at `generativelanguage.googleapis.com` via the `google-genai` SDK. Rich display functions from `display.py` are called throughout all modules for consistent terminal output. There is no inter-process communication, message queue, or shared database communication within the application itself.
228
+
229
+ ### Design Decision Log
230
+
231
+ 1. **API key stored in `~/.config/ichiran/config.json` instead of per-project `.env` files:** This allows the user to set their Gemini API key once and use it across all projects without re-entering it each time, improving the user experience for a global CLI tool.
232
+ 2. **Codebase injected directly into the Gemini prompt instead of summarising it:** This approach significantly reduces the risk of hallucination and ensures that the generated README accurately reflects the actual code and structure, rather than relying solely on the developer's memory or description.
233
+ 3. **Progressive 3-phase interview with optional depth layers:** This design prevents user overwhelm by breaking down the extensive questionnaire into manageable phases. Phase 1 provides a publishable draft, allowing users to choose additional depth only if needed for comprehensive documentation.
234
+ 4. **`QUIT_SENTINEL` pattern for quit handling:** This allows for a clear quit confirmation while preserving any answers already collected. It cleanly signals to `cli.py` to cancel README generation without losing previously entered data.
235
+ 5. **Plain text format for answers sent to Gemini instead of JSON or TOML:** This was chosen to reduce token count and because Gemini generally handles labeled plain text more effectively for this specific use case, minimizing parsing errors or misinterpretations.
236
+ 6. **`SKIP` and `TLDR` are distinct keywords:** `SKIP` stores nothing for a given question, instructing Gemini to infer entirely from the codebase. `TLDR` sends a generic placeholder answer, providing Gemini with an explicit fallback signal for inference, which can be useful when specific details are known but concise.
237
+ 7. **`TEXT_EXTENSIONS` whitelist in `scanner`:** Blocks binary files from being sent to Gemini by default, without relying solely on extension matching. The `is_binary_file()` null-byte sniff acts as an additional safety net.
238
+ 8. **Priority file bucketing before token budget loop:** Ensures key files like `cli.py`, `pyproject.toml` always appear in the prompt even on large codebases, preventing important architectural context from being excluded due to token budget starvation.
239
+ 9. **All terminal output routed through `display.py` Rich functions:** Ensures consistent styling across all modules and centralizes UI management, making it easy to restyle the entire terminal interface from one file.
240
+
241
+ ## Security
242
+
243
+ ### Data Handling and Storage
244
+
245
+ Ichiran handles the **Gemini API key** as its only sensitive data. This key is stored in plaintext JSON at `~/.config/ichiran/config.json` on the user's local machine. The security of this key relies on the operating system's file permissions for the user's home directory. Ichiran does not handle passwords, personally identifiable information (PII), financial data, or session state.
246
+
247
+ ### Authentication Model
248
+
249
+ There is no authentication or authorisation model within Ichiran itself. It operates as a local CLI tool, and access to its functionality is entirely controlled by the operating system user running the application. The only credential involved is the Gemini API key, which is read by `config.get_api_key()` at runtime to authenticate requests to the Google Gemini API.
250
+
251
+ ### Network Exposure
252
+
253
+ Ichiran is a local-only application. It does not open any inbound network ports, run a server, or expose any services to the local area network (LAN) or the internet. Its only network interaction is a single outbound HTTPS call to the Google Gemini API at `generativelanguage.googleapis.com` to facilitate README generation.
254
+
255
+ ### Safe to Commit / Never Commit
256
+
257
+ **Safe to commit:**
258
+ * All application source code files (`.py`)
259
+ * `pyproject.toml`
260
+ * `LICENSE`
261
+ * `README.md` (the generated output, and this documentation itself)
262
+
263
+ **Never commit:**
264
+ Files listed in `.gitignore` should never be committed to the repository. This includes:
265
+ * Python-generated files (`__pycache__/`, `*.py[oc]`, `build/`, `dist/`, `wheels/`, `*.egg-info`)
266
+ * Virtual environments (`.venv`, `.env.local`)
267
+ * `uv` package lock files (`.python-version`, `uv.lock`)
268
+ * Any other files containing credentials, secrets, or local environment variables (e.g., your Gemini API key, `.env` files).
269
+
270
+ ### `.gitignore` Contents
271
+
272
+ ```
273
+ # Python-generated files
274
+ __pycache__/
275
+ *.py[oc]
276
+ build/
277
+ dist/
278
+ wheels/
279
+ *.egg-info
280
+ .ruff_cache/
281
+
282
+ # Virtual environments
283
+ .venv
284
+ .env.local
285
+
286
+ # uv packages
287
+ .python-version
288
+ uv.lock
289
+
290
+ # OS / Editors
291
+ .DS_Store
292
+ Thumbs.db
293
+ .idea/
294
+ .vscode/
295
+ ```
296
+
297
+ ## Deployment
298
+
299
+ Ichiran is a local-only CLI tool. It is not containerized, and there are no differences between local development and production environments. Users install it via `pip install ichiran` and run `ichiran` in their project directory. No production-specific setup steps are required beyond the initial installation.
300
+
301
+ ## Troubleshooting
302
+
303
+ ### `ModuleNotFoundError: No module named 'google'`
304
+ **Cause:** Required Python dependencies, specifically the `google-genai` library, are not installed or are not accessible in your Python environment.
305
+ **Fix:**
306
+ ```bash
307
+ pip install ichiran
308
+ ```
309
+
310
+ ### `google.genai.errors.ClientError: 429 RESOURCE_EXHAUSTED`
311
+ **Cause:** You have exceeded the free tier quota for the Gemini API.
312
+ **Fix:**
313
+ Wait until midnight Pacific time for your quota to reset. Alternatively, generate a fresh API key at `aistudio.google.com/apikey` and clear your saved key by running:
314
+ ```bash
315
+ ichiran --reset
316
+ ```
317
+ Then, re-run `ichiran` and enter the new API key when prompted.
318
+
319
+ ### `RuntimeError: Gemini rate limit hit after all retries. Wait a few minutes and try again, or use a different API key.`
320
+ **Cause:** The daily free tier limit for the Gemini API has been exhausted, even after Ichiran's internal retry logic.
321
+ **Fix:**
322
+ Wait for the daily quota to reset (typically at midnight Pacific time). If you need to proceed immediately, generate a fresh API key at `aistudio.google.com/apikey` and reset your current key:
323
+ ```bash
324
+ ichiran --reset
325
+ ```
326
+ Then, re-run `ichiran` and enter the fresh API key.
327
+
328
+ ## Contributing
329
+
330
+ Yes, Ichiran is open to contributions! We welcome developers to help improve the tool.
331
+
332
+ **Branching Strategy:**
333
+ Fork the repository, then create a feature branch from `main` for your changes.
334
+
335
+ **Pull Request Process:**
336
+ 1. Open a Pull Request (PR) against the `main` branch.
337
+ 2. Provide a clear and concise description of your changes.
338
+ 3. Ensure each PR focuses on a single feature or bug fix.
339
+
340
+ **Code Style:**
341
+ Adhere to PEP8 standards. Before submitting a PR, run a linter like `ruff` to ensure your code complies with the project's style guidelines.
342
+
343
+ **Bug Reporting:**
344
+ Report bugs via GitHub Issues at [https://github.com/ushiecodes/ichiran/issues](https://github.com/ushiecodes/ichiran/issues). Please include:
345
+ * The exact error message.
346
+ * Your operating system.
347
+ * Your Python version.
348
+ * Detailed steps to reproduce the bug.
349
+
350
+ **Feature Requests:**
351
+ Submit feature requests via GitHub Issues. Describe the problem your proposed feature solves, rather than just the solution itself.
352
+
353
+ ## License & Credits
354
+
355
+ This project is licensed under the **MIT License**.
356
+
357
+ **Maintainer:**
358
+ Utkarsh Kamat
359
+ * Email: work.utkarshkamat@gmail.com
360
+ * GitHub: [ushiecodes](https://github.com/ushiecodes)
361
+
362
+ **Third-party Libraries:**
363
+ Ichiran uses the following third-party libraries, installed via `pip` and listed in `pyproject.toml`, each under its respective open-source license:
364
+ * `google-genai` (Apache 2.0 License)
365
+ * `python-dotenv` (BSD License)
366
+ * `platformdirs` (MIT License)
367
+ * `rich` (MIT License)
368
+ * `pip-audit` (Apache 2.0 License)
369
+ * `pyasn1` (BSD 3-Clause License)
370
+ * `pathspec` (MIT License)