> For the complete documentation index, see [llms.txt](https://open-papertrade.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://open-papertrade.gitbook.io/docs/contributing/contributing.md).

# Contributing Guide

We welcome contributors at all experience levels. This page is a lightweight overview; the authoritative source is [`CONTRIBUTING.md`](https://github.com/) in the repo root.

## Where to start

Some good first contributions, roughly by effort:

<table><thead><tr><th width="180">Effort</th><th>Ideas</th></tr></thead><tbody><tr><td><strong>Small</strong></td><td>• Fix typos, improve error messages<br>• Add sample questions to the Filings UI<br>• Improve mobile responsiveness of a specific page<br>• Add a keyboard shortcut</td></tr><tr><td><strong>Medium</strong></td><td>• Grow the Filings eval gold sets (target 30 retrieval, 40 answer)<br>• Add a new backtesting indicator or pattern<br>• Improve the chunker (table-aware, sentence-boundary-snapping)<br>• Add a new LLM provider adapter</td></tr><tr><td><strong>Large</strong></td><td>• Migrate the vector store to pgvector (see IDEA.md §16)<br>• Add streaming responses to <code>/ask/</code><br>• Fine-tune a domain-adapted embedding model on filings text<br>• Build a Langfuse / Phoenix tracing integration</td></tr></tbody></table>

## Development workflow

### 1. Fork + clone

```bash
git clone https://github.com/<your-fork>/Open-Papertrade.git
cd Open-Papertrade
git remote add upstream https://github.com/Open-Papertrade/Open-Papertrade.git
```

### 2. Set up as usual

Follow [Installation](/docs/getting-started/installation.md) — venv, deps, `.env`, migrations, both dev servers.

### 3. Branch

```bash
git checkout -b feature/short-description
```

Branch naming:

* `feature/…` — new features
* `fix/…` — bug fixes
* `docs/…` — documentation only
* `refactor/…` — code restructure without behavior change

### 4. Make the change

Keep changes focused. One PR = one concern.

### 5. Test locally

Run the app end-to-end. If your change touches the filings retrieval or QA layer:

```bash
python manage.py evaluate --hybrid --rerank --out my_change.json
# compare vs. a baseline run before your change
```

Numbers speak louder than intuition.

### 6. Commit + push

```bash
git add <files>
git commit -m "Concise summary of what changed and why"
git push origin feature/short-description
```

Commit messages should describe **why**, not what — the diff already shows what.

### 7. Open a PR

* Reference any related issue.
* Include a "how to verify" section — the exact commands to reproduce.
* If the change is UI-facing, include a screenshot or a short screen-cap.
* If the change is retrieval/eval-facing, include before/after eval numbers.

## Code style

* **Python**: PEP 8, type hints where they help, no over-abstraction. Comments only when the "why" is non-obvious.
* **TypeScript**: strict mode, existing formatting conventions (see the rest of `frontend-ui/`), Tailwind for styles.
* **No AI attribution**: keep commit messages and code comments free of "generated by X" tags.

## The design principles to preserve

If you're touching the AI pipeline, keep the design principles intact:

1. **Refusal over hallucination** — every AI feature has an "I don't know" path.
2. **Measure everything** — new retrieval features come with eval numbers.
3. **Provider-agnostic** — don't hard-code a vendor name in reasoning code.
4. **Traceable citations** — new chunk types must preserve `char_start`/`char_end`.
5. **Explainable retrieval** — prefer NumPy-visible logic to framework calls where possible.

## Reporting bugs

Open an issue with:

* What you tried (exact commands).
* What you expected.
* What actually happened (full error, please).
* Your `LLM_PROVIDER` value (**do not paste your API key**).

## Feature ideas

Big-picture ideas live in `IDEA.md` and `readme/FEATURE_IDEAS.md`. If you have a new idea, open a discussion issue before starting to code — saves both sides time.

## Community

Be kind. Assume good faith. Concise, technical feedback is better than long, vague feedback.

## Related

* [Getting Started → Installation](/docs/getting-started/installation.md) — set up your dev environment.
* [Project Structure](/docs/reference/project-structure.md) — where things live in the codebase.
* [Evaluation Harness](/docs/filings-deep-dive/evals.md) — how to measure retrieval/QA changes.