replicate
diff --git a/‎.github/workflows/ci.yaml‎
Lines changed: 38 additions & 0 deletions b/‎.github/workflows/ci.yaml‎
Lines changed: 38 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎ARCHITECTURE.md‎
Lines changed: 600 additions & 0 deletions b/‎ARCHITECTURE.md‎
Lines changed: 600 additions & 0 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 96 additions & 19 deletions b/‎CONTRIBUTING.md‎
Lines changed: 96 additions & 19 deletions
diff --git a/‎Makefile‎
Lines changed: 8 additions & 0 deletions b/‎Makefile‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎integration-tests/.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎integration-tests/.gitignore‎
Lines changed: 1 addition & 0 deletions
@@ -62,6 +62,7 @@ jobs:
       - test-go
       - test-python
       - test-integration
+      - test-integration-go
       - test-coglet-go
       - test-coglet-python
     runs-on: ubuntu-latest
@@ -155,6 +156,43 @@ jobs:
       - name: Test coglet Python
         run: uv run --project coglet pytest coglet/python/tests -v
 
+  # Go-based integration tests using testscript framework
+  test-integration-go:
+    name: "Test integration Go (${{ matrix.runtime }})"
+    needs: build-python
+    runs-on: ubuntu-latest-16-cores
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [cog, coglet-alpha]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          registry: index.docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Download built wheels
+        uses: actions/download-artifact@v6
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: Build cog binary
+        run: make cog
+      - name: Run Go integration tests
+        env:
+          COG_WHEEL: ${{ matrix.runtime }}
+          COG_BINARY: ./cog
+          TEST_PARALLEL: 8
+        run: make test-integration-go
+
   # TODO[md]: This is a gross hack, remove once this is sorted out: https://github.com/replicate/cog/pull/2353
   # cannot run this on mac due to licensing issues: https://github.com/actions/virtual-environments/issues/2150
   test-integration:
 
@@ -29,3 +29,6 @@ coglet/python/coglet/_version.py
 
 # Built coglet-server binaries
 coglet/python/cog/bin/
+
+# Local planning files
+docs/plans/**
@@ -144,7 +144,8 @@ As much as possible, this is attempting to follow the [Standard Go Project Layou
 - `pkg/predict/` - Runs predictions on models.
 - `pkg/util/` - Various packages that aren't part of Cog. They could reasonably be separate re-usable projects.
 - `python/` - The Cog Python library.
-- `test-integration/` - High-level integration tests for Cog.
+- `integration-tests/` - Go-based integration tests using testscript (primary test suite).
+- `test-integration/` - Legacy Python integration tests (supplementary - CLI flags and tooling).
 - `tools/compatgen/` - Tool for generating CUDA/PyTorch/TensorFlow compatibility matrices.
 
 ## Updating compatibility matrices
@@ -188,7 +189,7 @@ There are a few concepts used throughout Cog that might be helpful to understand
 script/test # see also: make test
 ```
 
-**To run just the Golang tests:**
+**To run just the Go unit tests:**
 
 ```sh
 script/test-go # see also: make test-go
@@ -203,38 +204,114 @@ script/test-python # see also: make test-python
 > [!INFO]
 > This runs the Python test suite using the default Python version. To run a more comprehensive test across multiple Python versions, use `make test-python`.
 
-**To run just the integration tests:**
+### Integration Tests
+
+Cog has two integration test suites that are complementary:
+
+**Go integration tests (primary - 60 tests):**
+
+Tests core predictor functionality using [testscript](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript). Each test is a self-contained `.txtar` file in `integration-tests/tests/`.
 
 ```sh
-make test-integration
+# Run all Go integration tests
+make test-integration-go
+
+# Run fast tests only (skip slow GPU/framework tests)
+COG_TEST_FAST=1 make test-integration-go
+
+# Run a specific test
+cd integration-tests && go test -v -run TestIntegration/string_predictor
+
+# Run with a custom cog binary
+COG_BINARY=/path/to/cog make test-integration-go
 ```
 
-**To run a specific Python test:**
+**Python integration tests (supplementary - 37 tests):**
+
+Tests CLI flags, `cog run`, and other tooling features using pytest.
 
 ```sh
-script/test-python python/tests/server/test_http.py::test_openapi_specification_with_yield
+# Run all Python integration tests
+make test-integration
+
+# Run a specific Python integration test
+cd test-integration && uv run tox -e integration -- test_integration/test_build.py::test_build_gpu_model_on_cpu
 ```
 
-**To run a specific Python test under a specific environment**
+**Integration test coverage:**
+- **Go tests**: Core predictors, types, builds, training, subprocess behavior, HTTP server testing
+- **Python tests**: CLI flags (`--json`, `-o`), commands (`cog run`, `cog init`), edge cases
 
-```sh
-uv run tox -e py312-pydantic2-tests -- python/tests/server/test_http.py::test_openapi_specification_with_yield
+### Writing Integration Tests
+
+When adding new functionality, prefer adding Go integration tests in `integration-tests/tests/`. They are:
+- Self-contained (embedded fixtures in `.txtar` files)
+- Faster to run (parallel execution with automatic cleanup)
+- Easier to read and write (simple command script format)
+
+Example test structure:
+
+```txtar
+# Test string predictor
+cog build -t $TEST_IMAGE
+cog predict $TEST_IMAGE -i s=world
+stdout 'hello world'
+
+-- cog.yaml --
+build:
+  python_version: "3.12"
+predict: "predict.py:Predictor"
+
+-- predict.py --
+from cog import BasePredictor
+
+class Predictor(BasePredictor):
+    def predict(self, s: str) -> str:
+        return "hello " + s
 ```
 
-_You can see all the available test environments under `env_list` in the tox.ini file_
+For testing `cog serve`, use `cog serve` and the `curl` command:
 
-**To stand up a server for one of the integration tests:**
+```txtar
+cog build -t $TEST_IMAGE
+cog serve
+curl POST /predictions '{"input":{"s":"test"}}'
+stdout '"output":"hello test"'
+```
 
-```sh
-make install
-pip install -r requirements-dev.txt
-make test
-cd test-integration/test_integration/fixtures/file-project
-cog build
-docker run -p 5001:5000 --init --platform=linux/amd64 cog-file-project
+#### Advanced Test Commands
+
+For tests that require subprocess initialization or async operations, use `retry-curl`:
+
+**`retry-curl` - HTTP request with automatic retries:**
+
+```txtar
+# Make HTTP request with retry logic (useful for subprocess initialization delays)
+# retry-curl [method] [path] [body] [max-attempts] [retry-delay]
+retry-curl POST /predictions '{"input":{"s":"test"}}' 30 1s
+stdout '"output":"hello test"'
+```
+
+**Example: Testing predictor with subprocess in setup**
+
+```txtar
+cog build -t $TEST_IMAGE
+cog serve
+
+# Use generous retries since setup spawns a background process
+retry-curl POST /predictions '{"input":{"s":"test"}}' 30 1s
+stdout '"output":"hello test"'
+
+-- predict.py --
+class Predictor(BasePredictor):
+    def setup(self):
+        self.process = subprocess.Popen(["./background.sh"])
+    
+    def predict(self, s: str) -> str:
+        return "hello " + s
 ```
 
-Then visit [localhost:5001](http://localhost:5001) in your browser.
+See existing tests in `integration-tests/tests/`, especially `setup_subprocess_*.txtar`, for more examples.
 
 ## Running the docs server
 
 
@@ -55,6 +55,14 @@ test-integration: $(COG_BINARIES)
 	$(GO) test ./pkg/docker/...
 	PATH="$(PWD):$(PATH)" $(TOX) -e integration
 
+# Run Go-based integration tests (testscript)
+# Use TEST_PARALLEL to control concurrency (default 4 to avoid Docker overload)
+# CI with more cores can set TEST_PARALLEL=8 or higher
+TEST_PARALLEL ?= 4
+.PHONY: test-integration-go
+test-integration-go:
+	cd integration-tests && $(GO) test -v -parallel $(TEST_PARALLEL) -timeout 30m $(ARGS) .
+
 .PHONY: test-python
 test-python: generate
 	$(TOX) run --installpkg $$(ls dist/cog-*.whl) -f tests
 
@@ -0,0 +1 @@
+.bin/