Split http-pool from http-client

Author: ddebowczyk

.github/workflows/split.yml

@@ -83,6 +83,9 @@ jobs:
           - local: 'packages/http-client'
             repo:  'cognesy/instructor-http-client'
             name:  'instructor-http-client'
+          - local: 'packages/http-pool'
+            repo:  'cognesy/instructor-http-pool'
+            name:  'instructor-http-pool'
           - local: 'packages/hub'
             repo:  'cognesy/instructor-hub'
             name:  'instructor-hub'

.github/workflows/split.yml.bak

@@ -0,0 +1,123 @@
+# Adding a Package
+
+This monorepo treats each package as a first-class split package.
+
+Use this checklist when adding a new package.
+
+## 1. Create The Package
+
+Create the package directory under `packages/<name>` with:
+
+- `src/`
+- `tests/`
+- `composer.json`
+- `README.md`
+- `CHEATSHEET.md`
+- `docs/`
+
+For docs, keep the initial structure small:
+
+- `docs/_meta.yaml`
+- `docs/overview.md`
+- `docs/quickstart.md`
+
+## 2. Register It In The Monorepo
+
+Add the package to [packages.json](/Users/ddebowczyk/projects/instructor-php/packages.json):
+
+```json
+{
+  "local": "packages/http-pool",
+  "repo": "cognesy/instructor-http-pool",
+  "github_name": "instructor-http-pool",
+  "composer_name": "cognesy/instructor-http-pool"
+}
+```
+
+Then update:
+
+- root `composer.json` autoload and autoload-dev
+- root `README.md`
+- [CONTENTS.md](/Users/ddebowczyk/projects/instructor-php/CONTENTS.md)
+- [CONTRIBUTOR_GUIDE.md](/Users/ddebowczyk/projects/instructor-php/CONTRIBUTOR_GUIDE.md)
+- any docs registries under `packages/*/resources/config/docs.yaml` or `.yml`
+
+If the package adds public docs, give it:
+
+- a description in each docs config
+- a stable place in package order
+
+## 3. Regenerate Split Workflow
+
+Run:
+
+```bash
+./scripts/update-split-yml.sh .
+```
+
+This regenerates the package matrix in `.github/workflows/split.yml` from `packages.json`.
+
+## 4. Create The GitHub Repo
+
+Create the split repository with `gh`:
+
+```bash
+gh repo create cognesy/instructor-http-pool \
+  --public \
+  --description "Concurrent HTTP request execution for Instructor"
+```
+
+Verify it exists:
+
+```bash
+gh repo view cognesy/instructor-http-pool --json name,url,visibility
+```
+
+## 5. Add The Package To Packagist
+
+Default path: manual.
+
+1. Open `https://packagist.org/packages/submit`
+2. Submit the split repository URL, for example:
+   `https://github.com/cognesy/instructor-http-pool`
+3. Confirm the package name from `composer.json`
+4. In Packagist package settings, enable the GitHub hook or auto-update
+
+If you want to automate this later, use a Packagist token and their API. That is not part of the current default workflow.
+
+## 6. Verify The Package Is Discoverable
+
+Check:
+
+- docs autodiscovery sees `packages/<name>/docs`
+- split workflow contains the package
+- root Composer autoload includes the namespace
+- package `composer.json` is valid
+
+Useful checks:
+
+```bash
+composer validate packages/http-pool/composer.json
+rg "http-pool" packages.json .github/workflows/split.yml packages/*/resources/config
+```
+
+## 7. Run Focused QA
+
+At minimum:
+
+```bash
+composer validate packages/http-pool/composer.json
+php vendor/bin/pest packages/http-pool/tests
+```
+
+If the package changes shared infrastructure, also run:
+
+```bash
+composer test
+```
+
+## Notes
+
+- `packages.json` is the source of truth for split-package registration.
+- `update-split-yml.sh` should be used instead of editing `.github/workflows/split.yml` by hand.
+- Keep package docs minimal at first. Add more only when the API stabilizes.

ADDING-PACKAGE.md

@@ -13,6 +13,7 @@ Contains all independent PHP packages that make up the Instructor ecosystem. Eac
 - **Agents SDK**: `agents` - SDK for building custom AI agents
 - **Observability**: `metrics`, `logging`
 - **HTTP client**: `http-client`
+- **HTTP pooling**: `http-pool`
 - **Pipeline processing**: `pipeline`
 - **Sandbox**: `sandbox` - Safe code execution environment
 

CONTENTS.md

@@ -12,6 +12,7 @@ This is a monorepo containing multiple independent packages under the `packages/
 - **Agent control**: `agent-ctrl` - Unified CLI bridge for code agents
 - **Observability**: `metrics` - metrics collection and export
 - **HTTP client**: `http-client`
+- **HTTP pooling**: `http-pool`
 - **Pipeline processing**: `pipeline`
 
 Each package is independently publishable to Packagist with its own `composer.json`, tests, and documentation.

CONTRIBUTOR_GUIDE.md

@@ -377,6 +377,7 @@ Links to read-only repositories of the standalone package distributions:
 - [instructor-evals](https://github.com/cognesy/instructor-evals) - LLM output evaluation tools
 - [instructor-events](https://github.com/cognesy/instructor-events) - events and event listeners for Instructor
 - [instructor-http-client](https://github.com/cognesy/instructor-http-client) - easily switch between underlying HTTP client libraries (out-of-the-box support for Guzzle, Symfony, Laravel)
+- [instructor-http-pool](https://github.com/cognesy/instructor-http-pool) - concurrent HTTP request execution for fan-out workloads
 - [instructor-hub](https://github.com/cognesy/instructor-hub) - CLI tool for browsing and running Instructor examples
 - [instructor-messages](https://github.com/cognesy/instructor-messages) - chat message sequence handling for Instructor
 - [instructor-polyglot](https://github.com/cognesy/instructor-polyglot) - use single API for inference and embeddings across most of LLM providers, easily switch between them (e.g., develop on Ollama, switch to Groq in production)

README.md

@@ -25,7 +25,7 @@ $result = SandboxCommandExecutor::forOpenCode()->execute($spec);
 $response = (new ResponseParser())->parse($result, OutputFormat::Json);
 
 echo $response->messageText();
-// @doctest id="8cd5"
+// @doctest id="5913"
 ```
 
 ## Session Handling

builds/docs-build/packages/agent-ctrl/10-opencode-bridge.mdx

@@ -7,7 +7,7 @@ description: 'Run your first prompt with AgentCtrl.'
 
 ```bash
 composer require cognesy/agent-ctrl
-# @doctest id="746d"
+# @doctest id="4be1"
 ```
 
 You need at least one CLI binary installed and authenticated (`claude`, `codex`, or `opencode`).
@@ -20,7 +20,7 @@ use Cognesy\AgentCtrl\AgentCtrl;
 $response = AgentCtrl::codex()->execute('Summarize this repository.');
 
 echo $response->text();
-// @doctest id="e800"
+// @doctest id="6a9a"
 ```
 
 ## Runtime Agent Selection
@@ -31,5 +31,5 @@ use Cognesy\AgentCtrl\Enum\AgentType;
 
 $agent = AgentType::from('codex');
 $response = AgentCtrl::make($agent)->execute('List top risks in this code.');
-// @doctest id="69f2"
+// @doctest id="1033"
 ```

builds/docs-build/packages/agent-ctrl/2-getting-started.mdx

@@ -15,7 +15,7 @@ $response = AgentCtrl::openCode()
     ->onComplete(fn(AgentResponse $response) => print("\n[done]\n"))
     ->onError(fn(string $message, ?string $code) => print("\n[error:$message]\n"))
     ->executeStreaming('Explain this package architecture.');
-// @doctest id="4c1c"
+// @doctest id="846c"
 ```
 
 `execute()` is a non-streaming convenience method.

builds/docs-build/packages/agent-ctrl/3-streaming.mdx

@@ -13,7 +13,7 @@ use Cognesy\AgentCtrl\AgentCtrl;
 $response = AgentCtrl::codex()
     ->continueSession()
     ->execute('Continue from the previous plan and apply step 2.');
-// @doctest id="8963"
+// @doctest id="2c93"
 ```
 
 ## Resume Specific Session
@@ -29,7 +29,7 @@ if ($sessionId !== null) {
         ->resumeSession((string) $sessionId)
         ->execute('Now implement the first migration.');
 }
-// @doctest id="9a67"
+// @doctest id="800c"
 ```
 
 `sessionId()` returns `AgentSessionId|null`.