agent-instruction-protocol 0.7.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_instruction_protocol-0.7.0/.github/workflows/release.yml +222 -0
- agent_instruction_protocol-0.7.0/.gitignore +11 -0
- agent_instruction_protocol-0.7.0/.python-version +1 -0
- agent_instruction_protocol-0.7.0/AGENTS.md +125 -0
- agent_instruction_protocol-0.7.0/CHANGELOG.md +206 -0
- agent_instruction_protocol-0.7.0/LICENSE +201 -0
- agent_instruction_protocol-0.7.0/PKG-INFO +474 -0
- agent_instruction_protocol-0.7.0/README.md +453 -0
- agent_instruction_protocol-0.7.0/docs/PLAN-0.6a0.md +492 -0
- agent_instruction_protocol-0.7.0/docs/cli-json.md +269 -0
- agent_instruction_protocol-0.7.0/docs/client-execution.md +146 -0
- agent_instruction_protocol-0.7.0/docs/examples/aip-runtime-session.md +523 -0
- agent_instruction_protocol-0.7.0/docs/run-modes.md +69 -0
- agent_instruction_protocol-0.7.0/docs/running.md +363 -0
- agent_instruction_protocol-0.7.0/docs/sdk.md +120 -0
- agent_instruction_protocol-0.7.0/docs/server-design.md +400 -0
- agent_instruction_protocol-0.7.0/docs/state.md +237 -0
- agent_instruction_protocol-0.7.0/docs/upgrading.md +177 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/SKILL.md +127 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/assets/config.json +1 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/assets/policy.md +4 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/assets/reply.md +12 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/references/help.md +5 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/scripts/escalate.py +15 -0
- agent_instruction_protocol-0.7.0/examples/billing-support/source/README.md +6 -0
- agent_instruction_protocol-0.7.0/img/aip-authoring.png +0 -0
- agent_instruction_protocol-0.7.0/img/aip-console-example-email-blast.png +0 -0
- agent_instruction_protocol-0.7.0/img/aip-console-example.png +0 -0
- agent_instruction_protocol-0.7.0/img/aip-console-example2.png +0 -0
- agent_instruction_protocol-0.7.0/img/aip-logo.png +0 -0
- agent_instruction_protocol-0.7.0/img/aip-skill-example2.png +0 -0
- agent_instruction_protocol-0.7.0/img/aip.png +0 -0
- agent_instruction_protocol-0.7.0/install.sh +75 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/LICENSE +201 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/README.md +29 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/docs/specification.md +266 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/hatch_build.py +29 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/pyproject.toml +46 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/__init__.py +15 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/agents.py +269 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/cli.py +203 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/models.py +322 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/resources.py +58 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/runtime-0.5a1.md +19 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/runtime-0.6a0.md +19 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/runtime.md +19 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/skill.py +503 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/tests/conftest.py +9 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/tests/fixtures/dialogue-graph.yaml +168 -0
- agent_instruction_protocol-0.7.0/packages/aip-spec/tests/test_spec.py +627 -0
- agent_instruction_protocol-0.7.0/pyproject.toml +46 -0
- agent_instruction_protocol-0.7.0/skills/aip-compile/SKILL.md +482 -0
- agent_instruction_protocol-0.7.0/skills/aip-compile/assets/procedure.schema.json +740 -0
- agent_instruction_protocol-0.7.0/skills/aip-compile/references/skill-creation-best-practices.md +241 -0
- agent_instruction_protocol-0.7.0/skills/aip-runtime/SKILL.md +117 -0
- agent_instruction_protocol-0.7.0/src/aip/__init__.py +15 -0
- agent_instruction_protocol-0.7.0/src/aip/client/__init__.py +20 -0
- agent_instruction_protocol-0.7.0/src/aip/client/aip-runtime/SKILL.md +117 -0
- agent_instruction_protocol-0.7.0/src/aip/client/backend.py +306 -0
- agent_instruction_protocol-0.7.0/src/aip/client/cli.py +702 -0
- agent_instruction_protocol-0.7.0/src/aip/client/executor.py +139 -0
- agent_instruction_protocol-0.7.0/src/aip/client/resolver.py +120 -0
- agent_instruction_protocol-0.7.0/src/aip/client/runner.py +304 -0
- agent_instruction_protocol-0.7.0/src/aip/client/server.py +219 -0
- agent_instruction_protocol-0.7.0/src/aip/db/__init__.py +1 -0
- agent_instruction_protocol-0.7.0/src/aip/db/neo4j.py +58 -0
- agent_instruction_protocol-0.7.0/src/aip/errors.py +18 -0
- agent_instruction_protocol-0.7.0/src/aip/model/__init__.py +24 -0
- agent_instruction_protocol-0.7.0/src/aip/model/engine.py +314 -0
- agent_instruction_protocol-0.7.0/src/aip/model/environment.py +150 -0
- agent_instruction_protocol-0.7.0/src/aip/model/procedure.py +116 -0
- agent_instruction_protocol-0.7.0/src/aip/model/resources.py +85 -0
- agent_instruction_protocol-0.7.0/src/aip/model/steps.py +607 -0
- agent_instruction_protocol-0.7.0/src/aip/model/types.py +150 -0
- agent_instruction_protocol-0.7.0/src/aip/sdk.py +716 -0
- agent_instruction_protocol-0.7.0/src/aip/server/__init__.py +1 -0
- agent_instruction_protocol-0.7.0/src/aip/server/app.py +639 -0
- agent_instruction_protocol-0.7.0/src/aip/server/backend.py +132 -0
- agent_instruction_protocol-0.7.0/src/aip/server/backends/__init__.py +1 -0
- agent_instruction_protocol-0.7.0/src/aip/server/backends/filesystem.py +414 -0
- agent_instruction_protocol-0.7.0/src/aip/server/backends/neo4j.py +1030 -0
- agent_instruction_protocol-0.7.0/src/aip/server/config.py +236 -0
- agent_instruction_protocol-0.7.0/src/aip/server/governance.py +196 -0
- agent_instruction_protocol-0.7.0/src/aip/server/records.py +293 -0
- agent_instruction_protocol-0.7.0/src/aip/server/search.py +220 -0
- agent_instruction_protocol-0.7.0/src/aip/spec/__init__.py +18 -0
- agent_instruction_protocol-0.7.0/src/aip/spec/loader.py +119 -0
- agent_instruction_protocol-0.7.0/tests/conftest.py +15 -0
- agent_instruction_protocol-0.7.0/tests/server/test_config.py +126 -0
- agent_instruction_protocol-0.7.0/tests/server/test_contract.py +789 -0
- agent_instruction_protocol-0.7.0/tests/server/test_http.py +681 -0
- agent_instruction_protocol-0.7.0/tests/server/test_records.py +100 -0
- agent_instruction_protocol-0.7.0/tests/server/test_runs.py +258 -0
- agent_instruction_protocol-0.7.0/tests/server/test_search.py +117 -0
- agent_instruction_protocol-0.7.0/tests/test_cli_json.py +372 -0
- agent_instruction_protocol-0.7.0/tests/test_client_execution.py +223 -0
- agent_instruction_protocol-0.7.0/tests/test_loader.py +86 -0
- agent_instruction_protocol-0.7.0/tests/test_model.py +306 -0
- agent_instruction_protocol-0.7.0/tests/test_runner.py +450 -0
- agent_instruction_protocol-0.7.0/tests/test_runtime_skill.py +140 -0
- agent_instruction_protocol-0.7.0/tests/test_sdk.py +267 -0
- agent_instruction_protocol-0.7.0/uv.lock +609 -0
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
name: Release to PyPI
|
|
2
|
+
|
|
3
|
+
# Manual trigger from the Actions tab, after the release PR is merged. Reads the version from
|
|
4
|
+
# both pyprojects (the release PR aligned them), refuses if they differ or the tag exists,
|
|
5
|
+
# builds all four distributions, pushes the tag, publishes `aip-spec` and then
|
|
6
|
+
# `agent-instruction-protocol` with PyPI Trusted Publishing, and cuts a GitHub Release whose
|
|
7
|
+
# notes are the `## [X.Y.Z]` section of CHANGELOG.md.
|
|
8
|
+
#
|
|
9
|
+
# Two publish jobs because PyPI allows one pending publisher per (repo, workflow, environment):
|
|
10
|
+
# `aip-spec` publishes from the `release-spec` environment and `agent-instruction-protocol`
|
|
11
|
+
# from `release`. The spec goes first so the runtime's exact pin (`aip-spec==X.Y.Z`) resolves
|
|
12
|
+
# the moment the runtime lands. The GitHub environments and the pending publishers are set up
|
|
13
|
+
# by hand once (issue #17, "Before starting").
|
|
14
|
+
#
|
|
15
|
+
# `target: testpypi` is the dry run for a new or changed workflow: same checks, same build,
|
|
16
|
+
# both uploads go to test.pypi.org (its own account and its own two pending publishers under
|
|
17
|
+
# the same names), no tag is pushed and no GitHub Release is created. TestPyPI refuses a
|
|
18
|
+
# filename it has seen before, so one dry run per version; to repeat, suffix the version
|
|
19
|
+
# `.dev1` in both pyprojects on a scratch branch.
|
|
20
|
+
on:
|
|
21
|
+
workflow_dispatch:
|
|
22
|
+
inputs:
|
|
23
|
+
target:
|
|
24
|
+
description: "Where to publish. testpypi is the dry run: no tag, no GitHub Release."
|
|
25
|
+
type: choice
|
|
26
|
+
options: [pypi, testpypi]
|
|
27
|
+
default: pypi
|
|
28
|
+
|
|
29
|
+
jobs:
|
|
30
|
+
build:
|
|
31
|
+
name: Check, build, tag
|
|
32
|
+
runs-on: ubuntu-latest
|
|
33
|
+
permissions:
|
|
34
|
+
contents: write # push the tag
|
|
35
|
+
outputs:
|
|
36
|
+
version: ${{ steps.v.outputs.version }}
|
|
37
|
+
tag: ${{ steps.v.outputs.tag }}
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v4
|
|
40
|
+
|
|
41
|
+
- name: Install uv
|
|
42
|
+
uses: astral-sh/setup-uv@v6
|
|
43
|
+
with:
|
|
44
|
+
enable-cache: true
|
|
45
|
+
|
|
46
|
+
- name: Set up Python
|
|
47
|
+
run: uv python install 3.14
|
|
48
|
+
|
|
49
|
+
- name: Resolve the version from both pyprojects
|
|
50
|
+
id: v
|
|
51
|
+
# The two packages always share a version and the runtime pins the spec exactly, so
|
|
52
|
+
# all three numbers must agree before anything is built.
|
|
53
|
+
run: |
|
|
54
|
+
uv run --no-project python - <<'PY' >> "$GITHUB_OUTPUT"
|
|
55
|
+
import re, sys, tomllib, pathlib
|
|
56
|
+
runtime = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
|
|
57
|
+
spec = tomllib.loads(pathlib.Path("packages/aip-spec/pyproject.toml").read_text())["project"]
|
|
58
|
+
pin = next((d for d in runtime["dependencies"] if re.match(r"aip-spec\s*==", d)), "")
|
|
59
|
+
pinned = pin.split("==", 1)[1].strip() if pin else None
|
|
60
|
+
if not (runtime["version"] == spec["version"] == pinned):
|
|
61
|
+
print(f"::error::versions differ: pyproject.toml {runtime['version']}, "
|
|
62
|
+
f"packages/aip-spec/pyproject.toml {spec['version']}, pin {pin or '(none)'}. "
|
|
63
|
+
"Align all three in the release PR.", file=sys.stderr)
|
|
64
|
+
sys.exit(1)
|
|
65
|
+
print(f"version={runtime['version']}")
|
|
66
|
+
print(f"tag=v{runtime['version']}")
|
|
67
|
+
PY
|
|
68
|
+
echo "version $(grep '^version=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)"
|
|
69
|
+
|
|
70
|
+
- name: Refuse to release a version that already has a tag
|
|
71
|
+
# Forces a version bump before re-running. Without this, a re-run after a successful
|
|
72
|
+
# tag-and-publish would try to double-publish. Runs for testpypi too: a dry run of a
|
|
73
|
+
# version that has shipped is a mistake.
|
|
74
|
+
run: |
|
|
75
|
+
if git ls-remote --tags origin "refs/tags/${{ steps.v.outputs.tag }}" | grep -q .; then
|
|
76
|
+
echo "::error::tag ${{ steps.v.outputs.tag }} already exists. Bump both pyprojects before re-running."
|
|
77
|
+
exit 1
|
|
78
|
+
fi
|
|
79
|
+
|
|
80
|
+
- name: Build all four distributions
|
|
81
|
+
# Before tagging, so a build failure leaves the repo clean. `--all-packages` builds
|
|
82
|
+
# every workspace member: a wheel and an sdist each for agent-instruction-protocol
|
|
83
|
+
# and aip-spec.
|
|
84
|
+
run: |
|
|
85
|
+
rm -rf dist/
|
|
86
|
+
uv build --all-packages
|
|
87
|
+
ls -1 dist/
|
|
88
|
+
count=$(find dist/ -type f \( -name '*.whl' -o -name '*.tar.gz' \) | wc -l) # uv also writes dist/.gitignore
|
|
89
|
+
if [ "$count" -ne 4 ]; then
|
|
90
|
+
echo "::error::expected 4 files in dist/, found $count"
|
|
91
|
+
exit 1
|
|
92
|
+
fi
|
|
93
|
+
for d in agent_instruction_protocol aip_spec; do
|
|
94
|
+
test -f dist/${d}-${{ steps.v.outputs.version }}-py3-none-any.whl
|
|
95
|
+
test -f dist/${d}-${{ steps.v.outputs.version }}.tar.gz
|
|
96
|
+
done
|
|
97
|
+
|
|
98
|
+
- name: Extract release notes from CHANGELOG.md
|
|
99
|
+
# Pulls the section under `## [<version>] ...` up to (but not including) the next
|
|
100
|
+
# `## [...` heading. Empty file is fine; the GitHub Release just won't have a body.
|
|
101
|
+
run: |
|
|
102
|
+
awk -v ver="${{ steps.v.outputs.version }}" '
|
|
103
|
+
$0 ~ "^## \\[" ver "\\]" { found=1; next }
|
|
104
|
+
found && /^## \[/ { exit }
|
|
105
|
+
found { print }
|
|
106
|
+
' CHANGELOG.md > release-notes.md
|
|
107
|
+
echo "----- release-notes.md -----"
|
|
108
|
+
cat release-notes.md
|
|
109
|
+
if [ ! -s release-notes.md ]; then
|
|
110
|
+
echo "::warning::CHANGELOG.md has no '## [${{ steps.v.outputs.version }}]' section; the GitHub Release will have no notes."
|
|
111
|
+
fi
|
|
112
|
+
|
|
113
|
+
- name: Upload the distributions and the notes
|
|
114
|
+
uses: actions/upload-artifact@v4
|
|
115
|
+
with:
|
|
116
|
+
name: release-${{ steps.v.outputs.version }}
|
|
117
|
+
path: |
|
|
118
|
+
dist/
|
|
119
|
+
release-notes.md
|
|
120
|
+
if-no-files-found: error
|
|
121
|
+
|
|
122
|
+
- name: Create and push the tag
|
|
123
|
+
if: inputs.target == 'pypi'
|
|
124
|
+
# Before the first publish, as in the original single-package workflow: a publish
|
|
125
|
+
# failure leaves a tag with no release behind it, which is visible and recoverable.
|
|
126
|
+
run: |
|
|
127
|
+
git config user.name "github-actions[bot]"
|
|
128
|
+
git config user.email "github-actions[bot]@users.noreply.github.com"
|
|
129
|
+
git tag -a "${{ steps.v.outputs.tag }}" -m "Release ${{ steps.v.outputs.tag }}"
|
|
130
|
+
git push origin "${{ steps.v.outputs.tag }}"
|
|
131
|
+
|
|
132
|
+
publish-spec:
|
|
133
|
+
name: Publish aip-spec
|
|
134
|
+
needs: build
|
|
135
|
+
runs-on: ubuntu-latest
|
|
136
|
+
environment:
|
|
137
|
+
name: release-spec
|
|
138
|
+
url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/p/aip-spec' || 'https://pypi.org/p/aip-spec' }}
|
|
139
|
+
permissions:
|
|
140
|
+
contents: read
|
|
141
|
+
id-token: write # PyPI Trusted Publishing
|
|
142
|
+
steps:
|
|
143
|
+
- uses: actions/download-artifact@v4
|
|
144
|
+
with:
|
|
145
|
+
name: release-${{ needs.build.outputs.version }}
|
|
146
|
+
|
|
147
|
+
- name: Keep only the aip-spec files
|
|
148
|
+
run: |
|
|
149
|
+
mkdir -p upload
|
|
150
|
+
mv dist/aip_spec-*.whl dist/aip_spec-*.tar.gz upload/
|
|
151
|
+
ls -1 upload/
|
|
152
|
+
|
|
153
|
+
- name: Publish aip-spec
|
|
154
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
155
|
+
with:
|
|
156
|
+
packages-dir: upload/
|
|
157
|
+
repository-url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
|
|
158
|
+
|
|
159
|
+
publish-runtime:
|
|
160
|
+
name: Publish agent-instruction-protocol
|
|
161
|
+
needs: [build, publish-spec]
|
|
162
|
+
runs-on: ubuntu-latest
|
|
163
|
+
environment:
|
|
164
|
+
name: release
|
|
165
|
+
url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/p/agent-instruction-protocol' || 'https://pypi.org/p/agent-instruction-protocol' }}
|
|
166
|
+
permissions:
|
|
167
|
+
contents: read
|
|
168
|
+
id-token: write # PyPI Trusted Publishing
|
|
169
|
+
steps:
|
|
170
|
+
- uses: actions/download-artifact@v4
|
|
171
|
+
with:
|
|
172
|
+
name: release-${{ needs.build.outputs.version }}
|
|
173
|
+
|
|
174
|
+
- name: Keep only the agent-instruction-protocol files
|
|
175
|
+
run: |
|
|
176
|
+
mkdir -p upload
|
|
177
|
+
mv dist/agent_instruction_protocol-*.whl dist/agent_instruction_protocol-*.tar.gz upload/
|
|
178
|
+
ls -1 upload/
|
|
179
|
+
|
|
180
|
+
- name: Publish agent-instruction-protocol
|
|
181
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
182
|
+
with:
|
|
183
|
+
packages-dir: upload/
|
|
184
|
+
repository-url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
|
|
185
|
+
|
|
186
|
+
- name: How to verify the dry run
|
|
187
|
+
if: inputs.target == 'testpypi'
|
|
188
|
+
# TestPyPI holds only these two packages; the dependencies come from PyPI.
|
|
189
|
+
run: |
|
|
190
|
+
{
|
|
191
|
+
echo "## Dry run published to TestPyPI"
|
|
192
|
+
echo
|
|
193
|
+
echo "Verify in a fresh venv:"
|
|
194
|
+
echo
|
|
195
|
+
echo '```'
|
|
196
|
+
echo "pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ agent-instruction-protocol==${{ needs.build.outputs.version }}"
|
|
197
|
+
echo "aip --version"
|
|
198
|
+
echo '```'
|
|
199
|
+
} | tee -a "$GITHUB_STEP_SUMMARY"
|
|
200
|
+
|
|
201
|
+
github-release:
|
|
202
|
+
name: GitHub Release
|
|
203
|
+
if: inputs.target == 'pypi'
|
|
204
|
+
needs: [build, publish-runtime]
|
|
205
|
+
runs-on: ubuntu-latest
|
|
206
|
+
permissions:
|
|
207
|
+
contents: write # create the GitHub Release
|
|
208
|
+
steps:
|
|
209
|
+
- uses: actions/download-artifact@v4
|
|
210
|
+
with:
|
|
211
|
+
name: release-${{ needs.build.outputs.version }}
|
|
212
|
+
|
|
213
|
+
- name: Create GitHub Release
|
|
214
|
+
# After both publishes, so a publish failure doesn't leave behind a GitHub Release
|
|
215
|
+
# pointing at nothing on PyPI. The tag already exists; the action attaches to it.
|
|
216
|
+
uses: softprops/action-gh-release@v2
|
|
217
|
+
with:
|
|
218
|
+
tag_name: ${{ needs.build.outputs.tag }}
|
|
219
|
+
name: ${{ needs.build.outputs.tag }}
|
|
220
|
+
body_path: release-notes.md
|
|
221
|
+
files: dist/*
|
|
222
|
+
fail_on_unmatched_files: true
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.14
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Instructions for AI agents working **on** this repository. If you are an agent being asked to
|
|
4
|
+
*use* AIP, read `skills/aip-runtime/SKILL.md` (running a published procedure) or
|
|
5
|
+
`skills/aip-compile/SKILL.md` (compiling material into one) instead.
|
|
6
|
+
|
|
7
|
+
## What this repo is
|
|
8
|
+
|
|
9
|
+
The Agent Instruction Protocol (AIP): a format for procedures as graph-shaped Agent Skills, and
|
|
10
|
+
the runtime that executes them. Two Python packages live here as one uv workspace and release
|
|
11
|
+
together under one version:
|
|
12
|
+
|
|
13
|
+
| package | where | what |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `agent-instruction-protocol` | the root (`src/aip/`) | the runtime: the `aip` command, the Python SDK, `aip server`, the Neo4j and filesystem backends, the `aip-runtime` skill |
|
|
16
|
+
| `aip-spec` | `packages/aip-spec/` | the format: pydantic models, the JSON Schema generated from them, the runtime block every skill carries, the `aip-spec` validator CLI, the `aip-compile` skill and the example |
|
|
17
|
+
|
|
18
|
+
The distribution name of the runtime is `agent-instruction-protocol` (PyPI blocks `aip` as a
|
|
19
|
+
look-alike of an existing project); its module and command are `aip`. The runtime depends on
|
|
20
|
+
`aip-spec==<the same version>`. The web console is a separate repository,
|
|
21
|
+
[aip-console](https://github.com/zach-blumenfeld/aip-console), with its own npm version.
|
|
22
|
+
|
|
23
|
+
## Repo map
|
|
24
|
+
|
|
25
|
+
| Path | What's there |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `pyproject.toml` | the `agent-instruction-protocol` package and the uv workspace root (`[tool.uv.workspace] members = ["packages/*"]`); `testpaths` lists both packages' tests |
|
|
28
|
+
| `src/aip/client/` | the `aip` command (`cli.py`), the local runner, the executor that runs scripts and asks the decision model, the resolver, the HTTP client; `aip-runtime/SKILL.md` is the bundled copy of the runtime skill |
|
|
29
|
+
| `src/aip/model/` | the execution engine: steps, types, the environment a run carries, the procedure graph |
|
|
30
|
+
| `src/aip/server/` | `aip server`: the FastAPI app, catalog search, run records, governance, and `backends/` (Neo4j, filesystem) |
|
|
31
|
+
| `src/aip/spec/` | loads a skill folder through `aip_spec` into the runtime's model |
|
|
32
|
+
| `src/aip/sdk.py` | `aip.Client`, the runtime as a library; the CLI is a thin wrapper over it (`docs/sdk.md`) |
|
|
33
|
+
| `tests/` | the runtime's tests; `tests/server/` drives the HTTP API; the Neo4j backend tests skip unless `NEO4J_URI` is set |
|
|
34
|
+
| `packages/aip-spec/src/aip_spec/` | **where the format lives**: `models.py` (the pydantic models, `FORMAT_VERSION`, `SCHEMA_ID`, `SPEC_URL`), `runtime.md` (the runtime block; `runtime-0.5a1.md` and `runtime-0.6a0.md` are the earlier ones the validator still recognises), `cli.py` (`aip-spec validate`, `schema`, `runtime`, `skill`, `example`), `resources.py` (finds the skill and the example in a checkout or a wheel, `SKILL_NAME`, `LEGACY_SKILL_NAMES`), `agents.py` (the agent skills directories), `skill.py` |
|
|
35
|
+
| `packages/aip-spec/docs/specification.md` | the format specification as prose; the models are the source of truth |
|
|
36
|
+
| `packages/aip-spec/tests/` | the format's tests, including the schema-sync and runtime-block drift checks |
|
|
37
|
+
| `packages/aip-spec/hatch_build.py` | bundles `skills/aip-compile/` and `examples/` into the `aip_spec` wheel from the checkout or from the sdist |
|
|
38
|
+
| `skills/aip-compile/` | the authoring skill (`SKILL.md`, `references/`, `assets/procedure.schema.json`); reviewed line by line, keep diffs small |
|
|
39
|
+
| `skills/aip-runtime/` | the runtime skill agents read to run published procedures; `tests/test_runtime_skill.py` fails if it drifts from the copy under `src/aip/client/` or lags `FORMAT_VERSION` |
|
|
40
|
+
| `examples/billing-support/` | the bundled example skill; validation fails on `aip_version_mismatch` if the format moves without it |
|
|
41
|
+
| `docs/` | design and reference: `running.md`, `run-modes.md`, `state.md`, `client-execution.md`, `server-design.md`, `sdk.md`, `cli-json.md`, `upgrading.md` |
|
|
42
|
+
| `CHANGELOG.md` | one changelog for both packages; before `0.7.0` the two histories are interleaved and marked `(aip)` or `(aip-spec)` |
|
|
43
|
+
| `install.sh` | the one-command installer: uv, `aip-spec`, `agent-instruction-protocol[server]`, both skills, `aip skill prune` |
|
|
44
|
+
| `.github/workflows/release.yml` | the release workflow, below |
|
|
45
|
+
|
|
46
|
+
## Conventions
|
|
47
|
+
|
|
48
|
+
- **Python, built with `uv` and `hatchling`.** `uv sync --group dev` to set up; `uv run pytest -q`
|
|
49
|
+
at the root runs both packages' tests and must pass before any commit. No `pip install`, no
|
|
50
|
+
`python -m venv`.
|
|
51
|
+
- **One version, two pyprojects.** `pyproject.toml` and `packages/aip-spec/pyproject.toml` carry
|
|
52
|
+
the same `version`, and the root's dependency pin `aip-spec==<version>` matches. The workflow
|
|
53
|
+
refuses to release if the three differ.
|
|
54
|
+
- **Change the format in one place and let the tests find the rest.** `models.py` is normative;
|
|
55
|
+
`aip-spec schema` regenerates the JSON Schema, and the schema-sync test fails until
|
|
56
|
+
`skills/aip-compile/assets/procedure.schema.json` matches. The runtime block in `runtime.md`
|
|
57
|
+
is copied into every skill under its own heading; the drift tests compare the copies.
|
|
58
|
+
- **Do not change behaviour in a release branch.** If a test must change for a path, say so in
|
|
59
|
+
the commit; if it must change for a behaviour, stop and write it down in the plan issue.
|
|
60
|
+
- **Plans live in issues, not in the repo.** The roadmap is
|
|
61
|
+
[#20](https://github.com/zach-blumenfeld/aip/issues/20); each release has a plan issue with a
|
|
62
|
+
checklist of milestones, each naming the command that proves it. A fresh agent implements one
|
|
63
|
+
milestone per session: read the plan's "Context" and "Rules", then only the first unchecked
|
|
64
|
+
milestone; run its proof, tick it, comment `Done <date>, commit <sha>: <one sentence>`, commit.
|
|
65
|
+
Product-visible questions sit under "Open items" with a default; take the default and say so.
|
|
66
|
+
|
|
67
|
+
## Versioning
|
|
68
|
+
|
|
69
|
+
The rules, decided 2026-11-01 in the roadmap (#20):
|
|
70
|
+
|
|
71
|
+
- **Package version** `X.Y.Z` in both pyprojects, SemVer, pre-1.0 so breaking changes bump the
|
|
72
|
+
minor. Moves every release. PyPI distribution names: `agent-instruction-protocol` (import and
|
|
73
|
+
command `aip`) and `aip-spec`.
|
|
74
|
+
- **Format version** `X.Y` (`FORMAT_VERSION` in `models.py`, the runtime block heading of every
|
|
75
|
+
`SKILL.md`). It is the package's `major.minor` at the last release that changed the format. A
|
|
76
|
+
format change is breaking by definition, so it never happens in a patch release; the format has
|
|
77
|
+
no third number. An additive change (a new optional field) may ride on a patch release without
|
|
78
|
+
moving the format version.
|
|
79
|
+
- Concretely: 0.7.0 ships format `0.6a1`; 0.8.0 introduces `0.8`; 0.8.1 stays `0.8`; 0.9.0
|
|
80
|
+
introduces `0.9`.
|
|
81
|
+
- **Every format change ships `aip upgrade <folder>`** that rewrites a skill where the change is
|
|
82
|
+
mechanical, reports what it could not migrate, and validates the result. The validator's
|
|
83
|
+
outdated-format message names it.
|
|
84
|
+
- The console has its own package version (npm) and declares the minimum `aip` it works with
|
|
85
|
+
(`MINIMUM_AIP` in its `bin/aip-console.mjs`).
|
|
86
|
+
|
|
87
|
+
## Releasing
|
|
88
|
+
|
|
89
|
+
Releases are cut by the **`.github/workflows/release.yml`** workflow, **triggered manually**
|
|
90
|
+
(Actions → *Release to PyPI* → Run workflow) by a maintainer **after the release PR is merged to
|
|
91
|
+
`main`**. The workflow reads the version from both pyprojects and refuses if they differ or if
|
|
92
|
+
the tag already exists, builds all four distributions (`uv build --all-packages`), tags
|
|
93
|
+
`vX.Y.Z`, publishes `aip-spec` and then `agent-instruction-protocol` to PyPI with Trusted
|
|
94
|
+
Publishing (two jobs, two GitHub environments, `release-spec` then `release`, because PyPI
|
|
95
|
+
allows one publisher per environment; the spec goes first so the runtime's exact pin resolves
|
|
96
|
+
the moment it lands), and cuts a GitHub Release whose body is the matching `## [X.Y.Z]` section
|
|
97
|
+
of `CHANGELOG.md`.
|
|
98
|
+
|
|
99
|
+
Running it with `target: testpypi` is the dry run for a new or changed workflow: same checks,
|
|
100
|
+
same build, both uploads go to test.pypi.org, no tag and no GitHub Release, and the run ends by
|
|
101
|
+
printing the `pip install` line to verify with. TestPyPI refuses a filename it has seen before,
|
|
102
|
+
so a failed dry run cannot be repeated at the same version: fix the workflow, then rerun with
|
|
103
|
+
the version temporarily suffixed `.dev1` in both pyprojects on a scratch branch, or accept one
|
|
104
|
+
dry run per version.
|
|
105
|
+
|
|
106
|
+
So an agent's job for a release is **prep only — never build, tag, or publish by hand:**
|
|
107
|
+
|
|
108
|
+
1. **Align the version** in both `pyproject.toml` files and in the root's `aip-spec==` pin
|
|
109
|
+
(`version = "X.Y.Z"`; SemVer, pre-1.0 → breaking changes bump the minor), then `uv lock`.
|
|
110
|
+
2. **Finalize `CHANGELOG.md`**: roll `## [Unreleased]` into a single `## [X.Y.Z] — <date>`
|
|
111
|
+
section (one section per release — the workflow extracts just that one). The `## [X.Y.Z]`
|
|
112
|
+
heading format is **load-bearing** (awk-matched); leave a fresh empty `## [Unreleased]` above
|
|
113
|
+
it.
|
|
114
|
+
3. Open the release PR. The maintainer merges it and triggers the workflow.
|
|
115
|
+
|
|
116
|
+
The tags `vX.Y.Z` are shared by both packages; never move or force-push a published tag.
|
|
117
|
+
|
|
118
|
+
## When you're unsure
|
|
119
|
+
|
|
120
|
+
- For what a procedure may contain, `packages/aip-spec/docs/specification.md` is the prose and
|
|
121
|
+
`models.py` is the law.
|
|
122
|
+
- For how a run moves, `docs/running.md`, `docs/state.md` and `docs/run-modes.md`; for the
|
|
123
|
+
server, `docs/server-design.md` with `docs/client-execution.md` on top.
|
|
124
|
+
- For what agents see, the two `SKILL.md` files are the contract; a change to the runtime's
|
|
125
|
+
behaviour that they describe changes them in the same commit.
|