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 +21 -0
- ichiran-0.1.0/PKG-INFO +370 -0
- ichiran-0.1.0/README.md +339 -0
- ichiran-0.1.0/pyproject.toml +69 -0
- ichiran-0.1.0/setup.cfg +4 -0
- ichiran-0.1.0/src/ichiran/__init__.py +1 -0
- ichiran-0.1.0/src/ichiran/__main__.py +4 -0
- ichiran-0.1.0/src/ichiran/cli.py +69 -0
- ichiran-0.1.0/src/ichiran/config.py +45 -0
- ichiran-0.1.0/src/ichiran/display.py +142 -0
- ichiran-0.1.0/src/ichiran/gemini.py +58 -0
- ichiran-0.1.0/src/ichiran/interview.py +1052 -0
- ichiran-0.1.0/src/ichiran/prompt.py +182 -0
- ichiran-0.1.0/src/ichiran/scanner.py +213 -0
- ichiran-0.1.0/src/ichiran/writer.py +51 -0
- ichiran-0.1.0/src/ichiran.egg-info/PKG-INFO +370 -0
- ichiran-0.1.0/src/ichiran.egg-info/SOURCES.txt +28 -0
- ichiran-0.1.0/src/ichiran.egg-info/dependency_links.txt +1 -0
- ichiran-0.1.0/src/ichiran.egg-info/entry_points.txt +2 -0
- ichiran-0.1.0/src/ichiran.egg-info/requires.txt +10 -0
- ichiran-0.1.0/src/ichiran.egg-info/top_level.txt +1 -0
- ichiran-0.1.0/tests/test_cli.py +96 -0
- ichiran-0.1.0/tests/test_config.py +101 -0
- ichiran-0.1.0/tests/test_display.py +51 -0
- ichiran-0.1.0/tests/test_gemini.py +114 -0
- ichiran-0.1.0/tests/test_integration.py +30 -0
- ichiran-0.1.0/tests/test_interview.py +237 -0
- ichiran-0.1.0/tests/test_packaging.py +17 -0
- ichiran-0.1.0/tests/test_scanner.py +117 -0
- ichiran-0.1.0/tests/test_writer.py +58 -0
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
|
+

|
|
37
|
+

|
|
38
|
+

|
|
39
|
+

|
|
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)
|