jpmschweitzer/odysseus
1
0
Fork 0
mirror of https://github.com/pewdiepie-archdaemon/odysseus.git synced 2026-11-12 08:02:20 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(style): improve roadmap and contributing Markdown layout

Browse Source
This commit is contained in:
Alexandre Teixeira
2026-11-11 16:56:17 +00:00
parent a130611340
commit 716e7f1e28
2 changed files with 180 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+100 -75
View File
@@ -1,28 +1,50 @@
# Contributing to Odysseus # Contributing to Odysseus
Thanks for helping. The project is moving quickly, so the best contributions are focused, easy to review, and easy to test. Thanks for helping improve Odysseus. The best contributions are **focused, reviewable, and backed by meaningful validation**.
> [!IMPORTANT]
> **Public pull requests target `dev`, not `main`.** Search existing work before implementing, and follow the current [PR template](.github/pull_request_template.md). Runtime changes require relevant execution evidence, not just a green CI badge.
## At a glance
| Topic | What contributors should do |
| --- | --- |
| **Branch** | Target `dev`; `main` is the curated release branch |
| **Scope** | One coherent change per PR; coordinate larger modularization work through [#4071](https://github.com/odysseus-dev/odysseus/issues/4071) |
| **Validation** | Document commands, results, runtime checks, and anything not tested |
| **Visual changes** | Run the UI, match the existing visual language, and attach screenshots or clips |
| **Review** | Follow the [risk-based maintainer policy](docs/maintainers/changes-and-review.md) and applicable repository protections |
| **Security** | Report vulnerabilities privately using [SECURITY.md](SECURITY.md) |
**Jump to:** [Branches](#branch-model) · [Getting started](#before-you-start) · [Setup](#setup) · [Checks](#running-checks) · [Pull requests](#pull-requests) · [Modularization](#structural-changes-and-modularization) · [Visual changes](#style-and-visual-changes) · [Code conventions](#code-conventions) · [Issue reports](#issue-reports)
---
## Branch model ## Branch model
Odysseus has two branches: | Branch | Purpose |
| --- | --- |
| **`dev`** | Default integration branch and target for every public PR. Work can be in flux. |
| **`main`** | Curated release branch. A [Release Maintainer](docs/maintainers/testing-and-releases.md#release-ownership) promotes a verified `dev` commit. |
- **`dev`** — where all PRs land. Things can be in flux here; the merge button gets used freely. If your PR accidentally targets `main`, use **Edit** on GitHub to change its base to `dev`. Changing the base does not itself require a rebase.
- **`main`** — what users run. Curated and tested by the release's [Release Maintainer](docs/maintainers/testing-and-releases.md#release-ownership). Fast-forwarded to a stable `dev` commit at each release.
**Open your PR against `dev`, not `main`.** The GitHub "base" dropdown defaults to `dev`. If you opened a PR against `main` by accident, click "Edit" on the PR and change the base — no rebase needed. End users cloning the repository land on `dev` by default. To use the curated release branch, run `git checkout main` after cloning.
End-users cloning the repo will land on `dev` by default. To run the curated/stable version: `git checkout main` after clone.
## Before You Start ## Before You Start
- Search existing issues and pull requests before opening a new one. 1. Search [open issues](https://github.com/odysseus-dev/odysseus/issues) and [PRs](https://github.com/odysseus-dev/odysseus/pulls) to avoid duplicate or conflicting work.
- Prefer one bug fix or feature per pull request. 2. Prefer one bug fix, feature, or coherent refactor per PR. Avoid broad rewrites, formatting-only churn, and unrelated file moves.
- Avoid broad rewrites, formatting-only changes, or moving many files unless the issue is specifically about structure. 3. For a feature, open a **Feature Request** first. Big, new-direction, or difficult-to-reverse changes require the documented [product decision process](docs/maintainers/product-and-features.md#feature-proposal-workflow).
- If you want to work on a feature, open a Feature Request issue first. Big features, new directions, and changes that are hard to undo need a product decision before implementation — see [feature proposals](docs/maintainers/product-and-features.md#feature-proposal-workflow). 4. For structural work, coordinate the intended module boundary with maintainers and the [modularization tracker #4071](https://github.com/odysseus-dev/odysseus/issues/4071).
> [!NOTE]
> **Coding agents:** If you use an LLM coding agent, open an issue describing the problem before submitting its PR. Bulk agent-generated submissions that ignore the project's contribution format or visual style may be closed without review, even when the underlying fix is correct.
## Setup ## Setup
Docker is the recommended path for normal testing: <details open>
<summary><strong>Docker (recommended for normal testing)</strong></summary>
```bash ```bash
git clone https://github.com/odysseus-dev/odysseus.git git clone https://github.com/odysseus-dev/odysseus.git
@@ -31,7 +53,10 @@ cp .env.example .env
docker compose up -d --build docker compose up -d --build
``` ```
Manual development uses Python 3.11+: </details>
<details>
<summary><strong>Manual Python development (Python 3.11+)</strong></summary>
```bash ```bash
python3 -m venv venv python3 -m venv venv
@@ -40,11 +65,14 @@ pip install -r requirements.txt
python -m uvicorn app:app --host 127.0.0.1 --port 7000 python -m uvicorn app:app --host 127.0.0.1 --port 7000
``` ```
Windows is not actively tested. Docker on Linux or a Linux/macOS manual install is the safer path for now. </details>
> [!NOTE]
> Native Windows is not actively tested. Docker on Linux or a Linux/macOS manual installation is the safer path for now. Document the environment actually used for testing.
## Running Checks ## Running Checks
Run the smallest relevant checks for your change: Run relevant checks for the affected area. Examples from the existing contributor workflow:
```bash ```bash
python -m pytest python -m pytest
@@ -60,97 +88,94 @@ docker compose up -d --build
docker compose logs --tail=120 odysseus docker compose logs --tail=120 odysseus
``` ```
Mention what you ran in the pull request description. If you could not run a check, say so. > [!IMPORTANT]
> **Report what actually ran.** Include commands, results, and relevant manual/runtime verification in the PR description. If a check was not run, mark it as **not run** and explain the limitation. Passing syntax checks and unit tests do not automatically prove changed behavior works in the running application.
See the [testing and releases handbook](docs/maintainers/testing-and-releases.md) for risk-based validation and isolation requirements.
## Maintainer governance and review guidance ## Maintainer governance and review guidance
For repository roles, product decisions, risk-based approvals, issue triage, independent security reviews, CodeQL findings, and release handoffs, see the [Odysseus maintainer handbook](docs/maintainers/README.md). This complements the contributor requirements below and does not change the branch model or current PR template. The [Odysseus maintainer handbook](docs/maintainers/README.md) is authoritative for repository roles, product decisions, risk-based approvals, issue triage, security review, CodeQL findings, and release handoffs.
> [!NOTE]
> The handbook complements this contributor guide. It does not override the branch model, live GitHub protection rules, or the PR template.
## Pull Requests ## Pull Requests
Good pull requests usually include: Keep PRs **cohesive**. Small, focused changes are the default. A larger, coordinated module decomposition may be appropriate under the criteria below, but unrelated cleanup, formatting, refactors, and behavior changes must not be mixed.
- A short explanation of the bug or feature. | Include in the PR | Why it matters |
- The files or areas changed. | --- | --- |
- Manual test steps or automated test results from running the actual app, not just the test suite. | **Summary and scope** | Explain the problem, intended behavior, and areas changed |
- Screenshots or short recordings for UI changes. | **Linked issue** | Connect the PR to the existing report or approved work, for example `Fixes #123` or `Part of #4071` |
- Links to related issues, for example `Fixes #123`. | **Validation evidence** | Show manual test steps or automated results that exercise the actual behavior |
| **UI evidence, when applicable** | Attach screenshots or short recordings from the running application |
Keep PRs cohesive. Small, focused changes are the default. Larger, coordinated decompositions can be appropriate under the conditions below; unrelated cleanup, formatting, refactors, and behavior changes should not be mixed. | **Limitations** | Clearly identify tests or environments that were not exercised |
> **Auto-generated PRs.** If you are running an LLM agent (Devin, Cursor, OpenHands, Claude Code, etc.) against this repo: please open an issue describing the problem first instead of opening a PR directly. Bulk agent-generated PRs that don't match the project's visual style or contribution format will be closed without review, even when the underlying fix is correct.
For exact required sections and attestations, follow the current [PR template](.github/pull_request_template.md).
### Structural changes and modularization ### Structural changes and modularization
Small, focused PRs remain the default. However, a larger PR may be appropriate when it extracts one coherent responsibility from an oversized module and splitting that extraction across several PRs would create unnecessary conflicts or integration complexity. **One coherent responsibility is the unit of review.** A larger PR can be appropriate when extracting that responsibility from an oversized module is safer or simpler than splitting the work into many conflicting or interdependent PRs.
Before starting structural work: Before implementation and review:
- Review existing issues and PRs, and coordinate the intended boundary with maintainers. Use #4071 for codebase modularization. - **Coordinate:** Read existing issues/PRs and agree on the boundary with maintainers. Use [#4071](https://github.com/odysseus-dev/odysseus/issues/4071) for codebase modularization.
- Keep the change limited to one coherent responsibility or subsystem. Do not combine unrelated rewrites, new features, formatting changes, or opportunistic cleanup. - **Constrain scope:** Keep one subsystem or responsibility per PR. Avoid unrelated features, formatting, and opportunistic cleanup.
- Preserve observable behavior, existing interfaces, import compatibility, persistence contracts, and relevant runtime invariants unless a separate change has been explicitly approved. - **Preserve contracts:** Maintain observable behavior, imports, public interfaces, persistence contracts, and runtime invariants unless an approved issue explicitly scopes a change.
- Provide focused regression tests and runtime validation appropriate to the affected behavior. For frontend changes, include browser validation and screenshots or recordings where rendering may change. - **Validate behavior:** Include targeted regression tests and runtime checks. Frontend work needs browser validation and screenshots or recordings when rendering may change.
- Explain the extraction boundary, compatibility considerations, validation evidence, and any limitations in the PR description. - **Explain tradeoffs:** Describe extraction boundaries, compatibility, validation results, and known limitations in the PR.
There is no arbitrary line-count limit for a well-scoped structural PR. Reviewability, correctness, and integration risk determine whether its scope is acceptable. > [!TIP]
> **Large does not mean broad.** There is no arbitrary line-count limit for a well-scoped extraction. Correctness, reviewability, and integration risk determine whether the scope is acceptable.
**Temporary agent-runtime coordination:** Harness V2 development affects `src/agent_loop.py` and related execution, authorization, orchestration, and context contracts. Unrelated changes to those areas are temporarily frozen and must be coordinated with maintainers. Other modules remain open for contributions. Urgent bug and security reports remain welcome. > [!CAUTION]
> **Temporary Harness V2 coordination boundary:** Unrelated changes to `src/agent_loop.py` and closely related execution, authorization, orchestration, and context contracts are temporarily frozen while Harness V2 is developed and validated. Coordinate such work with maintainers. Other modules remain open, and urgent bug or security reports are welcome.
All changes must follow the existing [risk-based review policy](docs/maintainers/changes-and-review.md), repository protections, and PR template. These contributions remain subject to the [risk-based review policy](docs/maintainers/changes-and-review.md), current repository protections, and PR template.
## Style and visual changes ## Style and visual changes
Odysseus has an intentional visual style. PRs that ignore it will be closed without merge, no matter how correct the underlying code is. Odysseus has an intentional visual language. Changes that ignore it can be closed without merge even when their underlying code is correct.
Before submitting any change that affects what the app looks like — buttons, icons, fonts, colors, spacing, layout, CSS, HTML, SVG, or any `static/js/` module that draws to the DOM — please: For any change affecting buttons, icons, typography, colors, spacing, layout, CSS, HTML, SVG, or JavaScript that renders into the DOM:
1. **Run the app locally** and view the change in a browser. Type-checks and unit tests are not enough. 1. **Run the application locally** and inspect the change in a browser. Type checks and unit tests alone are insufficient.
2. **Attach a screenshot or short clip** of the change in the running app. Add a mobile screenshot too if the change affects mobile. 2. **Attach a screenshot or short clip** from the running app, plus a mobile screenshot when mobile behavior changes.
3. **Match the existing visual language.** Specifically: 3. **Reuse the existing design system:**
- Reuse existing CSS variables (`--red`, `--fg`, `--bg`, `--card`, `--border`, …). Do not introduce new color values, font sizes, or spacing units. - Prefer existing CSS tokens (`--red`, `--fg`, `--bg`, `--card`, `--border`, etc.). Do not introduce parallel colors, type scales, or spacing systems.
- Reuse existing button, input, card, and border classes. Don't invent parallel styling for similar widgets. - Reuse existing button, input, card, and border classes rather than creating duplicate patterns.
- **No Unicode emoji in UI or code.** Use inline SVG (matching the monochrome icon style already in `static/index.html`) or plain text. - Do **not** add Unicode emoji in UI or code. Use inline SVG consistent with `static/index.html` or plain text.
- Monospaced font (`Fira Code`) for primary UI text. Don't override. - Preserve the existing primary monospaced font (`Fira Code`).
- Dark theme is the default; any light-mode work goes through the existing theme system, not hard-coded. - Keep dark mode as the default; route any light-mode work through the existing theme system.
4. **Don't add parallel components.** If a similar widget already exists in the app, extend it instead of writing a new one. 4. **Extend existing components** instead of introducing a parallel component for the same purpose.
If you are unsure whether a change is "visual," it is. Default to attaching a screenshot. > [!IMPORTANT]
> If you are unsure whether a change is visual, assume that it is and provide a screenshot. Visual evidence does not replace behavioral validation.
## Code conventions ## Code conventions
Don't hardcode values that the project already exposes through a constant or a helper. Hardcoded literals drift out of sync, break on non-default deployments, and reintroduce bugs we've already fixed. **Use existing constants and helpers.** Hardcoded duplicates drift, break non-default deployments, and can reintroduce previously fixed issues.
- **Filesystem paths:** never build writable paths from `Path(__file__)...` into the source tree, hardcode `/app/...`, or use a relative `"data/..."` string. Every persisted file and directory has a named constant in `src/constants.py` (for example `AUTH_FILE`, `USER_PREFS_FILE`, `SETTINGS_FILE`, `TTS_CACHE_DIR`, `CHROMA_DIR`). Import and use that named constant; do not re-derive the path locally with `os.path.join(DATA_DIR, "x.json")` or `DATA_DIR / "x.json"`. `DATA_DIR` is the single place that reads `ODYSSEUS_DATA_DIR`, so use it directly only for dynamic paths that have no fixed name (for example per-owner files). If a data file or directory has no constant yet, add one to `src/constants.py`. The source tree is read-only in Docker and `/app/...` does not exist on native runs; guard directory creation so an unwritable path degrades gracefully instead of crashing at import. - **Filesystem paths:** Do not derive writable paths from `Path(__file__)...` into the source tree, hardcode `/app/...`, or use a relative `"data/..."` string. Persisted files and directories have named constants in `src/constants.py`, such as `AUTH_FILE`, `USER_PREFS_FILE`, `SETTINGS_FILE`, `TTS_CACHE_DIR`, and `CHROMA_DIR`. Import those names rather than deriving paths with `os.path.join(DATA_DIR, "x.json")` or `DATA_DIR / "x.json"`. `DATA_DIR` reads `ODYSSEUS_DATA_DIR` and is intended directly only for dynamic paths without fixed names, such as per-owner files. Add a constant when a fixed path does not yet have one. The source tree is read-only in Docker, and `/app/...` does not exist on native runs. Guard directory creation so unwritable paths degrade gracefully rather than crashing at import.
- **Internal API / loopback URLs:** don't hardcode `http://localhost:7000`. Use `internal_api_base()` from `src.constants` (it honors `ODYSSEUS_INTERNAL_BASE` / `APP_PORT`). - **Internal API and loopback URLs:** Do not hardcode `http://localhost:7000`. Use `internal_api_base()` from `src.constants`, which honors `ODYSSEUS_INTERNAL_BASE` and `APP_PORT`.
- **Ports, limits, model lists, and similar:** reuse the existing constant if one exists; if it doesn't and the value is used in more than one place, add a constant rather than copying the literal. - **Ports, limits, and model lists:** Reuse existing constants. When a value is shared by multiple locations and has no constant, add one in `src/constants.py` instead of duplicating a literal. `core/constants.py` is a compatibility re-export, not another source of truth.
If you need a value that has no constant or helper yet, add it to `src/constants.py` (the single source of truth for paths and config; `core/constants.py` only re-exports it for backward compatibility) and import it, rather than repeating a literal across files. **Commits:** Use [Conventional Commits](https://www.conventionalcommits.org) with `type(scope): summary`, for example `fix(search): ...`, `feat(notes): ...`, or `docs(contributing): ...`. Common types include `fix`, `feat`, `refactor`, `docs`, `test`, `chore`, and `ci`. Keep the subject short and imperative, with the motivation in the body when useful.
**Commits:** use [Conventional Commits](https://www.conventionalcommits.org), `type(scope): summary` (e.g. `fix(search): ...`, `feat(notes): ...`, `docs(contributing): ...`). Common types: `fix`, `feat`, `refactor`, `docs`, `test`, `chore`, `ci`. Keep the subject short and imperative; put the "why" in the body when it isn't obvious.
## Issue Reports ## Issue Reports
For bugs, include: | Bug reports should include | Model-serving reports should additionally include |
| --- | --- |
| Installation method (Docker, Python, WSL, etc.) | Backend (Ollama, vLLM, SGLang, llama.cpp, LM Studio, etc.) |
| OS, browser, and device when relevant | Model name |
| Exact reproduction steps | GPU/CPU and operating system |
| Expected versus actual behavior | Cookbook task logs or backend/server logs |
| Relevant logs, screenshots, or terminal output | Relevant backend configuration |
- Install method: Docker, manual Python, WSL, etc. Issues containing only "help", "does not work", or an unexplained screenshot may be closed as not actionable. Start with a reproducible problem or use [Discussions](https://github.com/odysseus-dev/odysseus/discussions) for setup questions.
- OS, browser, and device if relevant.
- Exact steps to reproduce.
- Expected behavior and actual behavior.
- Logs, screenshots, or terminal output.
For model-serving issues, include:
- Backend: Ollama, vLLM, SGLang, llama.cpp, LM Studio, etc.
- Model name.
- GPU/CPU and operating system.
- Cookbook task logs or server logs.
Issues with only "help", "does not work", or a screenshot without context may be closed as not actionable.
## Security ## Security
Do not post secrets, API keys, private logs, personal documents, or public IPs in issues or pull requests. > [!CAUTION]
> **Do not publish secrets.** Keep API keys, sensitive logs, personal documents, and public IP addresses out of public issues and PRs. Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
For security reports, follow [SECURITY.md](SECURITY.md).
ROADMAP.md
+80 -65
View File
@@ -1,102 +1,117 @@
# Roadmap / Help Wanted # Roadmap / Help Wanted
Odysseus is an evolving self-hosted AI workspace. This roadmap highlights the areas where improvements and contributions are most useful. Odysseus is an evolving, self-hosted AI workspace. This roadmap highlights where improvements and contributions are most useful, from reliability and maintainability to product capabilities.
It describes current direction, not a fixed release schedule or a complete issue backlog. Specific implementations should be coordinated through existing issues and pull requests. > [!NOTE]
> **Direction, not a release schedule.** This page is not a complete issue backlog or a promise to deliver every proposal. Implementation scope and priority are coordinated through existing issues, pull requests, and the project's [feature proposal process](docs/maintainers/product-and-features.md).
Contributions target `dev`. The `main` branch is curated for releases. ## At a glance
| Area | Direction | Coordination |
| --- | --- | --- |
| **Stabilization** | Reliability, CI, fresh installs, security, and integrations | [Stabilization & Modularization milestone](https://github.com/odysseus-dev/odysseus/milestone/1) |
| **Modularization** | Clearer module ownership, safer changes, and contributor onboarding | [Canonical tracker #4071](https://github.com/odysseus-dev/odysseus/issues/4071) |
| **Agent runtime** | Active Harness V2 development, with a narrow temporary change freeze | [Coordination in #4071](https://github.com/odysseus-dev/odysseus/issues/4071) |
| **Product improvements** | Local models, research, frontend experience, and operations | [Issues](https://github.com/odysseus-dev/odysseus/issues) and [feature proposals](docs/maintainers/product-and-features.md) |
**Jump to:** [Stabilization](#stabilization-and-reliability) · [Modularization](#modularization-and-maintainability) · [AI and local models](#ai-local-models-and-research) · [Frontend](#frontend-and-user-experience) · [Backend](#backend-and-operations) · [Contributing](#contributing)
---
## Stabilization and reliability ## Stabilization and reliability
Reliable operation across installations, platforms, providers, and supported hardware remains a priority. **Priority:** Make Odysseus dependable across installations, platforms, providers, and supported hardware.
- **CI and validation:** Improve the reliability of automated checks, exact-revision validation, and release confidence. See #5932 and the confirmed docs-only CI regression, #7109. | Workstream | What needs improvement | Tracking |
- **Test quality:** Continue improving deterministic tests, isolation, focused execution, and maintainable test structure. See #2523 and the [testing standard](tests/TESTING_STANDARD.md). | --- | --- | --- |
- **Fresh installations:** Expand smoke-test coverage for native Linux, macOS, Windows, WSL, and Docker. Verify clean startup, health reporting, and graceful handling of unavailable optional services. See #3968. | **CI and validation** | Exact-revision validation, meaningful regression coverage, and release confidence | [#5932](https://github.com/odysseus-dev/odysseus/issues/5932), [#7109](https://github.com/odysseus-dev/odysseus/issues/7109) |
- **Cookbook reliability:** Improve model installation, dependency management, hardware detection, and serving across supported platforms, GPUs, drivers, and execution backends. | **Test quality** | Deterministic tests, isolation, focused execution, and maintainable test structure | [#2523](https://github.com/odysseus-dev/odysseus/issues/2523), [testing standard](tests/TESTING_STANDARD.md) |
- **Email integration:** Resolve remaining Google OAuth regressions, preserve account isolation, and improve cross-provider reliability. See #5637. | **Fresh installations** | Smoke tests for Linux, macOS, Windows, WSL, and Docker; baseline startup and graceful degradation | [#3968](https://github.com/odysseus-dev/odysseus/issues/3968) |
- **Storage integrity:** Investigate upload payloads, database growth, indexing, and file lifecycle without introducing unsafe or destructive cleanup. See #4889. | **Email integration** | Remaining Google OAuth regressions, account isolation, and cross-provider reliability | [#5637](https://github.com/odysseus-dev/odysseus/issues/5637) |
- **Security:** Continue hardening authorization, agent tool execution, prompt-injection boundaries, filesystem access, and handling of untrusted content. | **Storage integrity** | Upload payload growth, indexing, and attachment/file lifecycle | [#4889](https://github.com/odysseus-dev/odysseus/issues/4889) |
- **Integration diagnostics:** Verify provider and optional-service behavior, improve failure reporting, and ensure unavailable dependencies degrade predictably.
Current stabilization work is coordinated through the [Stabilization & Modularization milestone](https://github.com/odysseus-dev/odysseus/milestone/1). Additional reliability priorities:
- **Cookbook:** Improve model installation, dependency management, hardware detection, and model serving across operating systems, GPUs, drivers, shells, Python environments, and supported backends.
- **Security:** Keep strengthening authorization, administrative tools, agent tool execution, prompt-injection boundaries, filesystem access, and untrusted-content handling.
- **Integrations and degraded states:** Audit supported providers and optional services, including ChromaDB, SearXNG, email, and ntfy. Make failures observable and nonessential outages predictable.
> [!TIP]
> Start with an existing, reproducible issue. The [Stabilization & Modularization milestone](https://github.com/odysseus-dev/odysseus/milestone/1) is a curated work queue, not an invitation to implement every item in this roadmap without coordination.
## Modularization and maintainability ## Modularization and maintainability
The goal is to make the codebase easier to navigate, test, review, and extend while preserving existing behavior and compatibility. The goal is **clearer responsibility boundaries and safer development**, not smaller files for their own sake. Changes should preserve behavior, compatibility, and relevant runtime contracts.
The initial CSS extraction and substantial tool-domain decomposition have established a foundation, but responsibility boundaries still need improvement. | Area | Current foundation | Remaining opportunities |
| --- | --- | --- |
| **CSS** | The former `static/style.css` has been split into ordered files under `static/css/` | Improve ownership while preserving the cascade, themes, and responsive layouts |
| **Tools** | Substantial tool-domain extraction has landed | Clarify remaining ownership and preserve compatibility through the existing tool interfaces |
| **Frontend** | Existing feature modules remain in use | Decompose large document, gallery, settings, calendar, and other UI modules around coherent behavior |
| **Backend** | Domain-specific routes and services already exist | Identify safe boundaries in Cookbook routes, persistence, and other tightly coupled modules |
| **Tests** | Taxonomy, focused execution, and structural improvements exist | Align fixtures, helpers, and regression coverage with implementation boundaries |
| **UI infrastructure** | Targeted cleanup is underway | Consolidate tour scaffolding, modal/window positioning, responsive overrides, and obsolete paths |
Current areas of interest: **Canonical coordination:** [Codebase modularization and contributor onboarding, #4071](https://github.com/odysseus-dev/odysseus/issues/4071).
- **Frontend:** Continue focused decomposition of large document, gallery, settings, calendar, and other UI modules. > [!IMPORTANT]
- **CSS:** The former `static/style.css` has been split into ordered files under `static/css/`. Improve maintainability without inadvertently changing cascade order, theme behavior, or responsive layouts. > **Cohesive work is more important than a small line count.** A larger PR may be appropriate for one well-defined decomposition when several smaller PRs would create avoidable conflicts or integration overhead. Coordinate the boundary, avoid unrelated work, and supply regression and runtime evidence. See [CONTRIBUTING.md](CONTRIBUTING.md#structural-changes-and-modularization).
- **Tools:** Continue clarifying ownership within `src/agent_tools/` and related implementations while preserving existing public contracts and compatibility.
- **Backend:** Identify safe boundaries in large Cookbook routes, persistence modules, and feature-specific route handlers.
- **Tests:** Keep test helpers, fixtures, and focused test ownership aligned with the implementation modules they exercise.
- **UI infrastructure:** Reduce duplicated tour scaffolding, fragile modal/window positioning, stale feature flags, and cross-feature coupling.
[#4071](https://github.com/odysseus-dev/odysseus/issues/4071) is the canonical coordination tracker for this work.
Larger PRs can be appropriate for a single coherent decomposition when splitting the work into many smaller PRs would create unnecessary integration complexity. Coordinate the intended boundary before implementation and provide meaningful regression and runtime validation.
### Agent runtime and Harness V2 ### Agent runtime and Harness V2
Harness V2 is under active development. Harness V2 is under active development.
The agent runtime, including `src/agent_loop.py` and closely related execution, authorization, orchestration, and context contracts, is temporarily frozen for unrelated changes while that work is developed and validated. > [!CAUTION]
> **Temporary agent-runtime freeze.** Unrelated changes to `src/agent_loop.py` and closely related execution, orchestration, authorization, and context contracts must be coordinated with maintainers while Harness V2 is developed and validated.
Agent-runtime refactors must be coordinated with maintainers. Urgent bug and security reports remain welcome. >
> This does **not** freeze unrelated application modules. Urgent bug reports and security issues remain welcome. No release date is implied.
This restriction does not apply to unrelated application modules.
## AI, local models, and research ## AI, local models, and research
The following improvements remain areas of product interest. Their exact implementations and priority relative to one another require normal issue triage and product decisions. These are **areas of product interest**, not commitments to a specific implementation or delivery order. Follow normal issue triage and product-decision requirements.
- **Smaller-model agent efficiency:** Reduce unnecessary prompt, tool-schema, skill, memory, and document context overhead. Improve tool selection and behavior with constrained context windows. | Direction | Opportunity |
- **Cookbook SGLang support:** Improve setup and serving across relevant operating systems, hardware, and deployment methods. | --- | --- |
- **Model discovery and ranking:** Recommend appropriate models using architecture, quantization, RAM/VRAM availability, backend support, multimodal requirements, and expected serving reliability. | **Smaller-model agents** | Reduce unnecessary prompt, tool-schema, skill, memory, and document context overhead; improve tool selection for constrained context windows |
- **Deep Research presets:** Explore hardware-appropriate model and parameter configurations for smaller and larger local systems. | **Cookbook and SGLang** | Improve installation and serving across relevant hardware, operating systems, and deployment methods |
- **Cookbook diagnostics:** Expose actionable installation, download, preflight, and serving failures with useful, copyable logs. | **Model discovery** | Rank models by architecture, quantization, RAM/VRAM fit, backend support, multimodal requirements, and expected reliability |
- **Speculative decoding:** Investigate supported draft-model configurations for compatible local backends. Evaluate end-to-end correctness and time to successful output, not throughput alone. | **Deep Research presets** | Explore suitable model and parameter configurations for small, medium, and large local systems |
- **Provider setup and probing:** Improve integration quality for supported local and hosted providers, including endpoint discovery and capability handling. | **Actionable diagnostics** | Expose command output, logs, and next steps for failed downloads, dependencies, preflights, and serving jobs |
| **Speculative decoding** | Investigate compatible draft-model configurations and evaluate end-to-end correctness and time to success |
| **Provider setup** | Improve endpoint discovery, capability checks, and setup for supported local and hosted providers |
## Frontend and user experience ## Frontend and user experience
- Improve document and file editing, window behavior, save/export flows, and image-editing reliability. - **Editors and files:** Improve document/file editing, window behavior, save/export flows, and image-editing reliability.
- Expand agent-assisted workflows for Notes and Todos, including reading, updating, summarizing, and turning information into actionable tasks. - **Notes and Todos:** Expand agent-assisted reading, updates, summarization, and turning information into tasks.
- Improve the mobile gallery and editor experience. - **Mobile:** Improve gallery/editor usability, model setup, and responsive behavior.
- Strengthen keyboard navigation, accessibility, focus behavior, contrast, and reduced-motion support. - **Accessibility:** Strengthen keyboard navigation, focus states, contrast, and reduced-motion support.
- Improve first-run setup, empty states, error messages, and onboarding guidance. - **First run:** Improve setup, hints, empty states, error messages, and onboarding tours without duplicate guidance.
- Improve desktop/mobile CSS maintainability and responsive behavior. - **Self-hosting:** Reduce unnecessary external asset dependencies where practical for offline operation.
- Continue reducing unnecessary external asset dependencies where practical for self-hosted and offline operation.
## Backend and operations ## Backend and operations
- Improve email performance through measured investigation of fetching, caching, attachment handling, searching, and sending. - **Email performance:** Measure fetching, searching, body and attachment loading, caching, sending, and frontend refresh behavior before optimizing.
- Expand regression coverage for provider setup, endpoint probing, and degraded service states. - **Provider reliability:** Expand regression coverage for setup, endpoint probing, and degraded-service behavior.
- Improve task-scheduler defaults, reliability, and operational visibility. - **Task scheduling:** Improve defaults, reliability, and operational visibility.
- Improve backup and recovery guidance for persistent application data. - **Data recovery:** Improve backup and restore guidance and workflows for persistent data.
- Continue reviewing administrative capabilities, sensitive integrations, and their authorization boundaries. - **Administrative security:** Review privileged capabilities and sensitive integrations against their authorization boundaries.
## Not a current priority ## Not a current priority
- Adding more themes without a clear product need. - Additional themes without a demonstrated product need.
- Broad rewrites without demonstrated value. - Broad rewrites or framework migrations without clear, measurable value.
- Framework migrations or architectural changes undertaken solely to reduce file counts. - Changes undertaken solely to reduce file counts.
- Uncoordinated changes to the temporarily frozen agent-runtime contracts. - Uncoordinated changes to temporarily frozen agent-runtime contracts.
---
## Contributing ## Contributing
Before starting work: 1. Read [CONTRIBUTING.md](CONTRIBUTING.md) and search [existing issues](https://github.com/odysseus-dev/odysseus/issues) and [PRs](https://github.com/odysseus-dev/odysseus/pulls).
2. Coordinate modularization through [#4071](https://github.com/odysseus-dev/odysseus/issues/4071) and active stabilization work through the [milestone](https://github.com/odysseus-dev/odysseus/milestone/1).
3. Use the repository's issue and PR templates and target **`dev`**.
4. Include relevant tests, runtime evidence, and screenshots or recordings for visual changes.
1. Read [CONTRIBUTING.md](CONTRIBUTING.md). > [!NOTE]
2. Search existing issues and PRs to avoid duplicating work. > Product-direction or difficult-to-reverse changes follow the [feature proposal process](docs/maintainers/product-and-features.md). Report security vulnerabilities privately through [SECURITY.md](SECURITY.md), never in a public issue.
3. Coordinate structural changes through #4071 and stabilization work through the milestone.
4. Open a focused issue where needed and follow the existing contribution templates.
5. Provide relevant tests, runtime evidence, and screenshots or recordings for visual changes.
For changes involving product direction or difficult-to-reverse contracts, follow the [feature proposal process](docs/maintainers/product-and-features.md).
Security vulnerabilities must be reported privately through [SECURITY.md](SECURITY.md).