code/yieldomega
Watch
4
0
Fork
You've already forked yieldomega
 0
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity

docs: TimeCurve bot install — 'ModuleNotFoundError: web3' on fresh QA server without venv #50

New issue
Closed
opened 2026-04-23 04:08:53 +00:00 by Brouie · 8 comments
Brouie commented 2026-04-23 04:08:53 +00:00 (Migrated from gitlab.com)

Filed per dev request from #39 section A install gotcha.

Summary

First run of scripts/start-local-anvil-stack.sh on a fresh QA server (no venv) fails with ModuleNotFoundError: web3 from swarm_runner.py. The documented pip install -e . recommendation in bots/timecurve is insufficient on systems that enforce PEP 668 (externally-managed-environment).

Observed

First stack run fails at swarm bootstrap:

ModuleNotFoundError: No module named 'web3'

Error originates from bots/timecurve/src/swarm_runner.py (or equivalent entrypoint) attempting to import web3.

Working fix

cd bots/timecurve && pip install -e . --user --break-system-packages

Then rerun bash scripts/start-local-anvil-stack.sh.

Why this happens

  • Fresh Ubuntu 22/24 / Debian 12+ systems default to PEP 668 externally-managed-environment policy
  • Vanilla pip install -e . fails without --break-system-packages or a venv
  • Script / docs recommend pip install -e . which doesn't account for this

Suggested doc fixes

Either:
(a) Update bots/timecurve/README.md (or wherever the install step is documented) to show both the venv path and the --user --break-system-packages fallback for CI/QA servers, or
(b) Add a preflight check to start-local-anvil-stack.sh that attempts the pip install and surfaces a clearer error + copy-pasteable fix when it fails

Environment

  • QA server: 5.223.69.18 (Ubuntu 24, no venv)
  • Repo at fed6cd2..eac3d5f range

cc @PlasticDigits

**Filed per dev request from #39 section A install gotcha.** ## Summary First run of `scripts/start-local-anvil-stack.sh` on a fresh QA server (no venv) fails with `ModuleNotFoundError: web3` from `swarm_runner.py`. The documented `pip install -e .` recommendation in `bots/timecurve` is insufficient on systems that enforce PEP 668 (externally-managed-environment). ## Observed First stack run fails at swarm bootstrap: ``` ModuleNotFoundError: No module named 'web3' ``` Error originates from `bots/timecurve/src/swarm_runner.py` (or equivalent entrypoint) attempting to import web3. ## Working fix ``` cd bots/timecurve && pip install -e . --user --break-system-packages ``` Then rerun `bash scripts/start-local-anvil-stack.sh`. ## Why this happens - Fresh Ubuntu 22/24 / Debian 12+ systems default to PEP 668 externally-managed-environment policy - Vanilla `pip install -e .` fails without `--break-system-packages` or a venv - Script / docs recommend `pip install -e .` which doesn't account for this ## Suggested doc fixes Either: (a) Update `bots/timecurve/README.md` (or wherever the install step is documented) to show both the venv path and the `--user --break-system-packages` fallback for CI/QA servers, or (b) Add a preflight check to `start-local-anvil-stack.sh` that attempts the pip install and surfaces a clearer error + copy-pasteable fix when it fails ## Environment - QA server: `5.223.69.18` (Ubuntu 24, no venv) - Repo at `fed6cd2..eac3d5f` range cc @PlasticDigits
Brouie commented 2026-04-23 04:09:25 +00:00 (Migrated from gitlab.com)

mentioned in issue #39

mentioned in issue #39
PlasticDigits commented 2026-04-23 05:33:29 +00:00 (Migrated from gitlab.com)

mentioned in commit 2b47d7d61b

mentioned in commit 2b47d7d61bea9bbce6f7fd5960eb9f98a78da90f
PlasticDigits commented 2026-04-23 05:33:29 +00:00 (Migrated from gitlab.com)

mentioned in commit 35a055ee68

mentioned in commit 35a055ee6882d9b050d5e99c848a7053c0979f7b
PlasticDigits commented 2026-04-23 05:33:38 +00:00 (Migrated from gitlab.com)

Fix shipped (main)

What changed

  • bots/timecurve/README.md: PEP 668 section — venv-first install plus pip install -e ".[dev]" --user --break-system-packages fallback for bare QA hosts; links SKILL.md.
  • scripts/start-local-anvil-stack.sh: ensure_timecurve_bot_deps preflights import web3 before the bot swarm and prints the same copy-paste commands if deps are missing.
  • docs/testing/invariants-and-business-logic.md: Local stack bot swarm (tooling) row documents the invariant (swarm needs importable web3; not onchain authority).
  • Crosslinks: docs/testing/e2e-anvil.md, QA checklists, .cursor/skills/yieldomega-guardrails/SKILL.md, bots/timecurve/SKILL.md.

Merge: 35a055e on main (includes merge of fix/50-pep668-timecurve-bot).

@Brouie please verify on a fresh PEP 668 host (or simulate missing web3):

Checklist

  • Read bots/timecurve/README.md → PEP 668 — venv commands and fallback match your working fix.
  • With no bots/timecurve/.venv and no user-site web3, run SKIP_ANVIL_RICH_STATE=1 bash scripts/start-local-anvil-stack.sh — expect clear error with both install options (not a raw ModuleNotFoundError).
  • After cd bots/timecurve && python3 -m venv .venv && .venv/bin/pip install -e ".[dev]", re-run the stack — bot swarm should start (or proceed past the preflight).
  • Optional: on a PEP 668 machine, confirm the --user --break-system-packages one-liner from the README still works and import web3 succeeds for python3.
  • bash -n scripts/start-local-anvil-stack.sh passes.

Tests run (agent): bash -n scripts/start-local-anvil-stack.sh; bots/timecurve pytest (13 passed) in a fresh venv.

## Fix shipped (main) **What changed** - `bots/timecurve/README.md`: PEP 668 section — venv-first install plus `pip install -e ".[dev]" --user --break-system-packages` fallback for bare QA hosts; links `SKILL.md`. - `scripts/start-local-anvil-stack.sh`: `ensure_timecurve_bot_deps` preflights `import web3` before the bot swarm and prints the same copy-paste commands if deps are missing. - `docs/testing/invariants-and-business-logic.md`: **Local stack bot swarm (tooling)** row documents the invariant (swarm needs importable `web3`; not onchain authority). - Crosslinks: `docs/testing/e2e-anvil.md`, QA checklists, `.cursor/skills/yieldomega-guardrails/SKILL.md`, `bots/timecurve/SKILL.md`. **Merge:** `35a055e` on `main` (includes merge of `fix/50-pep668-timecurve-bot`). --- @Brouie please verify on a fresh PEP 668 host (or simulate missing `web3`): **Checklist** - [ ] Read `bots/timecurve/README.md` → **PEP 668** — venv commands and fallback match your working fix. - [ ] With **no** `bots/timecurve/.venv` and **no** user-site `web3`, run `SKIP_ANVIL_RICH_STATE=1 bash scripts/start-local-anvil-stack.sh` — expect **clear error** with both install options (not a raw `ModuleNotFoundError`). - [ ] After `cd bots/timecurve && python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"`, re-run the stack — bot swarm should start (or proceed past the preflight). - [ ] Optional: on a PEP 668 machine, confirm the `--user --break-system-packages` one-liner from the README still works and `import web3` succeeds for `python3`. - [ ] `bash -n scripts/start-local-anvil-stack.sh` passes. **Tests run (agent):** `bash -n scripts/start-local-anvil-stack.sh`; `bots/timecurve` `pytest` (13 passed) in a fresh venv.
Brouie commented 2026-04-23 06:24:53 +00:00 (Migrated from gitlab.com)

mentioned in issue #42

mentioned in issue #42
Brouie commented 2026-04-24 02:44:33 +00:00 (Migrated from gitlab.com)

@PlasticDigits verified.

Both touch points present:

  • bots/timecurve/README.md L17-27: dedicated 'PEP 668 (externally managed Python)' section. Explains symptom (ModuleNotFoundError: web3 when stack runs bot swarm) and gives the exact pip install -e ".[dev]" --user --break-system-packages fallback command.
  • scripts/start-local-anvil-stack.sh L52: ensure_timecurve_bot_deps() helper runs python -c 'import web3' preflight, prints copy-paste venv and PEP 668 install commands if it fails, instructs to either install then re-run or set START_BOT_SWARM=0 to skip the swarm. Called at L263 before swarm launch.

Fail-fast pattern is the right call — users now see the install command upfront rather than deep in a Python traceback.

Closing as verified.

@PlasticDigits verified. Both touch points present: - `bots/timecurve/README.md` L17-27: dedicated 'PEP 668 (externally managed Python)' section. Explains symptom (ModuleNotFoundError: web3 when stack runs bot swarm) and gives the exact `pip install -e ".[dev]" --user --break-system-packages` fallback command. - `scripts/start-local-anvil-stack.sh` L52: `ensure_timecurve_bot_deps()` helper runs `python -c 'import web3'` preflight, prints copy-paste venv and PEP 668 install commands if it fails, instructs to either install then re-run or set `START_BOT_SWARM=0` to skip the swarm. Called at L263 before swarm launch. Fail-fast pattern is the right call — users now see the install command upfront rather than deep in a Python traceback. Closing as verified.
Brouie (Migrated from gitlab.com) closed this issue 2026-04-24 02:44:34 +00:00
PlasticDigits commented 2026-04-30 09:24:44 +00:00 (Migrated from gitlab.com)

mentioned in issue #102

mentioned in issue #102
PlasticDigits commented 2026-05-01 06:11:32 +00:00 (Migrated from gitlab.com)

mentioned in issue #104

mentioned in issue #104
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
cac-design-issue-544
renovate/configure
No results found.
Labels
Clear labels   
agent:fix_bugfix

   
agent:fix_conflicts

   
agent:fix_security

   
agent:gap_analysis

   
agent:implement

   
agent:open_issues

   
agents

   
agent:security_audit

   
agent:verify
  
area
timecurve

  
arena

   
arena-v2

   
audit

   
block:feature_review

   
block:security

   
bug

   
contracts

   
design

   
devops

   
docs
Documentation

  
documentation

   
enhancement

   
epic
Epic / umbrella issue

  
feature

   
frontend

   
indexer

   
low priority
Low priority, investigate other issues first

  
megaeth

   
operations

   
ops
Deploy and operations

  
performance

   
QA

   
qa checklist

   
referrals

   
removal
Legacy removal

  
security

   
smart-contracts

   
tech-debt

   
testing

   
time-arena
TimeArena v2 revamp

  
timecurve

   
visual-qa
No labels
agent:fix_bugfix
agent:fix_conflicts
agent:fix_security
agent:gap_analysis
agent:implement
agent:open_issues
agents
agent:security_audit
agent:verify
area
timecurve
arena
arena-v2
audit
block:feature_review
block:security
bug
contracts
design
devops
docs
documentation
enhancement
epic
feature
frontend
indexer
low priority
megaeth
operations
ops
performance
QA
qa checklist
referrals
removal
security
smart-contracts
tech-debt
testing
time-arena
timecurve
visual-qa
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
code/yieldomega#50
No description provided.