Skip to content

Commit 08b0900

Browse files
bmolodanclaude
bmolodan
and
claude
committed
docs: add INSTALL.md (from-source guide) and link it from README
Adds a step-by-step source-install guide covering Python 3.12+ setup via a version manager (pyenv / uv / pyenv-win), editable install, endpoint configuration, and the --max-retries / --disable-thinking settings (persisted and per-run). Links it from the README install section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent d0cdcf0 commit 08b0900

2 files changed

Lines changed: 224 additions & 0 deletions

File tree

‎INSTALL.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Installing CodeWiki from Source
2+
3+
This guide walks through installing CodeWiki from a source checkout, including
4+
setting up the required Python version with a version manager.
5+
6+
## Prerequisites
7+
8+
- **Python 3.12+** — required (`pyproject.toml` sets `requires-python = ">=3.12"`;
9+
`pip install` refuses on older interpreters). See
10+
[Step 1](#1-install-python-312-with-a-version-manager) if you don't have it.
11+
- **Git**
12+
- **Node.js** — *optional*, only for Mermaid diagram validation. Skip it and set
13+
`MERMAID_VALIDATE=0` to disable validation (PythonMonkey-based validation is
14+
auto-disabled on Python 3.12+ regardless).
15+
16+
---
17+
18+
## 1. Install Python 3.12+ with a version manager
19+
20+
Using a version manager keeps CodeWiki's Python isolated from your system Python.
21+
Pick the one for your platform.
22+
23+
### Option A — pyenv (macOS / Linux)
24+
25+
```bash
26+
# Install pyenv (macOS)
27+
brew install pyenv
28+
29+
# Install pyenv (Linux)
30+
curl -fsSL https://pyenv.run | bash
31+
32+
# Add pyenv to your shell (zsh shown; use ~/.bashrc for bash), then restart the shell
33+
cat >> ~/.zshrc <<'EOF'
34+
export PYENV_ROOT="$HOME/.pyenv"
35+
export PATH="$PYENV_ROOT/bin:$PATH"
36+
eval "$(pyenv init -)"
37+
EOF
38+
exec "$SHELL"
39+
40+
# Install and select a 3.12 interpreter
41+
pyenv install 3.12.7
42+
pyenv shell 3.12.7 # this shell only (or: pyenv local 3.12.7 inside the repo)
43+
44+
# Verify
45+
python --version # -> Python 3.12.7
46+
```
47+
48+
### Option B — uv (macOS / Linux / Windows)
49+
50+
[uv](https://docs.astral.sh/uv/) can fetch a standalone Python build for you:
51+
52+
```bash
53+
# Install uv (macOS/Linux)
54+
curl -LsSf https://astral.sh/uv/install.sh | sh
55+
# Install uv (Windows PowerShell)
56+
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
57+
58+
uv python install 3.12
59+
```
60+
61+
### Option C — pyenv-win (Windows)
62+
63+
```powershell
64+
# Install pyenv-win (PowerShell)
65+
Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1 -OutFile ./install-pyenv-win.ps1
66+
&"./install-pyenv-win.ps1"
67+
# Restart the terminal, then:
68+
pyenv install 3.12.7
69+
pyenv shell 3.12.7
70+
python --version
71+
```
72+
73+
---
74+
75+
## 2. Clone the repository
76+
77+
```bash
78+
git clone https://github.com/FSoft-AI4Code/CodeWiki.git
79+
cd CodeWiki
80+
```
81+
82+
> Installing from a fork? Clone that instead and optionally check out a branch:
83+
> ```bash
84+
> git clone https://github.com/<your-user>/CodeWiki.git
85+
> cd CodeWiki
86+
> git checkout <branch>
87+
> ```
88+
89+
## 3. Create and activate a virtual environment
90+
91+
Create the venv with your 3.12 interpreter (from Step 1).
92+
93+
**pyenv / system 3.12:**
94+
```bash
95+
python3.12 -m venv .venv # or: python -m venv .venv (if pyenv shell is 3.12)
96+
source .venv/bin/activate # Windows: .venv\Scripts\activate
97+
```
98+
99+
**uv:**
100+
```bash
101+
uv venv --python 3.12
102+
source .venv/bin/activate # Windows: .venv\Scripts\activate
103+
```
104+
105+
## 4. Install CodeWiki
106+
107+
```bash
108+
# Editable install — source edits take effect without reinstalling
109+
pip install -e .
110+
```
111+
112+
This pulls every runtime dependency from `pyproject.toml` (tree-sitter parsers,
113+
pydantic-ai, openai, litellm, fastapi, …) and installs the `codewiki` CLI.
114+
115+
For development (tests, linters — adds pytest/black/ruff):
116+
```bash
117+
pip install -e ".[dev]"
118+
```
119+
120+
> Prefer uv for installs? `uv pip install -e .` works the same way.
121+
122+
## 5. Verify
123+
124+
```bash
125+
codewiki --version
126+
```
127+
128+
---
129+
130+
## 6. Configure an LLM provider
131+
132+
Settings are persisted to `~/.codewiki/config.json` and the API key is stored in
133+
your OS keychain, both via `codewiki config set`. Every flag is optional and only
134+
updates the keys you pass, so you can set things incrementally.
135+
136+
### Configure the endpoint
137+
138+
The endpoint is defined by `--provider` + `--base-url` (+ `--api-key`). Pick the
139+
provider that matches your server:
140+
141+
```bash
142+
# Local OpenAI-compatible server (vLLM / llama.cpp / LM Studio / Ollama, e.g. Qwen)
143+
codewiki config set \
144+
--provider openai-compatible \
145+
--base-url http://localhost:8000/v1 \
146+
--api-key not-needed \
147+
--main-model qwen3.6-35b-a3b \
148+
--cluster-model qwen3.6-35b-a3b \
149+
--fallback-model qwen3.6-35b-a3b
150+
```
151+
152+
- `--base-url` — the OpenAI-compatible endpoint. For local servers this is
153+
usually `http://<host>:<port>/v1`. Update just this flag if your server moves:
154+
`codewiki config set --base-url http://localhost:1234/v1`.
155+
- `--api-key` — stored in the keychain. Local servers that don't check it still
156+
need a non-empty value (`not-needed` works).
157+
- `--main-model` / `--cluster-model` / `--fallback-model` — model IDs as your
158+
endpoint advertises them (see your server's `/v1/models`).
159+
160+
Other providers set the endpoint differently (`--provider anthropic|bedrock|
161+
azure-openai|atlas-cloud`, or `claude-code` / `codex` subscription mode which need
162+
no base URL or key). See the [README](README.md) for full per-provider examples.
163+
164+
### New tuning parameters
165+
166+
These were added for running against local / hybrid-thinking models and can be
167+
set persistently here, or overridden per run on `generate` (next step).
168+
169+
```bash
170+
# Tool-call retries per agent before giving up (default: 3).
171+
# Raise it for weaker/local models that emit malformed tool arguments.
172+
codewiki config set --max-retries 5
173+
174+
# Reasoning/thinking mode. Off by default (hybrid-thinking models such as Qwen3
175+
# emit <think> blocks that corrupt tool calls). Injected as
176+
# chat_template_kwargs.enable_thinking=false; skipped for first-party APIs
177+
# (OpenAI/Azure/Bedrock/Anthropic) that reject unknown fields.
178+
codewiki config set --disable-thinking # default
179+
codewiki config set --enable-thinking # opt back in (leave thinking on)
180+
```
181+
182+
| Setting | Flag(s) | Default | Purpose |
183+
|---------|---------|---------|---------|
184+
| Max retries | `--max-retries N` (N ≥ 1) | `3` | Tool-call self-correction attempts per agent |
185+
| Thinking mode | `--disable-thinking` / `--enable-thinking` | disabled | Turn hybrid-model reasoning off/on |
186+
187+
> Non-CLI (web app / MCP) callers can also set thinking via the `DISABLE_THINKING`
188+
> environment variable (`true`/`false`, default `true`).
189+
190+
### Review and validate
191+
192+
```bash
193+
codewiki config show # print current config (API key masked)
194+
codewiki config validate # checks config + tests endpoint connectivity
195+
```
196+
197+
## 7. Generate documentation
198+
199+
```bash
200+
cd /path/to/your/repo
201+
codewiki generate --verbose # output written to ./docs
202+
```
203+
204+
The tuning parameters above can be overridden for a single run (these take
205+
precedence over the persisted config, which is otherwise used):
206+
207+
```bash
208+
codewiki generate --max-retries 5 --enable-thinking --verbose
209+
```
210+
211+
---
212+
213+
## Troubleshooting
214+
215+
- **`pip install` fails with a Python version error** — your active interpreter is
216+
older than 3.12. Re-check Step 1 (`python --version` inside the activated venv).
217+
- **Mermaid validation warnings / Node.js errors** — `export MERMAID_VALIDATE=0`
218+
to disable diagram validation.
219+
- **Clean reinstall** — `pip uninstall codewiki`, or simply delete `.venv` and
220+
redo Steps 3–4.
221+
222+
For architecture and contribution details, see [DEVELOPMENT.md](DEVELOPMENT.md).

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git
4646
codewiki --version
4747
```
4848

49+
> Prefer a source checkout (editable install, virtualenv, Python version-manager setup)? See **[INSTALL.md](INSTALL.md)** for a step-by-step guide, including how to configure the endpoint and the `--max-retries` / `--disable-thinking` options.
50+
4951
### 2. Configure Your Environment
5052

5153
CodeWiki supports multiple LLM providers: **OpenAI-compatible**, **Atlas Cloud**, **Anthropic**, **AWS Bedrock**, **Azure OpenAI**, plus subscription mode via **Claude Code** and **Codex** CLIs (no API key required).

0 commit comments

Comments
 (0)