lablup / lablup/mlxcel

docs(python): the model-plus-connect-target rule contradicts the recommended socket= recipe

Open Beginner friendly
#1,703 0 comments 0 reactions 0 assignees View on GitHub
priority:low status:ready type:docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.