Docs: Install steps in docs

[serjikibm]

In the docs the installation step with uv add requires that a uv project is initialized e.g., uv init, so maybe for uv we should add the required set of steps so the user has the correct python version, a venv, and initialized project. Instead of the initializing a uv project, they could also do uv pip install

[planetf1]

It's a good question to think about .... though uv is the most popular packaging tool now, so if someone is using the mellea library there'a distinct probability they are using it. uv pip install is more risky as any added dependency would be lost by a subsequent uv sync if that project uses uv.

ie
"I'm adding mellea to my project" → uv add mellea (assumes existing project)
"I just want to try it" → uv pip install mellea (no project needed)

Interestingly when I wrote that text I noted that Pydantic, CrewAI, Langchain all seemed to be forward on uv add - but clearly other projects don't.. and I get the confusion....

So maybe we should use

# Into an existing uv project:
uv add mellea

# Or directly into a virtual environment:
uv pip install mellea

consistently in the text? Though we can only likely do one alongside the pypi 'badge'

I think there's a bigger point here - we probably need a better 'from 0' set of instructions

• installing python (this is so variable - but there are nuances with versions)
• setting up the venv (as you noted)
• ollama install instructions
• better guidance on what extras are needed
• verification steps
• clarification of Windows (for example we could direct users to only use WSL2)

[serjikibm]

Other open source software installation steps have a tabbed UI where one can choose the package manager, etc.

However to keep things simple, we could have a comprehensive set of instructions for one approach, like using uv and then let the user pick/substitute if they are more advanced and want to customize, and then let the community contribute steps for more options.

[planetf1]

Implementation notes

PR #1152 is a correct narrowband fix but leaves the page in a slightly awkward state (three code blocks plus a prose note). The fuller fix below is about the same effort and produces a cleaner page.

What to change: docs/docs/getting-started/installation.md

Replace the two parallel code blocks with headed sections that make the decision explicit:

## Install

**If you're using a uv project** (`pyproject.toml` managed by uv):

\`\`\`bash
uv add mellea
\`\`\`

**If you're using a virtual environment** (uv venv, python -m venv, conda):

\`\`\`bash
uv pip install mellea
# or
pip install mellea
\`\`\`

Activate your environment first — running `pip install` without an active venv risks polluting your system Python.

Apply the same restructure to the Optional extras section, which currently has the same parallel-blocks problem.

Plain markdown throughout — no MDX/JSX components.

What NOT to change

Guide prerequisite blurbs — roughly 20 pages have lines like `pip install mellea`, Ollama running locally. These are conceptual shorthand meaning "mellea is importable in your environment", not literal instructions. Touching 20 files for cosmetic consistency isn't worth the diff noise. Leave them.

Error messages in source code — mellea/backends/, mellea/plugins/, etc. contain runtime hints like pip install 'mellea[hooks]'. At runtime we don't know the user's toolchain; pip install is universally readable. Leave these as-is.

docs/docs/index.mdx homepage — already uses uv pip install mellea as its one-liner, which is the right "just try it" canonical form. No change needed.

Decision for the implementer

uv pip install and pip install can be collapsed into one section (as above) since the user's real decision is "do I have a uv project or not", not "which pip-compatible tool do I use". If you prefer to keep them separate, that's fine too — just make both visible, not buried in a note.

[planetf1]

Thanks for the contribution - the change is mergeable is, and it adds a clarifying note — but I took a look through at the broader context (i did introduce some confusion when I rewrote the docs). The above is an assessment - may make sense for this PR as I think it would be sufficient to close the issue?

[serjikibm]

@planetf1 agreed with the assessment. Added my 👍 to the #1152

[planetf1]

See also #1162 -- this is a reason we don't use tabbed pages (I've used this in previous projects, including on mkdocs-material ie for different os options)