docs(python): the model-plus-connect-target rule contradicts the recommended socket= recipe
- Dominant language
- Rust
- Stars
- 467
- Forks
- 54
- Avg merge
- 4h 25m
- Merged PRs (30d)
- 310
Description
## Summary
`docs/python-client.md` says "Passing both a model and a connect target raises `MlxcelError`", then twelve lines later its own recommended secure-socket recipe passes a model together with `socket=`. The prose over-states the rule: `socket=` is the one connect target that is legal alongside a model (in managed mode it becomes the bind path for the spawned server).
## Background
The code only raises when `base_url` or `transport` is passed with a model; `socket=` is explicitly allowed and re-interpreted as the bind path. The docstring in `_client.py` already states this correctly, so only the prose in two files is wrong.
## Proposed Solution
Two prose edits narrowing "a connect target" to `base_url` / `transport`. The exact correct wording already exists in `_common.py`.
## Implementation Notes
- `docs/python-client.md:61` lists `mlxcel.LLM(socket=...)` as a connect target.
- `docs/python-client.md:77` (confirmed): "Passing both a model and a connect target raises `MlxcelError`, because the mode would be ambiguous."
- `docs/python-client.md:89`: `mlxcel.LLM("mlx-community/Qwen3-4B-4bit", socket=str(runtime_dir / "mlxcel.sock"))`, exactly model + socket, working as intended.
- `python/README.md:41` and `:58` repeat the same over-broad claim.
- Ground truth: `python/src/mlxcel/_common.py:48-56` (confirmed) raises only on `base_url is not None or transport is not None`, and its message says "In managed mode, `socket=` is the bind path for the spawned server"; `python/src/mlxcel/_client.py:74-77` docstring states it correctly.
## Acceptance Criteria
- [ ] The prose rule matches the code: only `base_url` / `transport` conflict with a model; `socket=` + model is documented as managed-mode bind.
---
## Original Suggestion
### Title: docs(python): the model-plus-connect-target rule contradicts the recommended socket= recipe
`docs/python-client.md` says "Passing both a model and a connect target raises `MlxcelError`" — and then, twelve lines later, its own recommended secure-socket recipe passes a model together with `socket=`. The prose over-states the rule: `socket=` is the one connect target that *is* legal alongside a model (in managed mode it becomes the bind path for the spawned server).
## Evidence
- `docs/python-client.md:61` — lists `mlxcel.LLM(socket=...)` as a connect target
- `docs/python-client.md:77` — "Passing both a model and a connect target raises `MlxcelError`, because the mode would be ambiguous."
- `docs/python-client.md:89` — `mlxcel.LLM("mlx-community/Qwen3-4B-4bit", socket=str(runtime_dir / "mlxcel.sock"))` — exactly model + socket, working as intended
- `python/README.md:41` and `:58` — same pairing, same over-broad claim
- Ground truth: `python/src/mlxcel/_common.py:48-56` — the raising branch is only `base_url is not None or transport is not None`, and its message says "In managed mode, `socket=` is the bind path for the spawned server"; `python/src/mlxcel/_client.py:74-77` docstring states it correctly
## Suggested fix
Two prose edits (`docs/python-client.md:77`, `python/README.md:58`) narrowing "a connect target" to `base_url`/`transport`; the exact correct wording already exists in `_common.py:53-55`.
## Acceptance criteria
- [ ] The prose rule matches the code: only `base_url`/`transport` conflict with a model; `socket=` + model is documented as managed-mode bind
Contributor guide
Research direction
Start by comparing the claims at docs/python-client.md:77 and python/README.md:58 with the validation in python/src/mlxcel/_common.py:48-56 and the _client.py docstring. Update the two prose passages so only base_url and transport conflict with a model, while socket= is documented as the managed-mode bind path. Done means the prose matches the existing behavior and the model-plus-socket recipe is no longer contradictory.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 92/100