From 2c5b3e8f9ff213c419bd2b3cca41ed9b7a38cd4f Mon Sep 17 00:00:00 2001 From: Eric Mann Date: Thu, 29 Oct 2026 09:56:27 -0700 Subject: [PATCH 1/4] ci: unpin setup-php, restore PHP 8.5 on macOS, weekly schedule, Dependabot - setup-php 2.36.0 -> @v2: the June 2026 macOS breakage was fixed upstream in 2.37.2 (verified by ext-template's probe, ext-template#1), and versions below 2.37.1 carry published advisories. - The PHP 8.5 x macos-14 exclusion is gone with it. - Weekly schedule + workflow_dispatch, so the badge means "green this week"; grouped weekly Dependabot PRs for composer and actions keep the schedule alive (GitHub disables it after 60 days without activity). --- .github/dependabot.yml | 28 ++++++++++++++++++++++++++++ .github/workflows/ci.yml | 24 +++++++++--------------- 2 files changed, 37 insertions(+), 15 deletions(-) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..a09e058 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,28 @@ +# Weekly, grouped updates for the dev toolchain (PHPUnit, PHPStan, +# php-cs-fixer) and the workflow actions. The merged PRs are also what +# keep the scheduled CI run alive: GitHub disables schedules in public +# repos after 60 days without activity. +version: 2 +updates: + - package-ecosystem: composer + directory: / + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 + commit-message: + prefix: "chore(deps)" + groups: + composer-minor-patch: + update-types: [minor, patch] + + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + day: monday + commit-message: + prefix: "chore(actions)" + groups: + actions: + patterns: ["*"] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a0d2957..e6d8e2f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,6 +4,13 @@ on: push: branches: [main] pull_request: + # Weekly run against fresh runners and PHP patch releases, so a green + # badge means "green this week". GitHub disables scheduled workflows in + # public repos after 60 days with no repository activity; the weekly + # Dependabot PRs (and merging them) are what keep this schedule alive. + schedule: + - cron: '29 6 * * 1' # Mondays 06:29 UTC + workflow_dispatch: env: # Opt every JavaScript-based action into the Node 24 runtime ahead of @@ -20,10 +27,7 @@ jobs: steps: - uses: actions/checkout@v4 - # Pinned to 2.36.0: setup-php 2.37.x stopped installing PHP on the - # macos-14 runners on 2026-06-12 (probe in DisplaceTech/ext-template). - # Unpin when upstream ships a fix. - - uses: shivammathur/setup-php@2.36.0 + - uses: shivammathur/setup-php@v2 with: php-version: '8.4' coverage: none @@ -47,20 +51,10 @@ jobs: # 8.5 is the current stable; 8.4 is the most-deployed; 8.3 is # security-only through end of 2026 but still widely installed. php: ['8.3', '8.4', '8.5'] - exclude: - # setup-php cannot currently install PHP 8.5 on the macos-14 - # runners (2026-06-12: 2.37.x fails for every PHP version there, - # and 2.36.0 predates 8.5). Re-add this leg when ext-template's - # "macOS probe" workflow passes on @v2 again. - - os: macos-14 - php: '8.5' steps: - uses: actions/checkout@v4 - # Pinned to 2.36.0: setup-php 2.37.x stopped installing PHP on the - # macos-14 runners on 2026-06-12 (probe in DisplaceTech/ext-template). - # Unpin when upstream ships a fix. - - uses: shivammathur/setup-php@2.36.0 + - uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} coverage: none From 4fd7475088b22896e67a3d31a8422e40d95026a7 Mon Sep 17 00:00:00 2001 From: Eric Mann Date: Thu, 29 Oct 2026 09:56:27 -0700 Subject: [PATCH 2/4] docs: status, stack table, writing links; PLAN.md as design notes Remaining ideas moved to `future` issues; the deliberately-out-of-scope section is unchanged. --- PLAN.md | 22 ++++++++++++---------- README.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 10 deletions(-) diff --git a/PLAN.md b/PLAN.md index e63aabe..5ed2e6c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,10 +1,14 @@ -# ai-toolkit — Plan +# ai-toolkit — design notes Part of the [phpai stack](https://github.com/DisplaceTech). Pure-PHP utilities every doc example wants; boring on purpose. No models, no extensions, no framework ambitions. -## v0.1.0 scope (current) +This file holds design notes and decision history, not a to-do list. +What shipped is in [`CHANGELOG.md`](CHANGELOG.md); remaining ideas are +[`future` issues](https://github.com/DisplaceTech/ai-toolkit/issues?q=is%3Aissue+is%3Aopen+label%3Afuture), each with its reasoning. + +## v0.1.0 scope (shipped 2026-06-11) - [x] `Vector\Packed` — pack/unpack, dot, cosine, norm, per-vector normalize, MRL truncation over packed float32 buffers. @@ -19,15 +23,13 @@ extensions, no framework ambitions. - [x] Rewrite ext-infer / ext-turbovec doc examples on these helpers where it clarifies — done 2026-06-11 (recipes in both repos). -## Later (unscheduled) +## Remaining work + +Tracked as [`future` issues](https://github.com/DisplaceTech/ai-toolkit/issues?q=is%3Aissue+is%3Aopen+label%3Afuture): -- Markdown-aware chunker (split on headings before paragraphs) if doc - examples keep wanting it. -- `Packed::topK()` brute-force search helper — only if a doc example - needs search without ext-turbovec; otherwise it competes with the - extension for no reason. -- Token-count estimation helper — only with a credible accuracy story; - ~4 chars/token guidance lives in the README until then. +- [#1](https://github.com/DisplaceTech/ai-toolkit/issues/1) Markdown-aware chunker +- [#2](https://github.com/DisplaceTech/ai-toolkit/issues/2) `Packed::topK()` brute-force helper, only if a doc example needs it +- [#3](https://github.com/DisplaceTech/ai-toolkit/issues/3) Token-count estimation helper, only with a credible accuracy story ## Design notes diff --git a/README.md b/README.md index 3dc185d..253ae88 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,16 @@ --- +## Status + +Feature-complete for its scope. Maintained: dependency updates and +compatibility fixes ship as patch/minor releases — see the +[CHANGELOG](CHANGELOG.md). Last verified: PHP 8.3/8.4/8.5 on Linux x86_64 and macOS arm64, `ext-mbstring` only, 2026-10-29. + +Remaining ideas are tracked as [`future` issues](https://github.com/DisplaceTech/ai-toolkit/issues?q=is%3Aissue+is%3Aopen+label%3Afuture). +**Co-maintainers welcome** — if you run this in production and want a +say in where it goes, open an issue or a PR. + ## What is ai-toolkit? The plumbing every embed-and-search pipeline needs and no one wants to @@ -106,6 +116,30 @@ database · **document loaders/parsers** (PDF, HTML, ...) — bring your own text · **an orchestration framework** — chains and agents belong to the frameworks. +## Part of a stack + +Transcribe → chunk → embed → search → answer, entirely on your hardware: + +| Stage | Package | What it does | +| ----- | ------- | ------------ | +| Transcribe | [ext-whisper](https://github.com/DisplaceTech/ext-whisper) | Speech-to-text over whisper.cpp | +| Chunk | **ai-toolkit** (this repo) | Text chunkers and packed-vector math, pure PHP | +| Embed · rerank · answer | [ext-infer](https://github.com/DisplaceTech/ext-infer) | Local LLM chat, embeddings and reranking over llama.cpp | +| Search | [ext-turbovec](https://github.com/DisplaceTech/ext-turbovec) | Compressed in-memory vector search (TurboQuant) | +| Integrate | [ai-contracts](https://github.com/DisplaceTech/ai-contracts) | The interfaces frameworks code against | +| Reference app | [rag-over-markdown](https://github.com/DisplaceTech/rag-over-markdown) | The whole pipeline over a folder of markdown | + +Every package links the others; the extensions share one scaffold, +[ext-template](https://github.com/DisplaceTech/ext-template). + +## Writing about this + +- [ai-contracts & ai-toolkit: The Primitives a PHP AI Ecosystem Needs](https://eric.mann.blog/ai-contracts-ai-toolkit-php-primitives/) +- [RAG Over Markdown: An End-to-End Local Pipeline in Pure PHP](https://eric.mann.blog/rag-over-markdown-local-pipeline-php/) + +The stack's launch series ran Sept 22 – Oct 1, 2026; everything else +is at [eric.mann.blog/writing](https://eric.mann.blog/writing/). + ## License [MIT](LICENSE) © 2026 Eric Mann / Displace Technologies From fc3e00ff8953c1fd0ac3343b783d970ac30c7fdc Mon Sep 17 00:00:00 2001 From: Eric Mann Date: Thu, 29 Oct 2026 09:56:27 -0700 Subject: [PATCH 3/4] =?UTF-8?q?chore(release):=20prepare=20v0.1.1=20?= =?UTF-8?q?=E2=80=94=20CHANGELOG?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keep a Changelog, backfilled from v0.1.0. Not tagged; the maintainer tags after merge. --- CHANGELOG.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2df8170 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,35 @@ +# Changelog + +All notable changes to ai-toolkit are documented here. The format is +based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and +this project adheres to [Semantic Versioning](https://semver.org/). +Chunk-boundary algorithm changes are always minor releases, even when +signature-compatible. Dates are tag dates. + +## [0.1.1] - Unreleased + +No code changes; chunk boundaries are identical to 0.1.0. + +### Changed + +- CI runs weekly as well as on push, and tests PHP 8.5 on macOS arm64 + again; setup-php is unpinned from 2.36.0, which carried known + advisories. Dependabot keeps the dev toolchain and actions current. +- README: Status section, stack table, links to the write-up; PLAN.md + reframed as design notes; remaining ideas moved to `future` issues. + +## [0.1.0] - 2026-06-11 + +First release. + +### Added + +- Text chunkers behind one `Chunker` interface, sized in characters + (multibyte-aware) with a hard `mb_strlen($chunk) <= $size` invariant: + `RecursiveCharacterChunker`, `SentenceChunker`, `FixedSizeChunker`. +- `Vector\Packed`: `pack()` / `unpack()`, `dot()`, `cosine()`, `norm()`, + per-vector `normalize()`, and Matryoshka `truncate()` over packed + float32 buffers. + +[0.1.1]: https://github.com/DisplaceTech/ai-toolkit/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/DisplaceTech/ai-toolkit/releases/tag/v0.1.0 From e751f67ddbd527e308266e6e21201ce81286bc93 Mon Sep 17 00:00:00 2001 From: Eric Mann Date: Thu, 29 Oct 2026 10:58:18 -0700 Subject: [PATCH 4/4] =?UTF-8?q?chore(release):=20v0.1.1=20=E2=80=94=202026?= =?UTF-8?q?-10-29?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2df8170..a826186 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ this project adheres to [Semantic Versioning](https://semver.org/). Chunk-boundary algorithm changes are always minor releases, even when signature-compatible. Dates are tag dates. -## [0.1.1] - Unreleased +## [0.1.1] - 2026-10-29 No code changes; chunk boundaries are identical to 0.1.0.