The Getting Started and Development Guide sections of README.md no longer match the code. Following them from a clean machine does not produce a working project. Each item below was reproduced.
1. README.md:66 — cp -r ../examples/* ./ copies five projects
examples/ now holds five separate project directories (email_assistant, finance, helloworld, portfolio, text2sql), not the contents of one project. This drops all five into my-app instead of scaffolding one.
Should name a single project, e.g. cp -r ../examples/helloworld/* ./.
2. README.md:45 — project structure says workflows/, code expects workflow/
├── workflows/ # Workflow scripts (deployed as REST APIs)
Every example uses workflow/ (singular). The plural spelling dates from before 9b2305d, which renamed the directory.
This one is worth more than a typo fix: when workflow_file in config/global_controller.yaml points at a path that does not exist, cli.py logs Workflow file not found and then continues. The build still exits 0 and still reports Build complete., it just never builds the Workflow image. Anyone following the README's spelling gets a silent partial build.
3. README.md:19 — placeholder clone URL
git clone https://github.com/your-repo/ventis.git
Never filled in. Should be https://github.com/CanyonCodeCoreAI/canyoncodecore.git.
Related: the next line is cd ventis, which is correct for a fresh clone whose directory is named ventis, but the repo also contains a ventis/ package directory. Anyone whose checkout directory is named something else (a worktree, or a clone of canyoncodecore) lands inside the package, where there is no pyproject.toml. Worth disambiguating.
4. README.md:21 — pip install -e . skips the environment setup it needs
Three things make this fail on a stock macOS machine, and the resulting error names none of them:
pyproject.toml sets requires-python = ">=3.10"; the system interpreter is Python 3.9.6.- There is no
setup.py, so an editable install goes through PEP 660, which needs pip >= 21.3. The pip bundled with Apple's Command Line Tools is 21.2.4.
pip is often not on PATH at all; only python3 -m pip works.
What that combination actually prints is misleading:
ERROR: File "setup.py" or "setup.cfg" not found.
Directory cannot be installed in editable mode
The real cause is the pip version, not a missing file.
A virtual environment step would sidestep all three. What works today:
uv venv --python 3.12
uv pip install -e .
5. ventis new-project does not run at all
$ ventis new-project my-app
ERROR:ventis:Templates directory not found at .../ventis/templates
$ echo $?
1
README.md:37 opens the Development Guide with this command, so the documented path is dead at step one.
9b2305d moved ventis/templates/ to examples/helloworld/ but updated neither caller:
cli.py _get_templates_dir() still returns <package>/templatespyproject.toml still declares package-data = ["templates/**/*"]
Pointing the CLI at examples/ is not a fix on its own: [tool.setuptools.packages.find] include = ["ventis*"] means examples/ never reaches a wheel, so it would work for an editable install and break for a real one. The template has to live inside the package, which is what package-data already assumes.
Three further problems are baked into the moved template itself, and each only surfaces at deploy time:
config/global_controller.yaml points at workflows/example_workflow.py while the directory is now workflow/. Per item 2, that means the Workflow image is silently never built.workflow/example_workflow.py does from example_agent_stub import ExampleAgentStub. stub_generator emits stubs/<yaml basename>.py containing a class named after agent.name, so both the module and the class name are wrong.agents/example_agent.yaml and agents/example_agent.py share a basename. The Docker context is flat, and generate_docker copies the entrypoint last, so the generated stub is overwritten by the implementation.
The Getting Started and Development Guide sections of
README.mdno longer match the code. Following them from a clean machine does not produce a working project. Each item below was reproduced.1.
README.md:66—cp -r ../examples/* ./copies five projectscp -r ../examples/* ./examples/now holds five separate project directories (email_assistant,finance,helloworld,portfolio,text2sql), not the contents of one project. This drops all five intomy-appinstead of scaffolding one.Should name a single project, e.g.
cp -r ../examples/helloworld/* ./.2.
README.md:45— project structure saysworkflows/, code expectsworkflow/Every example uses
workflow/(singular). The plural spelling dates from before 9b2305d, which renamed the directory.This one is worth more than a typo fix: when
workflow_fileinconfig/global_controller.yamlpoints at a path that does not exist,cli.pylogsWorkflow file not foundand thencontinues. The build still exits 0 and still reportsBuild complete., it just never builds the Workflow image. Anyone following the README's spelling gets a silent partial build.3.
README.md:19— placeholder clone URLNever filled in. Should be
https://github.com/CanyonCodeCoreAI/canyoncodecore.git.Related: the next line is
cd ventis, which is correct for a fresh clone whose directory is namedventis, but the repo also contains aventis/package directory. Anyone whose checkout directory is named something else (a worktree, or a clone ofcanyoncodecore) lands inside the package, where there is nopyproject.toml. Worth disambiguating.4.
README.md:21—pip install -e .skips the environment setup it needspip install -e .Three things make this fail on a stock macOS machine, and the resulting error names none of them:
pyproject.tomlsetsrequires-python = ">=3.10"; the system interpreter is Python 3.9.6.setup.py, so an editable install goes through PEP 660, which needs pip >= 21.3. The pip bundled with Apple's Command Line Tools is 21.2.4.pipis often not onPATHat all; onlypython3 -m pipworks.What that combination actually prints is misleading:
The real cause is the pip version, not a missing file.
A virtual environment step would sidestep all three. What works today:
uv venv --python 3.12 uv pip install -e .5.
ventis new-projectdoes not run at allREADME.md:37opens the Development Guide with this command, so the documented path is dead at step one.9b2305d moved
ventis/templates/toexamples/helloworld/but updated neither caller:cli.py_get_templates_dir()still returns<package>/templatespyproject.tomlstill declarespackage-data = ["templates/**/*"]Pointing the CLI at
examples/is not a fix on its own:[tool.setuptools.packages.find] include = ["ventis*"]meansexamples/never reaches a wheel, so it would work for an editable install and break for a real one. The template has to live inside the package, which is whatpackage-dataalready assumes.Three further problems are baked into the moved template itself, and each only surfaces at deploy time:
config/global_controller.yamlpoints atworkflows/example_workflow.pywhile the directory is nowworkflow/. Per item 2, that means the Workflow image is silently never built.workflow/example_workflow.pydoesfrom example_agent_stub import ExampleAgentStub.stub_generatoremitsstubs/<yaml basename>.pycontaining a class named afteragent.name, so both the module and the class name are wrong.agents/example_agent.yamlandagents/example_agent.pyshare a basename. The Docker context is flat, andgenerate_dockercopies the entrypoint last, so the generated stub is overwritten by the implementation.