diff --git a/README.md b/README.md index 1cfa1cf..228ae02 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,27 @@ networking, identity, and data. Python 3.12 or newer is required. Development and release verification use CPython 3.14, while CI keeps every declared minor from 3.12 through 3.14 compatible. -PyPI trusted publishing is not enabled yet, so use the public source checkout for the -current API rather than an unresolved package-index name: +PyPI trusted publishing is not enabled yet, so install the exact wheel from the public +v0.53.0 release. Standard `pip` and `uv` install the same distribution. + +With `pip`, create an isolated environment and import the underscore-named Python package: + +```bash +python -m venv .venv +.venv/bin/python -m pip install "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.53.0/tesserix_adk-0.53.0-py3-none-any.whl" +.venv/bin/python -c "import tesserix_adk; print(tesserix_adk.__version__)" +``` + +With `uv`, add the same immutable wheel to an application project and commit the generated +lockfile: + +```bash +uv add "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.53.0/tesserix_adk-0.53.0-py3-none-any.whl" +uv run python -c "import tesserix_adk; print(tesserix_adk.__version__)" +``` + +The distribution name is `tesserix-adk`; Python code imports `tesserix_adk`. To contribute +to the kit itself, use the source checkout: ```bash git clone https://github.com/tesserix/agent-development-kit.git diff --git a/docs/getting-started.md b/docs/getting-started.md index 78f0a18..95e6c88 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,26 +1,42 @@ # Getting started This path proves a complete agent/tool run locally, then replaces the fake model with a -real provider. It needs Python 3.12 or newer and [uv](https://docs.astral.sh/uv/). The -repository uses CPython 3.14 by default and tests the full declared 3.12–3.14 range. +real provider. It needs Python 3.12 or newer and either standard `pip` or +[uv](https://docs.astral.sh/uv/). The repository uses `uv` and CPython 3.14 for its own +development while testing the full declared 3.12–3.14 range. ## 1. Install -PyPI trusted publishing is not enabled yet. Use the public source checkout to learn and -test the current API; use an exact tagged artifact for an application dependency as -described in [Keep agents current safely](keeping-current.md). +PyPI trusted publishing is not enabled yet. Install the exact tagged v0.53.0 wheel from +the public GitHub Release rather than asking an index for a project that is not there. +The distribution name uses a hyphen; the Python import uses an underscore. + +With `pip`: ```bash -git clone https://github.com/tesserix/agent-development-kit.git -cd agent-development-kit -uv sync --frozen +python -m venv .venv +.venv/bin/python -m pip install "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.53.0/tesserix_adk-0.53.0-py3-none-any.whl" +.venv/bin/python -c "import tesserix_adk; print(tesserix_adk.__version__)" +``` + +With `uv`, from an application project: + +```bash +uv add "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.53.0/tesserix_adk-0.53.0-py3-none-any.whl" +uv run python -c "import tesserix_adk; print(tesserix_adk.__version__)" ``` -Optional integrations are extras and do not enter the base environment: +Optional integrations use the same extras with either installer. For example, +`tesserix-adk[a2a,google-adk,mcp]` installs the official A2A, Google Agent Development +Kit bridge, and MCP dependencies. The release workflow clean-installs every individual +extra and `all` with `pip` before publishing succeeds. + +Use the public source checkout only when contributing to this repository: ```bash -uv sync --frozen --extra a2a -uv sync --frozen --extra mcp --extra postgres --extra redis --extra temporal +git clone https://github.com/tesserix/agent-development-kit.git +cd agent-development-kit +uv sync --frozen ``` ## 2. Prove the offline path diff --git a/docs/keeping-current.md b/docs/keeping-current.md index f6dd44f..91d7789 100644 --- a/docs/keeping-current.md +++ b/docs/keeping-current.md @@ -21,25 +21,42 @@ the package is not yet present on PyPI. ## Pin the artifact an agent actually runs -Until PyPI publication is enabled, add the wheel from a specific public GitHub Release. -This example names the latest stable release at the time this guide was reviewed; replace -both occurrences when a newer stable release is approved: +Until PyPI publication is enabled, install the wheel from a specific public GitHub +Release. This example names the latest stable release at the time this guide was reviewed; +replace both occurrences when a newer stable release is approved. + +For a `uv`-managed application: ```bash -uv add "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.51.0/tesserix_adk-0.51.0-py3-none-any.whl" +uv add "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.53.0/tesserix_adk-0.53.0-py3-none-any.whl" git add pyproject.toml uv.lock ``` +For a standard virtual environment managed with `pip`: + +```bash +python -m pip install "tesserix-adk @ https://github.com/tesserix/agent-development-kit/releases/download/v0.53.0/tesserix_adk-0.53.0-py3-none-any.whl" +python -c "import tesserix_adk; print(tesserix_adk.__version__)" +``` + +Record that exact direct reference in the application's dependency declaration and commit +the environment's hash-pinned requirements. `pip` installs packages; it does not make an +unlocked environment reproducible by itself. Extras use normal PEP 508 syntax, for example +`tesserix-adk[a2a,mcp] @ https://.../tesserix_adk-0.53.0-py3-none-any.whl`. + After PyPI trusted publishing is enabled, use a pre-1.0 compatibility window that accepts patch fixes without silently accepting the next potentially breaking minor release: ```bash -uv add "tesserix-adk~=0.51.0" +uv add "tesserix-adk~=0.53.0" +python -m pip install "tesserix-adk~=0.53.0" ``` -In both cases, commit `uv.lock`. CI and production then install with `uv sync --frozen`. -The dependency declaration states what may be considered; the lock records the exact -version and hashes that were tested. +In the `uv` case, commit `uv.lock` and install with `uv sync --frozen`. In the `pip` case, +commit the consuming project's resolved, hash-pinned requirements and install with +`python -m pip install --require-hashes -r requirements.txt`. The dependency declaration +states what may be considered; the lock records the exact version and hashes that were +tested. ## Automate the proposal, not the decision diff --git a/tests/test_documentation.py b/tests/test_documentation.py index cb0dc4b..3d48287 100644 --- a/tests/test_documentation.py +++ b/tests/test_documentation.py @@ -113,6 +113,13 @@ def test_framework_interop_names_each_supported_boundary() -> None: assert all(f"`{name}`" in text for name in expected) +def test_readme_offers_pip_and_uv_install_paths() -> None: + text = (ROOT / "README.md").read_text(encoding="utf-8") + assert "python -m pip install" in text + assert "uv add" in text + assert "import tesserix_adk" in text + + @pytest.mark.parametrize( "page", NAMING_SURFACES, ids=lambda path: path.relative_to(ROOT).as_posix() )