docs: add agent-oriented knowledge base (AGENTS.md + .kb/) by blackboxsw · Pull Request #522 · canonical/pycloudlib

blackboxsw · 2026-07-29T22:33:39Z

Description

Adopt the canonical-agents convention: AGENTS.md directory indexes and
distilled .kb/*.md knowledge notes spanning the dev workflow, configuration,
BaseCloud/BaseInstance architecture, per-cloud backend specifics, testing,
examples, and Sphinx docs. Content describes architecture and references
self-documenting source modules rather than restating method signatures.

Additional Context and Relevant Issues

Test Steps

Prompt your favorite AI harness CLI or IDE and watch it reference .kb files to better inform
the agent with minimal context. Expectation of reduced token use and workload wall time for
agent-driven requests on this repository.

hammerstefan

This is a great initiative, helps agents and humans. I raised my eyebrows at some architectural smells this exposes 😄 .

I left a few minor comments around the cloud/areas that I know enough about to be able to find potential issues while skimming.

None of my feedback is blocking.

hammerstefan · 2026-07-30T12:33:55Z

+
+# Important
+
+- The OCI CLI must be initialized first (see the launch doc referenced in `oci/cloud.py`'s docstring). `compartment_id` falls back to `oci iam compartment get` via the CLI; failure raises `CloudSetupError`.


I don't think this is true in a strict sense. OCI CLI only has to be initialized if you need pycloudlib to fall back on locally configured defaults for users of the oci tool.

I'd be afraid that absolute statements like this will cause the agents to chase red herrings (trying to install/init oci themselves when they are running in a sandbox without oci installed).

Good point, I've updated the docs for clarity for this pass with the following diff

diff --git a/.kb/adding-a-cloud.md b/.kb/adding-a-cloud.md index e22cad8..1265227 100644 --- a/.kb/adding-a-cloud.md +++ b/.kb/adding-a-cloud.md @@ -12,7 +12,7 @@ A new backend is a subpackage under `pycloudlib/<cloud>/` providing a concrete ` # Important -1. **Subpackage** `pycloudlib/<cloud>/` with `__init__.py`, `cloud.py` (`<Cloud>(BaseCloud)`), `instance.py` (`<Cloud>Instance(BaseInstance)`). Add `errors.py`/`util.py`/`vpc.py` only if needed; cloud-specific exceptions MUST inherit from `PycloudlibException` (root in `pycloudlib/errors.py`). +1. **Subpackage** `pycloudlib/<cloud>/` with `__init__.py`, `cloud.py` (`<Cloud>(BaseCloud)`), `instance.py` (`<Cloud>Instance(BaseInstance)`). Add `errors.py`/`util.py` only if needed; cloud-specific exceptions MUST inherit from `PycloudlibException` (root in `pycloudlib/errors.py`). 2. **Implement every abstract method** of `BaseCloud` and `BaseInstance` (read `cloud.py`/`instance.py` for the list). If a method is genuinely unsupported, raise `PycloudlibError` (see `Openstack.released_image`). 3. **Register the class** in `pycloudlib/__init__.py` (import + `__all__` entry). 4. **Add SDK deps** to `pyproject.toml` `[project.dependencies]` and, if the SDK lacks type stubs, add it to the `[[tool.mypy.overrides]] ignore_missing_imports` list. Prefer strict typing where possible. diff --git a/pycloudlib/oci/.kb/oci.md b/pycloudlib/oci/.kb/oci.md index e2b21e4..07f08aa 100644 --- a/pycloudlib/oci/.kb/oci.md +++ b/pycloudlib/oci/.kb/oci.md @@ -7,7 +7,7 @@ Read the top-level `.kb/agents.md` file before continuing below. # Overview -`OCI(BaseCloud)` authenticates via the `oci` SDK using `~/.oci/config` (CLI-initialized), a config dict, or env vars; `OciInstance(BaseInstance)` wraps a compute instance. OCI uses availability domains, compartments, and VCNs. +`OCI(BaseCloud)` authenticates via the `oci` python SDK reading pycloudlib.toml oci.confg_path value or falling back to `~/.oci/config` (CLI or SDK initialized), a config dict, or env vars; `OciInstance(BaseInstance)` wraps a compute instance. OCI uses availability domains, compartments, and VCNs. # Important

hammerstefan · 2026-07-30T12:40:19Z

+
+# Overview
+
+Unit tests (`tests/unit_tests/`) are hermetic and mocked, run on every PR across Python 3.8/3.10/3.12. Integration tests (`tests/integration_tests/`) exercise real cloud APIs, require credentials, and are marker-gated; they run in dedicated tox envs, not the default `tox`.


out of scope: we should probably start testing 3.14 as well since that's in 26.04

Agreed, let's take it to a separate PR.

rpocase

nothing blocking here - looks great and i really like this. it's great to see a full example. i haven't seen anything fully adopt it yet.

how was this generated? i would like to extract this to some larger repositories too.

rpocase · 2026-07-30T14:25:13Z

@@ -0,0 +1,44 @@
+# Preface
+
+pycloudlib is a Python library (Python >=3.8) that launches, interacts with, and snapshots Ubuntu cloud instances across many public and private clouds through a uniform `BaseCloud` / `BaseInstance` abstraction. This file is relevant to any task touching the source tree, build, tests, docs, or examples.


ideally should merge #508 first and change the python ref to 3.10. not a blocker though (can change in that branch if we land later)

While I agree it may have been nice to see this changset in #508 land, I kindof also would like to see the kb articles be automatically updated by an agent after this PR lands too. @rpocase if you get a chance on #508 during addressing the review comments, can you rebase against tip of main to get the.kb articles and ask an agent to update any relevant kb articles due to current changes so we can see how this works in practice?

rpocase · 2026-07-30T14:35:27Z

+
+# Overview
+
+pycloudlib uses `uv` (wrapped by a thin `Makefile`) and `tox` for the multi-check workflow. Supported Python range is >=3.8; CI covers 3.8/3.10/3.12. ruff handles lint+format, mypy handles typing, pytest runs unit tests with `--doctest-modules`.


again, python version constraints if we merge #508

+1 we need this changed, but I want an agent to do that as part of #508 if we can so we can review a known expected .kb delta as part of the PR.

rpocase · 2026-07-30T14:36:11Z

+# Important
+
+- After editing any Python in `pycloudlib/` or `examples/`, run ruff and mypy. Prefer `make test` (full tox) or the individual tox envs defined in `tox.ini`.
+- Default `tox` envlist only **checks** (does not reformat): `ruff`, `mypy`, `py38`. Use `tox -e format` to apply formatting.


py versions if #508 merges first

rpocase · 2026-07-30T14:41:59Z

+
+# Overview
+
+`VMWare(BaseCloud)` shells out to `govc` (the govmomi CLI, not an SDK) against a vSphere endpoint; `VMWareInstance(BaseInstance)` wraps a VM. Image selection maps Ubuntu series to pre-uploaded VM templates.


are there any specific vsphere version constraints? govc officially supports 7.0, but i'm not familiar with the implementation to know if pycloudlib only exposes a subset of features.

blackboxsw · 2026-07-30T16:42:20Z

nothing blocking here - looks great and i really like this. it's great to see a full example. i haven't seen anything fully adopt it yet.

how was this generated? i would like to extract this to some larger repositories too.

Thanks @rpocase and @hammerstefan.
For initial generation I had cloned https://github.com/canonical/canonical-agents repo in a peer directory.
NOTE: canonical-agents repo is in flux and conventions may change in the future, this PR is just a starting point aligned with current skeletal suggestions from canonical-agents. I expect in the future we may want to refresh updated conventions and apply to pycloudlib's knowledge base files or layout as generalized improvements make sense.

Initial prompt with your favorite AI harness to generate intiial structured docs based on it's own assessment of the repo conventions/practices/architecture:

Enter plan mode

Review guidelines from @../canonical-agents repo to create knowledge base articles for this pycloudlib repo

I then spent time pruning files via additional "update plan" requests from the plan that I didn't want to create .kb files for.
Then review initial kb content generated (looking to make things more concise where possible as the model I used was noisier than I would have liked. We want less context in these files, more general guidance and arch hints/reasons.
3A:
I also noticed duplication in multiple areas across kb articles, and providing way too many details about required currect class API methods which should really just be in the code itself, not the kb articles as there will be way too much drift as PRs change code logic and class APIs.
prompt: @.kb/adding-a-cloud.md and cloud-abstraction.md appear to have a lot of duplication. Resolve this

3B: Remove too detailed 'specs' from kb docs for stuff that is documented by the class APIs anyway

prompt: A lot of kb files seem to restate the class methods encoded in the specific base classes. This feels unnecessary context given that the instnace.py is going to be read by the agent anyway
Ensure each .kb file avoids restating required methods or functions whether the referenced python module already documents itself. We want to avoid unnecessary churn in .kb files each time the python itself provides a reasonable source of truth. Just describe concise architecture and references to applicable modules where necessary.

Adopt the canonical-agents convention: AGENTS.md directory indexes and distilled .kb/*.md knowledge notes spanning the dev workflow, configuration, BaseCloud/BaseInstance architecture, per-cloud backend specifics, testing, examples, and Sphinx docs. Content describes architecture and references self-documenting source modules rather than restating method signatures.

hammerstefan approved these changes Jul 30, 2026

View reviewed changes

rpocase approved these changes Jul 30, 2026

View reviewed changes

blackboxsw force-pushed the canonical-agents-knowledge-base branch from d69083d to ee75954 Compare July 30, 2026 18:27

blackboxsw force-pushed the canonical-agents-knowledge-base branch from ee75954 to ed79bca Compare July 30, 2026 18:31

blackboxsw merged commit cd543b5 into canonical:main Jul 30, 2026
6 of 7 checks passed


		# Important

		- The OCI CLI must be initialized first (see the launch doc referenced in `oci/cloud.py`'s docstring). `compartment_id` falls back to `oci iam compartment get` via the CLI; failure raises `CloudSetupError`.


		# Overview

		Unit tests (`tests/unit_tests/`) are hermetic and mocked, run on every PR across Python 3.8/3.10/3.12. Integration tests (`tests/integration_tests/`) exercise real cloud APIs, require credentials, and are marker-gated; they run in dedicated tox envs, not the default `tox`.

		@@ -0,0 +1,44 @@
		# Preface

		pycloudlib is a Python library (Python >=3.8) that launches, interacts with, and snapshots Ubuntu cloud instances across many public and private clouds through a uniform `BaseCloud` / `BaseInstance` abstraction. This file is relevant to any task touching the source tree, build, tests, docs, or examples.


		# Overview

		pycloudlib uses `uv` (wrapped by a thin `Makefile`) and `tox` for the multi-check workflow. Supported Python range is >=3.8; CI covers 3.8/3.10/3.12. ruff handles lint+format, mypy handles typing, pytest runs unit tests with `--doctest-modules`.


		# Overview

		`VMWare(BaseCloud)` shells out to `govc` (the govmomi CLI, not an SDK) against a vSphere endpoint; `VMWareInstance(BaseInstance)` wraps a VM. Image selection maps Ubuntu series to pre-uploaded VM templates.

Uh oh!

Conversation

blackboxsw commented Jul 29, 2026

Description

Additional Context and Relevant Issues

Test Steps

Uh oh!

hammerstefan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rpocase left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blackboxsw commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants