From 5145eb9be46375e25e445267be2eaa76fc5e0850 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Lange?= Date: Sun, 15 Mar 2026 23:43:23 +0100 Subject: [PATCH] docs(onboarding): add first v1.1 starter wave --- README.md | 1 + docs/INTEGRATIONS.md | 41 +++++++++++ docs/ONBOARDING.md | 17 +++++ .../langchain-foundrygate.env.example | 6 ++ .../langgraph-foundrygate.env.example | 6 ++ .../paperclip-foundrygate.env.example | 6 ++ .../ship-faster-foundrygate.env.example | 6 ++ docs/examples/swe-af-foundrygate.env.example | 6 ++ foundrygate/onboarding.py | 72 +++++++++++++++++++ 9 files changed, 161 insertions(+) create mode 100644 docs/examples/langchain-foundrygate.env.example create mode 100644 docs/examples/langgraph-foundrygate.env.example create mode 100644 docs/examples/paperclip-foundrygate.env.example create mode 100644 docs/examples/ship-faster-foundrygate.env.example create mode 100644 docs/examples/swe-af-foundrygate.env.example diff --git a/README.md b/README.md index 4fb5640..c80ef09 100644 --- a/README.md +++ b/README.md @@ -171,6 +171,7 @@ Start here for the deeper deployment details: - [Integrations](./docs/INTEGRATIONS.md) - [Onboarding](./docs/ONBOARDING.md) - [Examples](./docs/examples) +- [First-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#first-wave-template-set-for-v110) - [Security review for `v1.0.0`](./docs/SECURITY-REVIEW-v1.0.0.md) - [Publishing](./docs/PUBLISHING.md) - [Troubleshooting](./docs/TROUBLESHOOTING.md) diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md index a984fc4..a929358 100644 --- a/docs/INTEGRATIONS.md +++ b/docs/INTEGRATIONS.md @@ -113,6 +113,47 @@ Starter snippet: - [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml) +## First-wave agent and framework starters + +The first post-`1.0` expansion wave focuses on clients that can already use FoundryGate cleanly through the common OpenAI-compatible path. + +### SWE-AF + +- starter: [examples/swe-af-foundrygate.env.example](./examples/swe-af-foundrygate.env.example) +- recommended header: `X-FoundryGate-Client: swe-af` +- recommended profile name: `swe-af` + +### paperclip + +- starter: [examples/paperclip-foundrygate.env.example](./examples/paperclip-foundrygate.env.example) +- recommended header: `X-FoundryGate-Client: paperclip` +- recommended profile name: `paperclip` + +### ship-faster + +- starter: [examples/ship-faster-foundrygate.env.example](./examples/ship-faster-foundrygate.env.example) +- recommended header: `X-FoundryGate-Client: ship-faster` +- recommended profile name: `ship-faster` + +### LangChain + +- starter: [examples/langchain-foundrygate.env.example](./examples/langchain-foundrygate.env.example) +- recommended header: `X-FoundryGate-Client: langchain` +- recommended profile name: `langchain` + +### LangGraph + +- starter: [examples/langgraph-foundrygate.env.example](./examples/langgraph-foundrygate.env.example) +- recommended header: `X-FoundryGate-Client: langgraph` +- recommended profile name: `langgraph` + +These starters are intentionally small: + +- keep one local OpenAI-compatible base URL +- keep one stable client tag +- use client profiles only when the framework traffic really needs distinct routing behavior +- validate with `POST /api/route` and `GET /api/traces` before adding policies or hooks + ## Provider onboarding When onboarding a new provider: diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index a1bea5c..55440a0 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -150,6 +150,23 @@ Starter files: - [examples/n8n-foundrygate-http-request.json](./examples/n8n-foundrygate-http-request.json) - [examples/cli-foundrygate-env.sh](./examples/cli-foundrygate-env.sh) - [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml) +- [examples/swe-af-foundrygate.env.example](./examples/swe-af-foundrygate.env.example) +- [examples/paperclip-foundrygate.env.example](./examples/paperclip-foundrygate.env.example) +- [examples/ship-faster-foundrygate.env.example](./examples/ship-faster-foundrygate.env.example) +- [examples/langchain-foundrygate.env.example](./examples/langchain-foundrygate.env.example) +- [examples/langgraph-foundrygate.env.example](./examples/langgraph-foundrygate.env.example) + +### 3b. First-wave framework starters + +The first post-`1.0` framework wave keeps every client on the same OpenAI-compatible entry point and varies only the stable client tag: + +- `SWE-AF` -> `X-FoundryGate-Client: swe-af` +- `paperclip` -> `X-FoundryGate-Client: paperclip` +- `ship-faster` -> `X-FoundryGate-Client: ship-faster` +- `LangChain` -> `X-FoundryGate-Client: langchain` +- `LangGraph` -> `X-FoundryGate-Client: langgraph` + +Use the starter env files above first, then add explicit profile rules only if one framework needs different locality, provider, or cost behavior. ### 4. Add request hooks only if needed diff --git a/docs/examples/langchain-foundrygate.env.example b/docs/examples/langchain-foundrygate.env.example new file mode 100644 index 0000000..a83b6cc --- /dev/null +++ b/docs/examples/langchain-foundrygate.env.example @@ -0,0 +1,6 @@ +# Example FoundryGate environment for LangChain / LangGraph stacks. + +export OPENAI_API_KEY="local" +export OPENAI_BASE_URL="http://127.0.0.1:8090/v1" +export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: langchain" + diff --git a/docs/examples/langgraph-foundrygate.env.example b/docs/examples/langgraph-foundrygate.env.example new file mode 100644 index 0000000..ab3a628 --- /dev/null +++ b/docs/examples/langgraph-foundrygate.env.example @@ -0,0 +1,6 @@ +# Example FoundryGate environment for LangGraph applications. + +export OPENAI_API_KEY="local" +export OPENAI_BASE_URL="http://127.0.0.1:8090/v1" +export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: langgraph" + diff --git a/docs/examples/paperclip-foundrygate.env.example b/docs/examples/paperclip-foundrygate.env.example new file mode 100644 index 0000000..ae3577b --- /dev/null +++ b/docs/examples/paperclip-foundrygate.env.example @@ -0,0 +1,6 @@ +# Example FoundryGate environment for Paperclip. + +export OPENAI_BASE_URL="http://127.0.0.1:8090/v1" +export OPENAI_API_KEY="local" +export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: paperclip" + diff --git a/docs/examples/ship-faster-foundrygate.env.example b/docs/examples/ship-faster-foundrygate.env.example new file mode 100644 index 0000000..b7606a6 --- /dev/null +++ b/docs/examples/ship-faster-foundrygate.env.example @@ -0,0 +1,6 @@ +# Example FoundryGate environment for ship-faster. + +export OPENAI_BASE_URL="http://127.0.0.1:8090/v1" +export OPENAI_API_KEY="local" +export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: ship-faster" + diff --git a/docs/examples/swe-af-foundrygate.env.example b/docs/examples/swe-af-foundrygate.env.example new file mode 100644 index 0000000..aeaf2d1 --- /dev/null +++ b/docs/examples/swe-af-foundrygate.env.example @@ -0,0 +1,6 @@ +# Example FoundryGate environment for SWE-AF. + +export OPENAI_BASE_URL="http://127.0.0.1:8090/v1" +export OPENAI_API_KEY="local" +export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: swe-af" + diff --git a/foundrygate/onboarding.py b/foundrygate/onboarding.py index 5da9102..3e826cc 100644 --- a/foundrygate/onboarding.py +++ b/foundrygate/onboarding.py @@ -348,6 +348,78 @@ def build_onboarding_report( " truly needs them.", ], }, + "swe-af": { + "recommended": "swe-af" in profile_names, + "header": "X-FoundryGate-Client: swe-af", + "profile": "swe-af", + "snippet": [ + "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1", + "export OPENAI_API_KEY=local", + ], + "notes": [ + "Treat SWE-AF like another OpenAI-compatible agent client first, not a" + " special runtime.", + "Keep a stable client header so coding and delegated subflows remain" + " attributable in traces.", + ], + }, + "paperclip": { + "recommended": "paperclip" in profile_names, + "header": "X-FoundryGate-Client: paperclip", + "profile": "paperclip", + "snippet": [ + "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1", + "export OPENAI_API_KEY=local", + ], + "notes": [ + "Start with the common OpenAI-compatible path before inventing a deeper adapter.", + "Use client profiles only when paperclip traffic should differ from" + " other app traffic.", + ], + }, + "ship-faster": { + "recommended": "ship-faster" in profile_names, + "header": "X-FoundryGate-Client: ship-faster", + "profile": "ship-faster", + "snippet": [ + "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1", + "export OPENAI_API_KEY=local", + ], + "notes": [ + "Use one short client tag first; add more profile splits only when the" + " workflow actually needs them.", + "Prefer hook-based overrides only for narrow rollout or locality constraints.", + ], + }, + "langchain": { + "recommended": "langchain" in profile_names, + "header": "X-FoundryGate-Client: langchain", + "profile": "langchain", + "snippet": [ + "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1", + "export OPENAI_API_KEY=local", + ], + "notes": [ + "LangChain should stay on the OpenAI-compatible path unless a" + " framework-specific blocker appears.", + "Use route previews before splitting chain traffic into multiple custom profiles.", + ], + }, + "langgraph": { + "recommended": "langgraph" in profile_names, + "header": "X-FoundryGate-Client: langgraph", + "profile": "langgraph", + "snippet": [ + "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1", + "export OPENAI_API_KEY=local", + ], + "notes": [ + "Keep LangGraph on the shared gateway path and use client tags to" + " distinguish graph traffic from generic LangChain traffic.", + "Only add dedicated policies when graph workloads need stricter" + " locality or cost boundaries.", + ], + }, } return {