create-agentmark 0.10.4 → 0.10.6

package/dist/index.js

@@ -71,7 +71,7 @@ sdk.initTracing({ disableBatch: true });
 `;
   const staticTracingInit = `
 // Initialize tracing - traces will be sent to local dev server
-// Make sure to run "npm run agentmark dev" in another terminal first
+// Make sure to run "npx agentmark dev" in another terminal first
 // To disable tracing, comment out sdk.initTracing() below
 const sdk = new AgentMarkSDK({
   apiKey: "",
@@ -242,7 +242,7 @@ AGENTMARK_APP_ID=your_agentmark_app_id
 `;
   return `${apiKeyName}=${apiKeyValue}
 ${cloudEnvVars}
-# Learn more: https://docs.agentmark.co/platform/getting_started/quickstart
+# Learn more: https://docs.agentmark.co/getting-started/quickstart
 `;
 };
 
@@ -487,9 +487,10 @@ var setupPackageJson = (targetPath = ".", deploymentMode = "cloud", projectInfo
     console.log("Creating package.json...");
     execSync("npm init -y", { cwd: targetPath });
   }
+  const demoScript = deploymentMode === "static" ? "npx agentmark build --out dist/agentmark && npx tsx index.ts" : "npx tsx index.ts";
   if (isExistingProject && fs2.existsSync(packageJsonPath)) {
     const scriptsToAdd = {
-      "demo": "npx tsx index.ts",
+      "demo": demoScript,
       "agentmark": "agentmark"
     };
     if (deploymentMode === "static") {
@@ -509,9 +510,12 @@ var setupPackageJson = (targetPath = ".", deploymentMode = "cloud", projectInfo
     const pkgJson = fs2.readJsonSync(packageJsonPath);
     pkgJson.name = pkgJson.name === "test" || !pkgJson.name ? "agentmark-example-app" : pkgJson.name;
     pkgJson.description = pkgJson.description || "A simple Node.js app using the Agentmark SDK";
+    if (pkgJson.type === "commonjs") {
+      delete pkgJson.type;
+    }
     const scripts = {
       ...pkgJson.scripts,
-      "demo": "npx tsx index.ts",
+      "demo": demoScript,
       "agentmark": "agentmark"
     };
     if (deploymentMode === "static") {
@@ -641,7 +645,7 @@ object_config:
       - names
 test_settings:
   dataset: party.jsonl
-  scores:
+  evals:
     - exact_match_json
   props:
     party_text: "We're having a party with Alice, Bob, and Carol."
@@ -757,12 +761,16 @@ var getClientConfigContent = (options) => {
 import { FileLoader } from "@agentmark-ai/loader-file";`;
   const loaderSetup = deploymentMode === "cloud" ? `  // ApiLoader works for both development and production
   // - Development: 'agentmark dev' sets AGENTMARK_BASE_URL to localhost
-  // - Production: Set AGENTMARK_API_KEY and AGENTMARK_APP_ID for cloud
+  // - Production: Set AGENTMARK_API_KEY and AGENTMARK_APP_ID for cloud.
+  //   AGENTMARK_BASE_URL overrides the default https://api.agentmark.co
+  //   target \u2014 managed deployments use this to point back at the gateway
+  //   that dispatched the job.
   const loader = process.env.NODE_ENV === 'development'
     ? ApiLoader.local({ baseUrl: process.env.AGENTMARK_BASE_URL || 'http://localhost:9418' })
     : ApiLoader.cloud({
         apiKey: process.env.AGENTMARK_API_KEY!,
         appId: process.env.AGENTMARK_APP_ID!,
+        baseUrl: process.env.AGENTMARK_BASE_URL,
       });` : `  const loader = process.env.NODE_ENV === 'development'
     ? ApiLoader.local({ baseUrl: process.env.AGENTMARK_BASE_URL || 'http://localhost:9418' })
     : new FileLoader('./dist/agentmark');`;
@@ -815,7 +823,7 @@ import type { ToolsInput } from '@mastra/core/agent';
 import { z } from 'zod';` : `import { tool } from 'ai';
 import type { Tool } from 'ai';
 import { z } from 'zod';`;
-  const createClientCall = isClaudeAgentSdk ? `return createAgentMarkClient<AgentMarkTypes>({ loader, modelRegistry, scores, adapterOptions, mcpServers: { 'customer-support': customerSupportTools } });` : `return createAgentMarkClient<AgentMarkTypes>({ loader, modelRegistry, tools, scores });`;
+  const createClientCall = isClaudeAgentSdk ? `return createAgentMarkClient<AgentMarkTypes>({ loader, modelRegistry, evals, adapterOptions, mcpServers: { 'customer-support': customerSupportTools } });` : `return createAgentMarkClient<AgentMarkTypes>({ loader, modelRegistry, tools, evals });`;
   const toolSchemaField = isMastra ? `parameters: z.object({ query: z.string().describe('The search query') })` : `inputSchema: z.object({ query: z.string().describe('The search query') })`;
   const toolsReturnType = isMastra ? "ToolsInput" : "Record<string, Tool>";
   const toolsSetup = isClaudeAgentSdk ? `
@@ -868,7 +876,7 @@ import path from 'node:path';
 import dotenv from 'dotenv';
 dotenv.config({ path: path.resolve(__dirname, '.env') });
 import { createAgentMarkClient, ${modelRegistry} } from "${adapterConfig.package}";
-import type { ScoreRegistry } from "@agentmark-ai/prompt-core";
+import type { EvalRegistry } from "@agentmark-ai/prompt-core";
 ${loaderImport}
 import AgentMarkTypes from './agentmark.types';
 ${providerImport}
@@ -878,26 +886,22 @@ ${adapterOptionsImport}
 ${modelRegistrySetup}
 ${toolsSetup}
 
-const scores: ScoreRegistry = {
-  exact_match_json: {
-    schema: { type: 'boolean' },
-    description: 'Whether output matches expected JSON exactly',
-    eval: ({ output, expectedOutput }) => {
-      if (!expectedOutput) {
-        return { score: 0, label: 'error', reason: 'No expected output provided', passed: false };
-      }
-      try {
-        const ok = JSON.stringify(output) === JSON.stringify(JSON.parse(expectedOutput));
-        return {
-          score: ok ? 1 : 0,
-          label: ok ? 'correct' : 'incorrect',
-          reason: ok ? 'Exact match' : 'Mismatch',
-          passed: ok
-        };
-      } catch (e) {
-        return { score: 0, label: 'error', reason: 'Failed to parse expected output as JSON', passed: false };
-      }
-    },
+const evals: EvalRegistry = {
+  exact_match_json: async ({ output, expectedOutput }) => {
+    if (!expectedOutput) {
+      return { score: 0, label: 'error', reason: 'No expected output provided', passed: false };
+    }
+    try {
+      const ok = JSON.stringify(output) === JSON.stringify(JSON.parse(expectedOutput));
+      return {
+        score: ok ? 1 : 0,
+        label: ok ? 'correct' : 'incorrect',
+        reason: ok ? 'Exact match' : 'Mismatch',
+        passed: ok
+      };
+    } catch (e) {
+      return { score: 0, label: 'error', reason: 'Failed to parse expected output as JSON', passed: false };
+    }
   },
 };
 
@@ -1140,6 +1144,19 @@ var createExampleApp = async (client, targetPath = ".", apiKey = "", adapter = "
       `${targetPath}/agentmark.client.ts`,
       getClientConfigContent({ provider: modelProvider, adapter, deploymentMode })
     );
+    const gitignoreEntries = ["node_modules/", ".env", "*.agentmark-outputs/", "dist/"];
+    if (shouldMergeFile(".gitignore", projectInfo, resolutions)) {
+      const result = appendGitignore(targetPath, gitignoreEntries);
+      if (result.added.length > 0) {
+        console.log(`\u2705 Added to .gitignore: ${result.added.join(", ")}`);
+      }
+      if (result.skipped.length > 0) {
+        console.log(`\u23ED\uFE0F  Already in .gitignore: ${result.skipped.join(", ")}`);
+      }
+    } else {
+      const gitignore = gitignoreEntries.join("\n");
+      fs4.writeFileSync(`${targetPath}/.gitignore`, gitignore);
+    }
     if (shouldMergeFile(".env", projectInfo, resolutions)) {
       const envVars = {};
       const apiKeyEnvVar = adapter === "claude-agent-sdk" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
@@ -1162,19 +1179,6 @@ var createExampleApp = async (client, targetPath = ".", apiKey = "", adapter = "
     } else {
       fs4.writeFileSync(`${targetPath}/.env`, getEnvFileContent(modelProvider, apiKey, adapter, deploymentMode));
     }
-    const gitignoreEntries = ["node_modules/", ".env", "*.agentmark-outputs/", "dist/"];
-    if (shouldMergeFile(".gitignore", projectInfo, resolutions)) {
-      const result = appendGitignore(targetPath, gitignoreEntries);
-      if (result.added.length > 0) {
-        console.log(`\u2705 Added to .gitignore: ${result.added.join(", ")}`);
-      }
-      if (result.skipped.length > 0) {
-        console.log(`\u23ED\uFE0F  Already in .gitignore: ${result.skipped.join(", ")}`);
-      }
-    } else {
-      const gitignore = gitignoreEntries.join("\n");
-      fs4.writeFileSync(`${targetPath}/.gitignore`, gitignore);
-    }
     if (!isExistingProject) {
       fs4.writeFileSync(
         `${targetPath}/index.ts`,
@@ -1223,15 +1227,23 @@ sdk.initTracing({ disableBatch: true });
 const adapter = new ${handlerClass}(client as any);
 
 export default async function handler(request: {
-  type: 'prompt-run' | 'dataset-run';
+  type: 'prompt-run' | 'dataset-run' | 'get-evals';
   data: {
-    ast: any;
+    ast?: any;
     customProps?: Record<string, unknown>;
     options?: { shouldStream?: boolean };
     experimentId?: string;
     datasetPath?: string;
   };
 }) {
+  if (request.type === 'get-evals') {
+    return {
+      type: 'evals',
+      result: JSON.stringify(Object.keys(client.getEvalRegistry())),
+      traceId: '',
+    };
+  }
+
   if (request.type === 'prompt-run') {
     return adapter.runPrompt(request.data.ast, {
       shouldStream: request.data.options?.shouldStream,
@@ -1331,20 +1343,11 @@ main().catch((err) => {
     console.log("\n" + "\u2550".repeat(70));
     console.log("Next Steps");
     console.log("\u2550".repeat(70));
-    const runCmd = packageManager?.runCmd ?? "npm run";
-    const pkgJsonPath = path2.join(targetPath, "package.json");
-    let agentmarkScriptName = "agentmark";
-    if (fs4.existsSync(pkgJsonPath)) {
-      const pkgJson = fs4.readJsonSync(pkgJsonPath);
-      if (pkgJson.scripts?.["agentmark:agentmark"]) {
-        agentmarkScriptName = "agentmark:agentmark";
-      }
-    }
     console.log("\n Get Started:");
     if (folderName !== "." && folderName !== "./" && !isExistingProject) {
       console.log(`  $ cd ${folderName}`);
     }
-    console.log(`  $ ${runCmd} ${agentmarkScriptName} dev
+    console.log(`  $ npx agentmark dev
 `);
     console.log("\u2500".repeat(70));
     console.log("Resources");
@@ -1471,7 +1474,8 @@ var setupMCPServer2 = (client, targetPath) => {
     return;
   }
 };
-var getPyprojectContent = (projectName, adapter) => {
+var getPyprojectContent = (projectName, adapter, deploymentMode) => {
+  const pyModules = deploymentMode === "cloud" ? `["agentmark_client", "main", "handler"]` : `["agentmark_client", "main"]`;
   if (adapter === "claude-agent-sdk") {
     return `[project]
 name = "${projectName}"
@@ -1479,9 +1483,9 @@ version = "0.1.0"
 description = "An AgentMark application using Claude Agent SDK"
 requires-python = ">=3.12"
 dependencies = [
-    "agentmark-sdk>=0.1.0",
-    "agentmark-claude-agent-sdk-v0>=0.1.0",
-    "agentmark-prompt-core>=0.1.0",
+    "agentmark-sdk>=0.2.0",
+    "agentmark-claude-agent-sdk-v0>=0.1.4",
+    "agentmark-prompt-core>=0.1.2",
     "python-dotenv>=1.0.0",
     "claude-agent-sdk>=0.1.0",
 ]
@@ -1494,8 +1498,11 @@ dev = [
 ]
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ${pyModules}
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
@@ -1510,11 +1517,11 @@ version = "0.1.0"
 description = "An AgentMark application using Pydantic AI"
 requires-python = ">=3.12"
 dependencies = [
-    "agentmark-sdk>=0.1.0",
-    "agentmark-pydantic-ai-v0>=0.1.0",
-    "agentmark-prompt-core>=0.1.0",
+    "agentmark-sdk>=0.2.0",
+    "agentmark-pydantic-ai-v0>=0.1.4",
+    "agentmark-prompt-core>=0.1.2",
     "python-dotenv>=1.0.0",
-    "pydantic-ai[openai]>=0.1.0",
+    "pydantic-ai-slim[openai]>=1.0,<2.0",
 ]
 
 [project.optional-dependencies]
@@ -1523,12 +1530,13 @@ dev = [
     "pytest-asyncio>=0.21",
     "mypy>=1.0",
 ]
-anthropic = ["pydantic-ai[anthropic]"]
-gemini = ["pydantic-ai[gemini]"]
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ${pyModules}
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
@@ -1538,8 +1546,8 @@ strict = true
 `;
 };
 var getHandlerPyContent = (adapter) => {
-  const webhookClass = adapter === "claude-agent-sdk" ? "ClaudeAgentSDKWebhookHandler" : "PydanticAIWebhookHandler";
-  const webhookImport = adapter === "claude-agent-sdk" ? "from agentmark_claude_agent_sdk import ClaudeAgentSDKWebhookHandler" : "from agentmark_pydantic_ai_v0 import PydanticAIWebhookHandler";
+  const webhookClass = adapter === "claude-agent-sdk" ? "ClaudeAgentWebhookHandler" : "PydanticAIWebhookHandler";
+  const webhookImport = adapter === "claude-agent-sdk" ? "from agentmark_claude_agent_sdk_v0 import ClaudeAgentWebhookHandler" : "from agentmark_pydantic_ai_v0 import PydanticAIWebhookHandler";
   return `"""AgentMark handler for managed cloud deployments.
 
 This file is used by the AgentMark platform to execute prompts and experiments
@@ -1564,10 +1572,18 @@ adapter = ${webhookClass}(client)
 
 
 async def handler(request: dict):
-    """Handle prompt-run and dataset-run requests from the platform."""
+    """Handle prompt-run, dataset-run, and get-evals requests from the platform."""
     req_type = request.get("type")
     data = request.get("data", {})
 
+    if req_type == "get-evals":
+        import json
+        return {
+            "type": "evals",
+            "result": json.dumps(list(client.get_eval_registry().keys())),
+            "traceId": "",
+        }
+
     if req_type == "prompt-run":
         return await adapter.run_prompt(data["ast"], {
             "shouldStream": data.get("options", {}).get("shouldStream", True),
@@ -1604,7 +1620,8 @@ from pathlib import Path
 from dotenv import load_dotenv
 
 ${loaderImport}
-from agentmark_claude_agent_sdk import (
+from agentmark.prompt_core import EvalRegistry
+from agentmark_claude_agent_sdk_v0 import (
     create_claude_agent_client,
     ClaudeAgentModelRegistry,
 )
@@ -1620,9 +1637,7 @@ model_registry.register_providers({
 })
 
 
-# Eval registry \u2014 define evaluation functions for experiments
-# TODO: Update to use scores (ScoreRegistry) once the Python SDK supports it.
-# The TypeScript SDK already uses scores with schema definitions.
+# Evaluation functions \u2014 used by experiments to score model outputs
 def exact_match_json(params):
     """Check if output matches expected output exactly."""
     output = params.get("output")
@@ -1642,7 +1657,7 @@ def exact_match_json(params):
     except (json.JSONDecodeError, TypeError):
         return {"score": 0, "label": "error", "reason": "Failed to parse JSON", "passed": False}
 
-eval_registry = {
+evals: EvalRegistry = {
     "exact_match_json": exact_match_json,
 }
 
@@ -1652,7 +1667,7 @@ ${loaderSetup}
 # Claude Agent SDK handles tools natively through the SDK
 client = create_claude_agent_client(
     model_registry=model_registry,
-    eval_registry=eval_registry,
+    evals=evals,
     loader=loader,
 )
 
@@ -1671,6 +1686,7 @@ from pathlib import Path
 from dotenv import load_dotenv
 
 ${loaderImport}
+from agentmark.prompt_core import EvalRegistry
 from agentmark_pydantic_ai_v0 import (
     create_pydantic_ai_client,
     PydanticAIModelRegistry,
@@ -1695,9 +1711,7 @@ model_registry.register_providers({
 tools = []
 
 
-# Eval registry \u2014 define evaluation functions for experiments
-# TODO: Update to use scores (ScoreRegistry) once the Python SDK supports it.
-# The TypeScript SDK already uses scores with schema definitions.
+# Evaluation functions \u2014 used by experiments to score model outputs
 def exact_match_json(params):
     """Check if output matches expected output exactly."""
     output = params.get("output")
@@ -1717,7 +1731,7 @@ def exact_match_json(params):
     except (json.JSONDecodeError, TypeError):
         return {"score": 0, "label": "error", "reason": "Failed to parse JSON", "passed": False}
 
-eval_registry = {
+evals: EvalRegistry = {
     "exact_match_json": exact_match_json,
 }
 
@@ -1727,7 +1741,7 @@ ${loaderSetup}
 client = create_pydantic_ai_client(
     model_registry=model_registry,
     tools=tools,
-    eval_registry=eval_registry,
+    evals=evals,
     loader=loader,
 )
 
@@ -1747,7 +1761,7 @@ sdk.init_tracing(disable_batch=True)
 `;
   const staticTracingInit = `
 # Initialize tracing - traces will be sent to local dev server
-# Make sure to run "npm run agentmark dev" in another terminal first
+# Make sure to run "npx agentmark dev" in another terminal first
 # To disable tracing, comment out sdk.init_tracing() below
 sdk = AgentMarkSDK(
     api_key="",
@@ -1760,49 +1774,40 @@ sdk.init_tracing(disable_batch=True)
   if (adapter === "claude-agent-sdk") {
     return `"""Example usage of AgentMark with Claude Agent SDK.
 
-Run with: python main.py
+Run with:
+    npx agentmark build   # compile party-planner.prompt.mdx -> dist/agentmark/*.json
+    python main.py
 """
 
 import asyncio
-import json
 import os
-from pathlib import Path
 
 from agentmark_sdk import AgentMarkSDK
-from agentmark_claude_agent_sdk import run_text_prompt
+from agentmark_claude_agent_sdk_v0 import traced_query
 from agentmark_client import client
 ${tracingInit}
 
 async def main():
-    """Run the party planner prompt."""
-    # Load the prompt AST (in production, use the API loader)
-    prompt_path = Path("agentmark/party-planner.prompt.mdx.json")
-
-    if not prompt_path.exists():
-        print("Prompt file not found. Run 'agentmark build' first.")
+    """Run the party planner prompt (object_config: extracts attendee names)."""
+    # \`agentmark build\` writes pre-compiled prompts to dist/agentmark/.
+    # The FileLoader reads them by name \u2014 extension is optional.
+    try:
+        prompt = await client.load_object_prompt("party-planner.prompt.mdx")
+    except FileNotFoundError:
+        print("Pre-built prompt not found. Run 'npx agentmark build' first.")
         return
 
-    with open(prompt_path) as f:
-        ast = json.load(f)
-
-    # Load and format the prompt
-    prompt = await client.load_text_prompt(ast)
-    params = await prompt.format(props={
-        "numberOfGuests": 10,
-        "theme": "80s disco",
-        "dietaryRestrictions": ["vegetarian", "gluten-free"],
+    adapted = await prompt.format(props={
+        "party_text": "We're having a party with Alice, Bob, and Carol.",
     })
 
-    # Execute the prompt
+    # Execute via Claude Agent SDK (streamed) with automatic OTEL tracing.
+    # adapted.query.options.output_format is set to the object schema.
     print("Running party planner prompt...")
-    result = await run_text_prompt(params)
-
-    print("\\n" + "=" * 50)
-    print("Party Plan:")
     print("=" * 50)
-    print(result.output)
-    print("\\n" + "-" * 50)
-    print(f"Tokens used: {result.usage}")
+    async for message in traced_query(adapted):
+        print(message)
+    print("=" * 50)
 
 
 if __name__ == "__main__":
@@ -1811,47 +1816,44 @@ if __name__ == "__main__":
   }
   return `"""Example usage of AgentMark with Pydantic AI.
 
-Run with: python main.py
+Run with:
+    npx agentmark build   # compile party-planner.prompt.mdx -> dist/agentmark/*.json
+    python main.py
 """
+# To use a different LLM provider, install: pip install "pydantic-ai-slim[anthropic]" (or [google], [bedrock], etc.)
 
 import asyncio
-import json
 import os
-from pathlib import Path
 
 from agentmark_sdk import AgentMarkSDK
-from agentmark_pydantic_ai_v0 import run_text_prompt
+from agentmark_pydantic_ai_v0 import run_object_prompt
 from agentmark_client import client
 ${tracingInit}
 
 async def main():
-    """Run the party planner prompt."""
-    # Load the prompt AST (in production, use the API loader)
-    prompt_path = Path("agentmark/party-planner.prompt.mdx.json")
-
-    if not prompt_path.exists():
-        print("Prompt file not found. Run 'agentmark build' first.")
+    """Run the party planner prompt (object_config: extracts attendee names)."""
+    # \`agentmark build\` writes pre-compiled prompts to dist/agentmark/.
+    # The FileLoader reads them by name \u2014 extension is optional, and it
+    # extracts the inner AST from the { ast, metadata } wrapper for you.
+    try:
+        prompt = await client.load_object_prompt("party-planner.prompt.mdx")
+    except FileNotFoundError:
+        print("Pre-built prompt not found. Run 'npx agentmark build' first.")
         return
 
-    with open(prompt_path) as f:
-        ast = json.load(f)
-
-    # Load and format the prompt
-    prompt = await client.load_text_prompt(ast)
     params = await prompt.format(props={
-        "numberOfGuests": 10,
-        "theme": "80s disco",
-        "dietaryRestrictions": ["vegetarian", "gluten-free"],
+        "party_text": "We're having a party with Alice, Bob, and Carol.",
     })
 
     # Execute the prompt
     print("Running party planner prompt...")
-    result = await run_text_prompt(params)
+    result = await run_object_prompt(params)
 
     print("\\n" + "=" * 50)
-    print("Party Plan:")
+    print("Extracted attendees:")
     print("=" * 50)
-    print(result.output)
+    # result.output is a Pydantic model instance with the schema's fields
+    print(result.output.names)
     print("\\n" + "-" * 50)
     print(f"Tokens used: {result.usage.total_tokens}")
 
@@ -1861,10 +1863,10 @@ if __name__ == "__main__":
 `;
 };
 var getDevServerContent = (adapter) => {
-  const adapterPackage = adapter === "claude-agent-sdk" ? "agentmark_claude_agent_sdk" : "agentmark_pydantic_ai_v0";
+  const adapterPackage = adapter === "claude-agent-sdk" ? "agentmark_claude_agent_sdk_v0" : "agentmark_pydantic_ai_v0";
   return `"""Auto-generated webhook server for AgentMark development.
 
-This server is started by 'npm run agentmark dev' (agentmark dev) and handles
+This server is started by 'npx agentmark dev' (agentmark dev) and handles
 prompt execution requests from the CLI.
 """
 
@@ -1904,6 +1906,62 @@ OPENAI_API_KEY=${apiKey}
 # GOOGLE_API_KEY=your-key-here
 `;
 };
+var getReadmeContent = (projectName, adapter) => {
+  const adapterName = adapter === "claude-agent-sdk" ? "Claude Agent SDK" : "Pydantic AI";
+  const apiKeyEnvVar = adapter === "claude-agent-sdk" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
+  const directInstallCmd = adapter === "claude-agent-sdk" ? "pip install agentmark-sdk agentmark-claude-agent-sdk-v0 agentmark-prompt-core python-dotenv claude-agent-sdk" : 'pip install agentmark-sdk agentmark-pydantic-ai-v0 agentmark-prompt-core python-dotenv "pydantic-ai-slim[openai]>=1.0,<2.0"';
+  return `# ${projectName}
+
+An AgentMark application using ${adapterName}.
+
+## Prerequisites
+
+- Python 3.12+
+- **pip 26.1+** (older pip versions fail to resolve the dependency graph \u2014 see "Why pip 26.1?" below)
+
+## Setup
+
+\`\`\`bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate
+
+# 2. Upgrade pip (REQUIRED \u2014 older pip cannot resolve pydantic-ai's transitive graph)
+python -m pip install --upgrade "pip>=26.1"
+
+# 3. Install dependencies
+${directInstallCmd}
+
+# 4. Set your API key
+echo "${apiKeyEnvVar}=your-key-here" > .env
+\`\`\`
+
+## Run
+
+\`\`\`bash
+# Start the AgentMark dev server (in another terminal)
+npx agentmark dev
+
+# Run the example prompt
+python main.py
+\`\`\`
+
+Then open [http://localhost:9418](http://localhost:9418) to view your traces.
+
+## Why pip 26.1?
+
+The \`pydantic-ai-slim\` package transitively depends on \`mcp\`, \`fastmcp\`, and
+\`logfire\`, which together produce a deep dependency graph. Pip versions before
+26.1 fall into long backtracking loops and abort with \`resolution-too-deep\`.
+Pip 26.1's resolver handles this graph efficiently. If you skip the upgrade and
+hit the error, run \`python -m pip install --upgrade pip\` and retry.
+
+## Resources
+
+- [Documentation](https://docs.agentmark.co)
+- [GitHub](https://github.com/agentmark-ai/agentmark)
+`;
+};
 var getGitignoreContent = () => {
   return `# Python
 __pycache__/
@@ -1950,7 +2008,7 @@ var createPythonApp = async (client, targetPath = ".", apiKey = "", deploymentMo
     console.log(`Example prompts and datasets created in ${folderName}/agentmark/`);
     if (!isExistingProject) {
       const projectName = path3.basename(targetPath).replace(/[^a-zA-Z0-9_-]/g, "-");
-      fs5.writeFileSync(`${targetPath}/pyproject.toml`, getPyprojectContent(projectName, adapter));
+      fs5.writeFileSync(`${targetPath}/pyproject.toml`, getPyprojectContent(projectName, adapter, deploymentMode));
     } else {
       console.log("\u23ED\uFE0F  Skipped pyproject.toml (existing project)");
     }
@@ -2017,6 +2075,14 @@ var createPythonApp = async (client, targetPath = ".", apiKey = "", deploymentMo
     } else {
       fs5.writeFileSync(`${targetPath}/.gitignore`, getGitignoreContent());
     }
+    if (!isExistingProject) {
+      const readmePath = path3.join(targetPath, "README.md");
+      if (!fs5.existsSync(readmePath)) {
+        const projectName = path3.basename(targetPath).replace(/[^a-zA-Z0-9_-]/g, "-");
+        fs5.writeFileSync(readmePath, getReadmeContent(projectName, adapter));
+        console.log(`\u2705 Created README.md`);
+      }
+    }
     const agentmarkInternalDir = path3.join(targetPath, ".agentmark");
     fs5.ensureDirSync(agentmarkInternalDir);
     fs5.writeFileSync(path3.join(agentmarkInternalDir, "dev_server.py"), getDevServerContent(adapter));
@@ -2049,16 +2115,20 @@ var createPythonApp = async (client, targetPath = ".", apiKey = "", deploymentMo
     if (folderName !== "." && folderName !== "./" && !isExistingProject) {
       console.log(`  $ cd ${folderName}`);
     }
+    const pipInstallCmd = adapter === "claude-agent-sdk" ? "  $ pip install agentmark-sdk agentmark-claude-agent-sdk-v0 agentmark-prompt-core python-dotenv claude-agent-sdk" : '  $ pip install agentmark-sdk agentmark-pydantic-ai-v0 agentmark-prompt-core python-dotenv "pydantic-ai-slim[openai]>=1.0,<2.0"';
+    const pipUpgradeCmd = '  $ python -m pip install --upgrade "pip>=26.1"';
     if (pythonVenv) {
       const activateCmd = process.platform === "win32" ? `${pythonVenv.name}\\Scripts\\activate` : `source ${pythonVenv.name}/bin/activate`;
       console.log(`  $ ${activateCmd}`);
-      console.log('  $ pip install agentmark-pydantic-ai-v0 agentmark-prompt-core python-dotenv "pydantic-ai[openai]"');
+      console.log(pipUpgradeCmd);
+      console.log(pipInstallCmd);
     } else {
       console.log("  $ python -m venv .venv");
       console.log("  $ source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate");
-      console.log('  $ pip install -e ".[dev]"');
+      console.log(pipUpgradeCmd);
+      console.log(pipInstallCmd);
     }
-    console.log("  $ npm run agentmark dev\n");
+    console.log("  $ npx agentmark dev\n");
     console.log("\u2500".repeat(70));
     console.log("Resources");
     console.log("\u2500".repeat(70));