benmaster82-Kwipu

repository

loading code, commits, and activity

repositories

loading repo index

benmaster82-Kwipu — gitlawb

#1	# Contributing to Kwipu
#2
#3	Thanks for your interest in contributing. This guide will help you get started.
#4
#5	## Getting Started
#6
#7	```bash
#8	git clone https://github.com/benmaster82/Kwipu.git
#9	cd Kwipu
#10	pip install -r requirements.txt
#11	```
#12
#13	Make sure you have [Ollama](https://ollama.ai/) installed and running with at least one model:
#14
#15	```bash
#16	ollama pull qwen2.5:3b
#17	ollama pull nomic-embed-text
#18	```
#19
#20	## Project Overview
#21
#22	Kwipu is a local Graph RAG system. The codebase is intentionally small:
#23
#24	- `geode_graph.py` - Main application (engine, retrievers, CLI, file watcher)
#25	- `lang_config.py` - Multilingual support (stopwords, relation patterns, date extraction)
#26	- `knowledge_base/examples/` - Sample notes for testing
#27
#28	## How to Contribute
#29
#30	1. Open an issue first if you want to discuss an approach before writing code.
#31	2. Fork the repo and create a branch from `main`.
#32	3. One feature per PR. Small, focused PRs get reviewed faster.
#33	4. Test with real notes. If possible, test with an actual Obsidian vault or a set of interconnected markdown files.
#34	5. Write in English. Code, comments, commit messages, and documentation should all be in English.
#35
#36	## Areas Where Help is Needed
#37
#38	### Retriever Attribution Logging
#39	Log which retriever (vector, BM25, temporal, synonym) contributed context for each answer. This helps users understand why the system gave a specific response and makes tuning easier.
#40
#41	### Evaluation Set
#42	Build a categorized test suite with question-answer pairs:
#43	- Exact-source questions (answer must cite a specific note)
#44	- Graph traversal questions (requires 2+ edges)
#45	- Temporal questions (depends on dates)
#46	- Negative questions (vault doesn't have the answer)
#47
#48	### Provenance Inspector
#49	Surface the chain: answer claim -> cited note -> heading/block -> extracted entity/edge. This lets users correct bad triples without the system being a black box.
#50
#51	### Telegram Bot
#52	Query the knowledge base remotely via Telegram. Should work as a separate module that imports the engine.
#53
#54	### Incremental Updates on Modification
#55	Currently, modifying a file triggers a full graph rebuild. Implementing delete-then-reinsert for modified files would make the system much faster on large vaults.
#56
#57	## Code Style
#58
#59	- Keep it simple. This is a local-first tool, not an enterprise platform.
#60	- No unnecessary abstractions. If a function is only used once, it probably doesn't need to be extracted.
#61	- Comments should explain "why", not "what".
#62	- Use type hints on function signatures.
#63
#64	## Commit Messages
#65
#66	Use short, descriptive commit messages:
#67
#68	```
#69	Add retriever attribution logging
#70	Fix BOM handling in frontmatter parser
#71	Update build time estimates in README
#72	```
#73
#74	## Running the Project
#75
#76	```bash
#77	# Standard mode
#78	python geode_graph.py
#79
#80	# Fast mode (no synonym retriever)
#81	python geode_graph.py --fast
#82
#83	# With model override
#84	python geode_graph.py --llm-model qwen2.5:7b
#85	```
#86
#87	## Questions?
#88
#89	Open an issue or start a discussion on the repo. We're happy to help.
#90

z6MkqRzA/benmaster82-Kwipu