Metadata-Version: 2.4
Name: codewiki
Version: 0.5.1
Summary: Code wiki platform with AST graph analysis, GraphRAG, SQLite/PostgreSQL storage, and LiteLLM.
Author-email: PorunC <09982.misaka@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/PorunC/CodeWiki
Project-URL: Repository, https://github.com/PorunC/CodeWiki
Project-URL: Issues, https://github.com/PorunC/CodeWiki/issues
Keywords: code-wiki,graphrag,fastapi,llm,documentation,postgresql,pgvector
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: graspologic>=3.4.4; python_version < "3.13"
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: litellm>=1.60.0
Requires-Dist: mermaid-parser-py>=0.0.4
Requires-Dist: networkx>=3.4.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: psycopg[binary]>=3.2.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: sqlalchemy>=2.0.35
Requires-Dist: tqdm>=4.67.0
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: tree-sitter-c>=0.24.2
Requires-Dist: tree-sitter-c-sharp>=0.23.5
Requires-Dist: tree-sitter-cpp>=0.23.4
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: uvicorn[standard]>=0.34.0
Provides-Extra: dev
Requires-Dist: mypy>=1.14.0; extra == "dev"
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: license-file

# CodeWiki

[简体中文](docs/README.zh-CN.md) | [Usage Guide](docs/usage.md) | [Changelog](docs/changelog.md)

CodeWiki is a single-user code intelligence platform for AST-based repository analysis,
GraphRAG retrieval, source-grounded wiki generation, and LiteLLM-powered Q&A.

## Screenshots

![CodeWiki wiki page](docs/img/wiki.png)

![CodeWiki graph explorer](docs/img/graph.png)

## Highlights

- Analyze Python, TypeScript/TSX, JavaScript/JSX, Java, Go, Rust, C, C++, and C#.
- Build deterministic code graphs for imports, definitions, calls, routes, inheritance,
  source references, and configuration usage.
- Generate DeepWiki-style catalogs and pages with source citations, diagrams,
  translations, incremental updates, and browser-side exports.
- Ask GraphRAG-grounded questions through the Web UI, CLI, HTTP API, or MCP server.
- Use SQLite by default, or PostgreSQL with full-text search and optional pgvector
  vector search.

## Quick Start

Install from PyPI:

```bash
pip install codewiki
codewiki serve
```

Open `http://127.0.0.1:8000`, register a repository, run analysis, then generate a
wiki or ask questions.

Run with Docker Compose:

```bash
docker compose up --build
```

The packaged Python app includes the built frontend. A source checkout is only needed
for development or Docker-based local runs.

## Common Commands

```bash
codewiki repos add . --name my-repo
codewiki analyze .
codewiki graphrag build . --embeddings
codewiki wiki catalog .
codewiki wiki pages .
codewiki ask --repo my-repo "How does the main workflow fit together?"
codewiki mcp
```

Most repository arguments accept an id, id prefix, registered name, path, or Git URL.
Use `--json` for machine-readable output.

## Configuration

CodeWiki defaults to SQLite:

```bash
CODEWIKI_DATABASE_URL=sqlite+aiosqlite:///./data/codewiki.sqlite3
```

PostgreSQL is also supported:

```bash
CODEWIKI_DATABASE_URL=postgresql+psycopg://codewiki:codewiki@localhost:5432/codewiki
```

Configure LLM profiles with `codewiki config` or `.env`:

```bash
codewiki config
codewiki config --set CODEWIKI_LLM__DEFAULT__MODEL=openai/gpt-4.1
codewiki config --profile qa --model openai/gpt-4.1 --api-key "$OPENAI_API_KEY"
```

## Documentation

- [Usage Guide](docs/usage.md): installation, Docker, database setup, wiki workflow,
  LLM profiles, CLI, MCP, HTTP API, and supported languages.
- [Design Notes](docs/design.md): architecture and feature design.
- [PostgreSQL Compatibility Design](docs/postgres-compatibility-design.md): storage
  compatibility, PostgreSQL FTS, and pgvector design.
- [Benchmarking Guide](docs/benchmarking.md) and
  [Benchmark Report](docs/benchmark-report-2026-05-22.md): benchmark workflow and
  current results.
- [Changelog](docs/changelog.md): release history.

## Development

```bash
make install
make start
make lint
make typecheck
make test
make build
```

Default local URLs:

- Backend: `http://127.0.0.1:8000`
- Frontend: `http://127.0.0.1:5173`

### Python Typing

Python type checking uses `mypy` with a gradual configuration in `pyproject.toml`.
New public service, repository, API helper, and CLI helper functions should include
explicit parameter and return types. Prefer dataclasses, Pydantic models, `TypedDict`,
or `Protocol` over broad `dict[str, Any]` when data crosses module boundaries. Keep
`Any` near integration edges such as LLM JSON payloads, SQLAlchemy JSON columns, and
third-party parser output.

## License

MIT
