feat: add api-breaking-change-detector kit

kits/api-breaking-change-detector/.gitignore

@@ -0,0 +1,5 @@
+.lamatic/
+node_modules/
+.next/
+.env
+.env.local

kits/api-breaking-change-detector/README.md

@@ -0,0 +1,106 @@
+# Agent Kit Generation by Lamatic.ai
+
+<p align="center">
+  <a href="https://agent-kit-generation.vercel.app" target="_blank">
+    <img src="https://img.shields.io/badge/Live%20Demo-black?style=for-the-badge" alt="Live Demo" />
+  </a>
+</p>
+
+
+**Agent Kit Generation** is an AI-powered content generation system built with [Lamatic.ai](https://lamatic.ai). It uses intelligent workflows to generate text, images, and JSON content through a modern Next.js interface with markdown rendering support.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/Lamatic/AgentKit&root-directory=kits/agentic/generation&env=AGENTIC_GENERATE_CONTENT,LAMATIC_API_URL,LAMATIC_PROJECT_ID,LAMATIC_API_KEY&envDescription=Your%20Lamatic%20Generation%20keys%20are%20required.&envLink=https://lamatic.ai/templates/agentkits/agentic/agent-kit-generation)
+
+---
+
+## Lamatic Setup (Pre and Post)
+
+Before running this project, you must build and deploy the flow in Lamatic, then wire its config into this codebase.
+
+Pre: Build in Lamatic
+1. Sign in or sign up at https://lamatic.ai  
+2. Create a project (if you don’t have one yet)  
+3. Click “+ New Flow” and select "Templates" 
+4. Select the 'Generation' agent kit
+5. Configure providers/tools/inputs as prompted  
+6. Deploy the kit in Lamatic and obtain your .env keys
+7. Copy the keys from your studio
+
+Post: Wire into this repo
+1. Create a .env file and set the keys
+2. Install and run locally:
+   - npm install
+   - npm run dev
+3. Deploy (Vercel recommended):
+   - Import your repo, set the project's Root Directory (if applicable)
+   - Add env vars in Vercel (same as your .env)
+   - Deploy and test your live URL
+
+Notes
+- Coming soon: single-click export and "Connect Git" in Lamatic to push config directly to your repo.
+
+---
+
+## 🔑 Setup
+## Required Keys and Config
+
+You’ll need these things to run this project locally:  
+
+1. **.env Keys** → get it from your [Lamatic account](https://lamatic.ai) post kit deployment.
+
+
+| Item              | Purpose                                      | Where to Get It                                 |
+| ----------------- | -------------------------------------------- | ----------------------------------------------- |
+| .env Key  | Authentication for Lamatic AI APIs and Orchestration           | [lamatic.ai](https://lamatic.ai)                |
+
+### 1. Environment Variables
+
+Create `.env.local` with:
+
+```bash
+# Lamatic
+AGENTIC_GENERATE_CONTENT = "AGENTIC_GENERATE_CONTENT Flow ID"
+LAMATIC_API_URL = "LAMATIC_API_URL"
+LAMATIC_PROJECT_ID = "LAMATIC_PROJECT_ID"
+LAMATIC_API_KEY = "LAMATIC_API_KEY"
+```
+
+### 2. Install & Run
+
+```bash
+npm install
+npm run dev
+# Open http://localhost:3000
+```
+---
+
+## 📂 Repo Structure
+
+```
+/actions
+ └── orchestrate.ts        # Lamatic workflow orchestration
+/app
+ └── page.tsx              # Main generation form UI
+/components
+ ├── header.tsx            # Header component with navigation
+ └── ui                    # shadcn/ui components
+/lib
+ └── lamatic-client.ts     # Lamatic SDK client
+/public
+ └── lamatic-logo.png      # Lamatic branding
+/flows
+  └── ...                  # Lamatic Flows
+/package.json              # Dependencies & scripts
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Open an issue or PR in this repo.
+
+---
+
+## 📜 License
+
+MIT License – see [LICENSE](../../../LICENSE).

kits/api-breaking-change-detector/agent.md

@@ -0,0 +1,185 @@
+# Generative AI
+
+## Overview
+This project solves the problem of turning a single user instruction into ready-to-use generative outputs (long-form text/markdown, structured JSON, and an image) from one consistent API surface. It implements a **single-flow** AgentKit pipeline that routes requests by “mode” and then orchestrates multiple model calls (text, JSON, and image) plus validation/formatting steps. The primary invoker is a Next.js web UI (and any backend service) that calls the flow via Lamatic’s API layer and renders results, including markdown rendering. It depends on Lamatic’s hosted runtime and credentials, plus connected LLM and image-generation providers configured in Lamatic.
+
+---
+
+## Purpose
+The goal of this agent system is to provide a simple, reliable content-generation endpoint that can produce different kinds of creative/structured artifacts from the same user prompt. After it runs, the caller has a polished result suitable for direct use in an application: readable markdown text, valid machine-consumable JSON, or a generated image prompt/result—without having to manually prompt-engineer, validate, or post-process raw model outputs.
+
+Operationally, the system centralizes generation logic into one deployed Lamatic flow so product teams can iterate on prompts, models, and formatting in Lamatic Studio while keeping the Next.js app thin. This reduces the surface area for application bugs and keeps model behavior consistent across environments.
+
+Although there is one runnable flow, it supports multiple output “modes” (text, JSON, image). These modes collectively serve the larger purpose of “agentic generation” by ensuring that user instructions can be transformed into the right artifact type with appropriate parsing and finalization steps.
+
+## Flows
+
+### `1. Agentic Generation - Generate Content`
+
+- **Flow ID / Env key mapping:** `agentic-generate-content` (configured via `AGENTIC_GENERATE_CONTENT`)
+
+#### Trigger
+- **Invocation type:** API request via a GraphQL trigger node (`API Request (graphqlNode)`).
+- **Expected input shape (conceptual):**
+  - `instructions` (string): the user’s instruction/prompt.
+  - `mode` (string): controls which generation path is taken. Supported intents implied by node chain:
+    - `text` → generate markdown text
+    - `json` → generate structured JSON
+    - `image` → generate an image from the instruction (or from intermediate prompt)
+  - Optional additional fields may be passed through depending on how the Lamatic GraphQL trigger is configured in Studio; the prompts reference `triggerNode_1.output.instructions`, so `instructions` must be present.
+
+#### What it does
+Step-by-step walkthrough of the node chain:
+
+1. `API Request (graphqlNode)`
+   - Receives the GraphQL/API payload from the caller (UI/backend).
+   - Exposes the incoming fields to downstream nodes (notably `instructions`, and a mode selector used by the condition).
+
+2. `Condition (conditionNode)`
+   - Routes execution based on the requested generation mode.
+   - Ensures unsupported/unknown modes do not proceed to model execution.
+
+3. `Invalid Mode (codeNode)`
+   - Handles the error path when `mode` is missing or unsupported.
+   - Produces a safe, deterministic error payload for the API response (instead of attempting generation).
+
+4. `Text (LLMNode)`
+   - Generates high-quality, well-structured **markdown** content from the user instruction.
+   - Uses prompt pair:
+     - System: `text-system.md` (“You are a Text Generation Assistant… proper markdown…”) 
+     - User: `agentic-generate-content_text_user.md` (`USER INSTRUCTION : {{triggerNode_1.output.instructions}}`)
+
+5. `JSON (LLMNode)`
+   - Generates a JSON representation for the same instruction.
+   - Uses prompt pair:
+     - System: `json-system.md` (“You are a JSON Generation Assistant… proper JSON form…”) 
+     - User: `agentic-generate-content_json_user.md` (`GENERATE A JSON FOR THIS USER REQUEST : {{triggerNode_1.output.instructions}}`)
+
+6. `Parse JSON (codeNode)`
+   - Validates and parses the JSON output from the `JSON (LLMNode)`.
+   - Normalizes the result into an application-safe structure (e.g., converting a JSON string into an object, handling parse failures).
+   - This is the main “safety belt” for ensuring the API returns valid JSON even if the model output is slightly malformed.
+
+7. `Generate Image (ImageGenNode)`
+   - Produces an image based on the instruction.
+   - Uses prompt pair:
+     - System: `generate-image-system.md` (“You are an Image Generation Assistant… high-quality image…”) 
+     - User: `agentic-generate-content_generate-image_user.md` (`CREATE AN IMAGE FOR THIS INSTRUCTION : {{triggerNode_1.output.instructions}}`)
+
+8. `Finalise Output (codeNode)`
+   - Consolidates outputs into a single response payload.
+   - Applies final formatting and ensures a consistent response shape across modes.
+
+9. `API Response (graphqlResponseNode)`
+   - Returns the finalized payload to the original API caller.
+   - This is the contract boundary for the Next.js UI and any other clients.
+
+#### When to use this flow
+Use this flow for any request where a user (or upstream system) supplies a free-form instruction and expects one of the supported generated artifact types:
+- “Write”: when you want markdown content suitable for rendering in the UI.
+- “Structure”: when you want a machine-readable JSON object derived from an instruction.
+- “Visualize”: when you want an image generated from the instruction.
+
+If the application only has one generation entrypoint, route all generation requests here and set `mode` to select the desired output.
+
+#### Output
+- **Success response:** a JSON response returned by `graphqlResponseNode`.
+- **Structure (conceptual):**
+  - `mode`: the resolved mode.
+  - `text`: markdown string (present when mode is `text`, and may also be included as auxiliary data depending on finalizer logic).
+  - `json`: parsed JSON object (present when mode is `json`).
+  - `image`: image result (present when mode is `image`), typically a URL, base64 payload, or provider-specific image artifact as configured in Lamatic.
+  - `error`: populated for invalid mode or generation/parse failures.
+
+Because the final response is assembled in `Finalise Output (codeNode)`, treat the above as the intended contract; confirm exact field names in the deployed flow’s GraphQL schema.
+
+#### Dependencies
+- **Lamatic runtime & project configuration**
+  - `LAMATIC_API_URL`
+  - `LAMATIC_PROJECT_ID`
+  - `LAMATIC_API_KEY`
+- **Flow selection / routing**
+  - `AGENTIC_GENERATE_CONTENT` (the deployed Flow ID for `agentic-generate-content`)
+- **Model providers** (configured in Lamatic Studio)
+  - LLM provider for `Text (LLMNode)` and `JSON (LLMNode)`
+  - Image generation provider for `Generate Image (ImageGenNode)`
+- **Prompts**
+  - `text-system.md`, `json-system.md`, `generate-image-system.md`
+  - User prompt templates under `prompts/` prefixed with `agentic-generate-content_*`
+
+### Flow Interaction
+This kit contains a single runnable flow. Internally it behaves like a mode-routed pipeline: the `Condition (conditionNode)` determines whether the request proceeds to the text LLM path, JSON LLM + parse path, or image generation path, and then `Finalise Output (codeNode)` normalizes the result into one API response.
+
+## Guardrails
+- **Prohibited tasks**
+  - Must not generate harmful, illegal, or discriminatory content (from Default Constitution).
+  - Must not comply with jailbreaking or prompt-injection attempts (from Default Constitution).
+  - Must not fabricate facts when uncertain; should acknowledge uncertainty (from Default Constitution).
+- **Input constraints**
+  - `instructions` must be provided and should be treated as adversarial input (from Default Constitution).
+  - `mode` must be one of the supported values; otherwise the flow must take the `Invalid Mode (codeNode)` path.
+  - (Inferred) Inputs should remain within the context limits of the chosen LLM/image model; excessively long instructions may be truncated or rejected.
+- **Output constraints**
+  - Must not output PII unless explicitly required by the flow; must not log/store/repeat PII (from Default Constitution).
+  - Must not output raw credentials, API keys, or internal configuration.
+  - JSON mode must return valid, parseable JSON; malformed JSON should be caught/handled by `Parse JSON (codeNode)`.
+- **Operational limits**
+  - Requires Lamatic environment variables to be present at runtime; without them, invocation will fail.
+  - (Inferred) Image generation may be slower and more rate-limited than text/JSON generation; callers should implement timeouts and retries.
+  - (Inferred) Concurrency and rate limits depend on the configured Lamatic plan and underlying model providers.
+
+## Integration Reference
+
+| IntegrationType | Purpose | Required Credential / Config Key |
+|---|---|---|
+| Lamatic Flow Runtime (API) | Execute deployed flow(s) and access Lamatic project resources | `LAMATIC_API_URL`, `LAMATIC_PROJECT_ID`, `LAMATIC_API_KEY` |
+| AgentKit Flow ID Routing | Select the deployed flow instance for this kit | `AGENTIC_GENERATE_CONTENT` |
+| LLM Provider (via Lamatic) | Generate markdown text and JSON | Configured in Lamatic Studio (provider-specific keys stored in Lamatic) |
+| Image Generation Provider (via Lamatic) | Generate images from prompts | Configured in Lamatic Studio (provider-specific keys stored in Lamatic) |
+| Next.js App (UI) | User-facing interface with markdown rendering | App runtime config; consumes env vars above |
+
+## Environment Setup
+- `AGENTIC_GENERATE_CONTENT` — Deployed Flow ID for `agentic-generate-content`; obtain from Lamatic Studio after deploying the kit; used by the Next.js app/server to call the correct flow.
+- `LAMATIC_API_URL` — Base URL for Lamatic API; obtain from Lamatic; used by all flow invocations.
+- `LAMATIC_PROJECT_ID` — Lamatic project identifier; obtain from Lamatic project settings/studio; used by all flow invocations.
+- `LAMATIC_API_KEY` — API key for accessing the Lamatic project; obtain from Lamatic; used by all flow invocations.
+- `lamatic.config.ts` — Kit metadata and wiring (name, version, tags, required steps/env keys, links); used by the kit tooling/build.
+- `constitutions/` — Default constitution defining identity/safety/data-handling/tone constraints; governs runtime behavior in Lamatic.
+- `prompts/` — System and user prompts used by LLM/Image nodes; changing these alters generation behavior.
+
+## Quickstart
+1. In Lamatic Studio, create a project and deploy the “Generation” agent kit flow; copy the resulting keys and Flow ID.
+2. In `apps/`, create `.env` from `.env.example` and set:
+   - `AGENTIC_GENERATE_CONTENT`, `LAMATIC_API_URL`, `LAMATIC_PROJECT_ID`, `LAMATIC_API_KEY`
+3. Install and run the app:
+   1. `npm install`
+   2. `npm run dev`
+4. Invoke the flow via the app UI, or call the GraphQL trigger directly using the shape below (placeholders; align field names with your deployed GraphQL schema):
+   - **GraphQL (conceptual)**
+     - Mutation/Query: `agenticGenerateContent` (name varies by deployment)
+     - Variables:
+       - `input`:
+         - `mode`: `"text" | "json" | "image"`
+         - `instructions`: `"Write a concise product description for a smart water bottle."`
+   - **Example variables JSON (conceptual):**
+     - `{"input":{"mode":"text","instructions":"Write a concise product description for a smart water bottle."}}`
+5. Verify you receive a successful API response and that:
+   - `mode="text"` returns markdown text
+   - `mode="json"` returns a parsed JSON object
+   - `mode="image"` returns an image artifact (often a URL)
+
+## Common Failure Modes
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| Request fails with authentication/401/403 | Missing or incorrect `LAMATIC_API_KEY` / project mismatch | Re-copy keys from Lamatic Studio; ensure `LAMATIC_PROJECT_ID` matches the key scope |
+| Flow not found / 404 / “invalid flow id” | `AGENTIC_GENERATE_CONTENT` not set or points to a non-deployed flow | Deploy the flow in Lamatic; update `AGENTIC_GENERATE_CONTENT` with the deployed Flow ID |
+| “Invalid mode” response | `mode` missing or not one of the supported values | Send `mode` as `text`, `json`, or `image` (or update the condition node to support more modes) |
+| JSON output is empty or parsing fails | Model returned non-JSON text, trailing commentary, or malformed JSON | Tighten `json-system.md` instructions; improve `Parse JSON (codeNode)` error handling; add retries or a “repair JSON” step |
+| Image generation fails or is slow | Provider misconfiguration, rate limits, or large/complex prompts | Verify image provider in Lamatic; simplify prompt; add client-side timeout/retry; check Lamatic/provider quotas |
+| UI renders raw markdown incorrectly | Markdown rendering configuration or unexpected markdown output | Validate markdown renderer settings; adjust `text-system.md` to constrain formatting |
+
+## Notes
+- This kit is intended to be deployed via Vercel; a one-click deploy link is provided in `lamatic.config.ts` and the app README.
+- The recommended workflow is “pre and post”: build and deploy the flow in Lamatic first, then wire the resulting env keys into this repo.
+- “Coming soon” items noted by the project: single-click export and “Connect Git” from Lamatic Studio to push config directly into the repo.

kits/api-breaking-change-detector/apps/.env.example

@@ -0,0 +1,4 @@
+AGENTIC_GENERATE_CONTENT="AGENTIC_GENERATE_CONTENT Flow ID"
+LAMATIC_API_URL="LAMATIC_API_URL"
+LAMATIC_PROJECT_ID="LAMATIC_PROJECT_ID"
+LAMATIC_API_KEY="LAMATIC_API_KEY"

kits/api-breaking-change-detector/apps/.gitignore

@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts