Skip to content

docs(ci): add AGENTS.md with Cursor Cloud setup notes #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
incrementaliser wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(ci): add AGENTS.md with Cursor Cloud setup notes #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# AGENTS.md

## Cursor Cloud specific instructions

`dynamicsyntax` (a.k.a. DyLan) is a single Python package (`>=3.11`) managed with **uv**.
There is no database, container stack, or backend API — every surface runs as a local
Python process or static files. The startup update script already runs `uv sync --group dev`,
so a `.venv` with dev tools is present when a session begins.

### Product surfaces
- **Core library** (`dynamicsyntax` / `dylan`): programmatic incremental parser producing TTR semantics.
- **Induction CLI** (`dsttr-induction`): YAML-driven EM lexicon learning + evaluation.
- **Flet GUI** (`dylan-gui`): desktop parser UI (also runnable in a browser).
- **Pyodide web shell** (`web/`): static browser app running the parser via WebAssembly.

### Running / testing (standard commands live in `README.md`, `pyproject.toml` `[project.scripts]`, and `.github/workflows/ci.yml`)
- Lint (CI scope): `uv run ruff check tests` (locally you can also lint `src`).
- Tests: `uv run pytest -q` — full suite takes ~1 min; a few induction tests use `@pytest.mark.timeout`.
- Build wheel/sdist: `uv build`.
- Library hello-world: `uv run python -c "import dynamicsyntax as ds; print(ds.parse('a man knows you','ttr').semantics)"`.
- Induction pipeline: `uv run dsttr-induction --config configs/induction/holdout.yaml` (writes to `out/runs/<timestamp>_<name>/`; ~2 min for `class1.txt`).

### Non-obvious gotchas
- **Prefer `uv run <cmd>`** rather than activating the venv; it always uses the project `.venv`.
- **Flet GUI in this headless VM must use web mode**: run `DYLAN_FLET_WEB=1 uv run dylan-gui`
and open `http://127.0.0.1:8550/`. Two caveats in web mode:
- It logs a non-fatal `TimeoutException ... Window(...).center` traceback at startup
(`page.window.center()` is desktop-only); the UI still renders and works.
- The "Load grammar" button uses a **native directory picker** that does not work in a
browser, so grammar loading (and therefore parsing) can't be completed via the web GUI.
Use the library API / `dsttr-induction` CLI for end-to-end parsing in this environment,
or run the GUI in native desktop mode where the picker works.
- **Pyodide web shell**: build + copy the wheel first (`uv build` then
`uv run python scripts/sync_web_wheel.py`, producing `web/dist/package.whl`), then serve
with `uv run dylan-serve-web` (port 8000). It needs network access to the pinned Pyodide
CDN (`cdn.jsdelivr.net/pyodide/v0.26.4`). Note: the bundled `micropip` rejects the wheel
because it is served as `package.whl` (`InvalidWheelFilename: wrong number of parts`), so
Python fails to boot in the browser — a pre-existing code-level issue, not an env/setup one.
- Conventional Commits are required (see `docs/CONTRIBUTING.md`); the `commit-msg` hook in
`scripts/git-hooks/` is optional and not enabled by default.
Loading