Sync open source content 🐝 (from 5e3b3d4fddb56538112664c521101d6265133313)

Author: beezythebot

docs/gram/gram-functions/functions-framework.mdx

@@ -163,5 +163,135 @@ const gram = new Gram().tool({
 });
 ```
 
+## Composability
+
+Gram instances can be composed together using the `.extend()` method, allowing tool definitions to be split across multiple files and modules. This pattern is similar to Hono's grouping pattern and helps organize larger codebases.
+
+### Basic composition
+
+Split tool definitions into separate modules and combine them:
+
+```typescript filename="train.ts"
+import { Gram } from "@gram-ai/functions";
+import * as z from "zod/mini";
+
+export const trainGram = new Gram({
+  envSchema: {
+    TRAIN_API_KEY: z.string().describe("API key for the train service"),
+  },
+})
+  .tool({
+    name: "train_book",
+    description: "Books a train ticket",
+    inputSchema: { destination: z.string(), date: z.string() },
+    async execute(ctx, input) {
+      const apiKey = ctx.env.TRAIN_API_KEY;
+      // Implementation here
+      return ctx.json({ booked: true });
+    },
+  })
+  .tool({
+    name: "train_status",
+    description: "Gets the status of a train",
+    inputSchema: { trainId: z.string() },
+    async execute(ctx, input) {
+      // Implementation here
+      return ctx.json({ status: "on time" });
+    },
+  });
+```
+
+```typescript filename="flight.ts"
+import { Gram } from "@gram-ai/functions";
+import * as z from "zod/mini";
+
+export const flightGram = new Gram({
+  envSchema: {
+    FLIGHT_API_KEY: z.string().describe("API key for the flight service"),
+  },
+})
+  .tool({
+    name: "flight_book",
+    description: "Books a flight ticket",
+    inputSchema: { destination: z.string(), date: z.string() },
+    async execute(ctx, input) {
+      const apiKey = ctx.env.FLIGHT_API_KEY;
+      // Implementation here
+      return ctx.json({ booked: true });
+    },
+  })
+  .tool({
+    name: "flight_status",
+    description: "Gets the status of a flight",
+    inputSchema: { flightNumber: z.string() },
+    async execute(ctx, input) {
+      // Implementation here
+      return ctx.json({ status: "departed" });
+    },
+  });
+```
+
+```typescript filename="gram.ts"
+import { Gram } from "@gram-ai/functions";
+import { trainGram } from "./train";
+import { flightGram } from "./flight";
+
+const gram = new Gram()
+  .extend(trainGram)
+  .extend(flightGram);
+
+export default gram;
+```
+
+### Environment schema merging
+
+When composing Gram instances, environment schemas are automatically merged. Each module can define its own environment variables, and the final composed instance will validate all required variables:
+
+```typescript
+// Each module defines its own environment requirements
+const weatherGram = new Gram({
+  envSchema: {
+    WEATHER_API_KEY: z.string(),
+  },
+}).tool({
+  name: "get_weather",
+  inputSchema: { city: z.string() },
+  async execute(ctx, input) {
+    // Access environment variable from this module
+    const apiKey = ctx.env.WEATHER_API_KEY;
+    return ctx.json({ temperature: 72 });
+  },
+});
+
+const newsGram = new Gram({
+  envSchema: {
+    NEWS_API_KEY: z.string(),
+  },
+}).tool({
+  name: "get_news",
+  inputSchema: { topic: z.string() },
+  async execute(ctx, input) {
+    // Access environment variable from this module
+    const apiKey = ctx.env.NEWS_API_KEY;
+    return ctx.json({ articles: [] });
+  },
+});
+
+// Composed instance requires both environment variables
+const gram = new Gram()
+  .extend(weatherGram)
+  .extend(newsGram);
+// Both WEATHER_API_KEY and NEWS_API_KEY must be provided
+```
+
+### Benefits of composition
+
+Composing Gram instances provides several advantages:
+
+- **Modularity**: Organize related tools into separate files
+- **Reusability**: Share tool definitions across different Gram instances
+- **Maintainability**: Easier to manage large codebases with many tools
+- **Team collaboration**: Different team members can work on separate modules
+
 ## Next steps
-- [Build and deploy](/docs/gram/gram-functions/build-deploy)
+- [Build and deploy](/docs/gram/gram-functions/build-deploy)