Skip to content

usability: remove uv run from first-run and viewer command hints #169

@changliu2

Description

@changliu2

Reporter perspective

As a first-time user, I followed the README install path (python -m venv + python -m pip install -e ".[otel,langgraph]"). After that flow, user-facing hints should be runnable as assert-eval .... Instead, several places tell me to run uv run assert-eval ..., even though uv was not required by onboarding.

Evidence

Confirmed by the usability sweep:

  • assert_eval/runner.py:962 prints the completion hint:
    log.info(f"  uv run assert-eval results status {suite_id} {run_id}")
  • examples/travel_planner_langgraph/agent.py:12 documents:
    uv run assert-eval run --config examples/travel_planner_langgraph/eval_config.yaml
    
  • examples/phoenix_auto_trace/travel_langgraph.py:10 has the same uv run assert-eval run ... usage hint.
  • viewer/src/routes/suite/[suite_id]/[run_id]/+page.svelte:917 shows:
    uv run assert-eval run --config <config>
    
  • viewer/src/lib/server/artifacts.ts:244 tells users to rebuild with:
    uv run assert-eval run --config ${configPath} --resume --force-stage judge
    
  • examples/agents/openclaw/README.md:12 also uses uv run assert-eval ... in a user-facing example.

uv run in contributor/dev-only docs may be fine, but these locations are visible to users following the pip install path.

Recommended fix

  • Change first-run and viewer hints to bare assert-eval ....
  • If a dev-only flow truly requires uv, label it explicitly as a contributor/developer path.
  • For viewer rebuild hints, prefer:
    assert-eval run --config <config> --resume --force-stage judge
    

Slice rollups

Found by slice 4 and confirmed by slice 5:

  • C:\Users\changliu2\.copilot\session-state\3714f9ab-3680-4990-a750-a80c932203f2\files\usability-slice-4-rollup.md
  • C:\Users\changliu2\.copilot\session-state\3714f9ab-3680-4990-a750-a80c932203f2\files\usability-slice-5-rollup.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentationshould-fixConfusing or visibly rough but not launch-blocking

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions