@ryanfw/prompt-orchestration-pipeline 0.5.0 → 0.7.0

package/src/pages/Code.jsx

@@ -0,0 +1,351 @@
+import React, { useState, useEffect } from "react";
+import { Box, Heading, Table, Code, Text } from "@radix-ui/themes";
+import Layout from "../components/Layout.jsx";
+import PageSubheader from "../components/PageSubheader.jsx";
+import { Button } from "../components/ui/button.jsx";
+
+const ioFunctions = [
+  {
+    name: "writeArtifact",
+    description: "Write an artifact file",
+    params:
+      'name: string, content: string, options?: { mode?: "replace"|"append"=replace }',
+    returns: "Promise<string>",
+    notes: "Writes to {workDir}/files/artifacts; updates tasks-status.json",
+  },
+  {
+    name: "writeLog",
+    description: "Write a log file",
+    params:
+      'name: string, content: string, options?: { mode?: "append"|"replace"=append }',
+    returns: "Promise<string>",
+    notes:
+      "Writes to {workDir}/files/logs; default append; updates tasks-status.json",
+  },
+  {
+    name: "writeTmp",
+    description: "Write a temporary file",
+    params:
+      'name: string, content: string, options?: { mode?: "replace"|"append"=replace }',
+    returns: "Promise<string>",
+    notes: "Writes to {workDir}/files/tmp; updates tasks-status.json",
+  },
+  {
+    name: "readArtifact",
+    description: "Read an artifact file",
+    params: "name: string",
+    returns: "Promise<string>",
+    notes: "Reads from {workDir}/files/artifacts",
+  },
+  {
+    name: "readLog",
+    description: "Read a log file",
+    params: "name: string",
+    returns: "Promise<string>",
+    notes: "Reads from {workDir}/files/logs",
+  },
+  {
+    name: "readTmp",
+    description: "Read a temporary file",
+    params: "name: string",
+    returns: "Promise<string>",
+    notes: "Reads from {workDir}/files/tmp",
+  },
+  {
+    name: "getTaskDir",
+    description: "Get the task directory path",
+    params: "",
+    returns: "string",
+    notes: "Returns {workDir}/tasks/{taskName}",
+  },
+  {
+    name: "getCurrentStage",
+    description: "Get the current stage name",
+    params: "",
+    returns: "string",
+    notes: "Calls injected getStage()",
+  },
+];
+
+const sampleSeed = {
+  name: "some-name",
+  pipeline: "content-generation",
+  data: {
+    type: "some-type",
+    contentType: "blog-post",
+    targetAudience: "software-developers",
+    tone: "professional-yet-accessible",
+    length: "1500-2000 words",
+    outputFormat: "blog-post",
+  },
+};
+
+export default function CodePage() {
+  const [llmFunctions, setLlmFunctions] = useState(null);
+
+  useEffect(() => {
+    fetch("/api/llm/functions")
+      .then((res) => res.json())
+      .then(setLlmFunctions)
+      .catch(console.error);
+  }, []);
+
+  const breadcrumbs = [{ label: "Home", href: "/" }, { label: "Code" }];
+
+  const handleCopySeed = () => {
+    navigator.clipboard.writeText(JSON.stringify(sampleSeed, null, 2));
+  };
+
+  return (
+    <Layout>
+      <PageSubheader breadcrumbs={breadcrumbs} />
+      <Box>
+        {/* Seed File Example Section */}
+        <Box mb="8">
+          <Heading size="6" mb="4">
+            Seed File Example
+          </Heading>
+          <Text as="p" mb="3" size="2">
+            A seed file is a JSON object used to start a new pipeline job. It
+            defines the job name, the pipeline to run, and any contextual data
+            the pipeline requires to begin.
+          </Text>
+          <Text as="p" mb="3" size="2" weight="bold">
+            Required fields:
+          </Text>
+          <ul className="list-disc list-inside mb-4 space-y-1">
+            <li className="text-sm text-gray-700">
+              <Text as="span" weight="bold">
+                name
+              </Text>{" "}
+              (string): Human-friendly title; non-empty, printable only, ≤120
+              chars; must be unique.
+            </li>
+            <li className="text-sm text-gray-700">
+              <Text as="span" weight="bold">
+                pipeline
+              </Text>{" "}
+              (string): Pipeline slug defined in your registry (e.g.,
+              content-generation).
+            </li>
+            <li className="text-sm text-gray-700">
+              <Text as="span" weight="bold">
+                data
+              </Text>{" "}
+              (object): Required but flexible; include any arbitrary keys your
+              pipeline tasks expect.
+            </li>
+          </ul>
+          <Box mb="3">
+            <Button
+              size="1"
+              onClick={handleCopySeed}
+              data-testid="copy-seed-example"
+            >
+              Copy
+            </Button>
+          </Box>
+          <pre className="text-xs bg-gray-50 p-3 rounded overflow-auto max-h-60 border border-gray-200">
+            {JSON.stringify(sampleSeed, null, 2)}
+          </pre>
+        </Box>
+
+        <Heading size="6" mb="4">
+          Pipeline Task IO API
+        </Heading>
+        <Box overflowX="auto">
+          <Table.Root>
+            <Table.Header>
+              <Table.Row>
+                <Table.ColumnHeaderCell>Function</Table.ColumnHeaderCell>
+                <Table.ColumnHeaderCell>Parameters</Table.ColumnHeaderCell>
+                <Table.ColumnHeaderCell>Returns</Table.ColumnHeaderCell>
+                <Table.ColumnHeaderCell>Notes</Table.ColumnHeaderCell>
+              </Table.Row>
+            </Table.Header>
+            <Table.Body>
+              {ioFunctions.map((fn) => (
+                <Table.Row key={fn.name}>
+                  <Table.RowHeaderCell>
+                    <Code size="3">io.{fn.name}</Code>
+                  </Table.RowHeaderCell>
+                  <Table.Cell>
+                    <Code size="3">{fn.params || "—"}</Code>
+                  </Table.Cell>
+                  <Table.Cell>
+                    <Code size="3">{fn.returns}</Code>
+                  </Table.Cell>
+                  <Table.Cell>
+                    {fn.description}
+                    <br />
+                    {fn.notes}
+                  </Table.Cell>
+                </Table.Row>
+              ))}
+            </Table.Body>
+          </Table.Root>
+        </Box>
+
+        <Heading size="6" mt="8" mb="4">
+          Pipeline Task LLM API
+        </Heading>
+        <Box mb="4">
+          <Heading size="4" mb="2">
+            Arguments
+          </Heading>
+          <Code size="3" mb="4">
+            {`{
+  messages: Array<{role: "system"|"user"|"assistant", content: string }>,
+  temperature?: number,
+  maxTokens?: number,
+  responseFormat?: "json" | { type: "json_object" | { type: "json_schema", name: string, json_schema: object } },
+  stop?: string | string[],
+  topP?: number,
+  frequencyPenalty?: number,
+  presencePenalty?: number,
+  seed?: number,
+  provider?: string,
+  model?: string,
+  metadata?: object,
+  maxRetries?: number
+}`}
+          </Code>
+          <Heading size="4" mb="2">
+            Returns
+          </Heading>
+          <Code size="3">{`Promise<{ content: any, usage?: object, raw?: any }>`}</Code>
+        </Box>
+
+        {llmFunctions && (
+          <Box overflowX="auto">
+            <Table.Root>
+              <Table.Header>
+                <Table.Row>
+                  <Table.ColumnHeaderCell>Function</Table.ColumnHeaderCell>
+                  <Table.ColumnHeaderCell>Model</Table.ColumnHeaderCell>
+                </Table.Row>
+              </Table.Header>
+              <Table.Body>
+                {Object.entries(llmFunctions).map(([provider, functions]) =>
+                  functions.map((fn) => (
+                    <Table.Row key={fn.fullPath}>
+                      <Table.RowHeaderCell>
+                        <Code size="3">{fn.fullPath}</Code>
+                      </Table.RowHeaderCell>
+                      <Table.Cell>
+                        <Code size="3">{fn.model}</Code>
+                      </Table.Cell>
+                    </Table.Row>
+                  ))
+                )}
+              </Table.Body>
+            </Table.Root>
+          </Box>
+        )}
+
+        <Heading size="6" mt="8" mb="4">
+          Validation API
+        </Heading>
+        <Text as="p" mb="3" size="2">
+          Schema validation helper available to task stages via validators.
+        </Text>
+        <Box mb="4">
+          <Heading size="4" mb="2">
+            Function Signature
+          </Heading>
+          <Code size="3">
+            {`validateWithSchema(schema: object, data: object | string): { valid: true } | { valid: false, errors: AjvError[] }`}
+          </Code>
+          <Heading size="4" mb="2" mt="4">
+            Behavior
+          </Heading>
+          <ul className="list-disc list-inside mb-4 space-y-1">
+            <li className="text-sm text-gray-700">
+              <Text as="span">
+                Parses string data to JSON; on parse failure returns{" "}
+                {`{ valid:false, errors:[{ keyword:"type", message:"must be a valid JSON object (string parsing failed)"} ]`}
+              </Text>
+            </li>
+            <li className="text-sm text-gray-700">
+              <Text as="span">
+                Uses Ajv({`{ allErrors: true, strict: false }`}); compiles
+                provided schema
+              </Text>
+            </li>
+            <li className="text-sm text-gray-700">
+              <Text as="span">Returns AJV errors array when invalid</Text>
+            </li>
+          </ul>
+          <Heading size="4" mb="2">
+            Source
+          </Heading>
+          <Code size="3">src/api/validators/json.js</Code>
+          <Heading size="4" mb="2" mt="4">
+            Usage Example
+          </Heading>
+          <Code size="3">{`export const validateStructure = async ({
+  io,
+  flags,
+  validators: { validateWithSchema },
+}) => {
+  const content = await io.readArtifact("research-output.json");
+  const result = validateWithSchema(researchJsonSchema, content);
+
+  if (!result.valid) {
+    console.warn("[Research:validateStructure] Validation failed", result.errors);
+    return { output: {}, flags: { ...flags, validationFailed: true } };
+  }
+  return { output: {}, flags };
+};`}</Code>
+        </Box>
+
+        <Heading size="6" mt="8" mb="4">
+          Environment Configuration
+        </Heading>
+        <Box mb="4">
+          <Heading size="4" mb="2">
+            Example .env Configuration
+          </Heading>
+          <Box overflowX="auto">
+            <Table.Root>
+              <Table.Header>
+                <Table.Row>
+                  <Table.ColumnHeaderCell>
+                    Environment Variable
+                  </Table.ColumnHeaderCell>
+                </Table.Row>
+              </Table.Header>
+              <Table.Body>
+                <Table.Row>
+                  <Table.RowHeaderCell>
+                    <Code size="3">OPENAI_API_KEY=</Code>
+                  </Table.RowHeaderCell>
+                </Table.Row>
+                <Table.Row>
+                  <Table.RowHeaderCell>
+                    <Code size="3">DEEPSEEK_API_KEY=</Code>
+                  </Table.RowHeaderCell>
+                </Table.Row>
+                <Table.Row>
+                  <Table.RowHeaderCell>
+                    <Code size="3">GEMINI_API_KEY=</Code>
+                  </Table.RowHeaderCell>
+                </Table.Row>
+                <Table.Row>
+                  <Table.RowHeaderCell>
+                    <Code size="3">ANTHROPIC_API_KEY=</Code>
+                  </Table.RowHeaderCell>
+                </Table.Row>
+                <Table.Row>
+                  <Table.RowHeaderCell>
+                    <Code size="3">ZHIPU_API_KEY=</Code>
+                  </Table.RowHeaderCell>
+                </Table.Row>
+              </Table.Body>
+            </Table.Root>
+          </Box>
+        </Box>
+      </Box>
+    </Layout>
+  );
+}

package/src/pages/PipelineDetail.jsx

@@ -1,10 +1,13 @@
 import React from "react";
-import { useParams } from "react-router-dom";
+import { data, useParams } from "react-router-dom";
 import { Box, Flex, Text } from "@radix-ui/themes";
+import * as Tooltip from "@radix-ui/react-tooltip";
 import JobDetail from "../components/JobDetail.jsx";
 import { useJobDetailWithUpdates } from "../ui/client/hooks/useJobDetailWithUpdates.js";
 import Layout from "../components/Layout.jsx";
+import PageSubheader from "../components/PageSubheader.jsx";
 import { statusBadge } from "../utils/ui.jsx";
+import { formatCurrency4, formatTokensCompact } from "../utils/formatters.js";
 
 export default function PipelineDetail() {
   const { jobId } = useParams();
@@ -12,7 +15,10 @@ export default function PipelineDetail() {
   // Handle missing job ID (undefined/null)
   if (jobId === undefined || jobId === null) {
     return (
-      <Layout title="Pipeline Details" showBackButton={true}>
+      <Layout
+        pageTitle="Pipeline Details"
+        breadcrumbs={[{ label: "Home", href: "/" }]}
+      >
         <Flex align="center" justify="center" className="min-h-64">
           <Box className="text-center">
             <Text size="5" weight="medium" color="red" className="mb-2">
@@ -24,11 +30,31 @@ export default function PipelineDetail() {
     );
   }
 
-  const { data: job, loading, error } = useJobDetailWithUpdates(jobId);
+  const {
+    data: job,
+    loading,
+    error,
+    isRefreshing,
+    isHydrated,
+  } = useJobDetailWithUpdates(jobId);
 
-  if (loading) {
+  // Only show loading screen on initial load, not during refresh
+  const showLoadingScreen = loading && !isHydrated;
+
+  if (showLoadingScreen) {
     return (
-      <Layout title="Pipeline Details" showBackButton={true}>
+      <Layout
+        pageTitle="Pipeline Details"
+        breadcrumbs={[
+          { label: "Home", href: "/" },
+          {
+            label:
+              job && job?.pipelineLabel
+                ? job.pipelineLabel
+                : "Pipeline Details",
+          },
+        ]}
+      >
         <Flex align="center" justify="center" className="min-h-64">
           <Box className="text-center">
             <Text size="5" weight="medium" className="mb-2">
@@ -42,7 +68,18 @@ export default function PipelineDetail() {
 
   if (error) {
     return (
-      <Layout title="Pipeline Details" showBackButton={true}>
+      <Layout
+        pageTitle="Pipeline Details"
+        breadcrumbs={[
+          { label: "Home", href: "/" },
+          {
+            label:
+              job && job?.pipelineLabel
+                ? job.pipelineLabel
+                : "Pipeline Details",
+          },
+        ]}
+      >
         <Flex align="center" justify="center" className="min-h-64">
           <Box className="text-center">
             <Text size="5" weight="medium" color="red" className="mb-2">
@@ -58,8 +95,15 @@ export default function PipelineDetail() {
   }
 
   if (!job) {
+    const pipelineDisplay = "Pipeline Details";
     return (
-      <Layout title="Pipeline Details" showBackButton={true}>
+      <Layout
+        pageTitle="Pipeline Details"
+        breadcrumbs={[
+          { label: "Home", href: "/" },
+          { label: job.pipelineLabel || "Pipeline Details" },
+        ]}
+      >
         <Flex align="center" justify="center" className="min-h-64">
           <Box className="text-center">
             <Text size="5" weight="medium" className="mb-2">
@@ -89,22 +133,87 @@ export default function PipelineDetail() {
       return { tasks: pipelineTasks };
     })();
 
-  // Header actions: job ID and status badge
-  const headerActions = (
-    <Flex align="center" gap="3" className="shrink-0">
+  const pageTitle = job.name || "Pipeline Details";
+
+  const breadcrumbs = [
+    { label: "Home", href: "/" },
+    {
+      label: job && job?.pipelineLabel ? job.pipelineLabel : "Pipeline Details",
+    },
+    ...(job.name ? [{ label: job.name }] : []),
+  ];
+
+  // Derive cost data from job object with safe fallbacks
+  const totalCost = job?.totalCost || job?.costs?.summary?.totalCost || 0;
+  const totalTokens = job?.totalTokens || job?.costs?.summary?.totalTokens || 0;
+  const totalInputTokens = job?.costs?.summary?.totalInputTokens || 0;
+  const totalOutputTokens = job?.costs?.summary?.totalOutputTokens || 0;
+
+  // Create cost indicator with tooltip when token data is available
+  const costIndicator = (
+    <Text size="2" color="gray">
+      Cost: {totalCost > 0 ? formatCurrency4(totalCost) : "—"}
+    </Text>
+  );
+
+  const costIndicatorWithTooltip =
+    totalCost > 0 && totalTokens > 0 ? (
+      <Tooltip.Provider delayDuration={100}>
+        <Tooltip.Root>
+          <Tooltip.Trigger asChild>
+            <Box
+              className="cursor-help border-b border-dotted border-gray-400 hover:border-gray-600 transition-colors"
+              aria-label={`Total cost: ${formatCurrency4(totalCost)}, ${formatTokensCompact(totalTokens)}`}
+            >
+              {costIndicator}
+            </Box>
+          </Tooltip.Trigger>
+          <Tooltip.Portal>
+            <Tooltip.Content
+              className="bg-gray-900 text-white px-2 py-1 rounded text-xs max-w-xs"
+              sideOffset={5}
+            >
+              <div className="space-y-1">
+                <div className="font-semibold">
+                  {formatTokensCompact(totalTokens)}
+                </div>
+                {totalInputTokens > 0 && totalOutputTokens > 0 && (
+                  <div className="text-gray-300">
+                    Input: {formatTokensCompact(totalInputTokens)} • Output:{" "}
+                    {formatTokensCompact(totalOutputTokens)}
+                  </div>
+                )}
+              </div>
+              <Tooltip.Arrow className="fill-gray-900" />
+            </Tooltip.Content>
+          </Tooltip.Portal>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    ) : (
+      costIndicator
+    );
+
+  // Right side content for PageSubheader: job ID, cost indicator, and status badge
+  const subheaderRightContent = (
+    <Flex align="center" gap="3" className="shrink-0 flex-wrap">
       <Text size="2" color="gray">
         ID: {job.id || jobId}
       </Text>
+      {costIndicatorWithTooltip}
       {statusBadge(job.status)}
     </Flex>
   );
 
   return (
-    <Layout
-      title={job.name || "Pipeline Details"}
-      showBackButton={true}
-      actions={headerActions}
-    >
+    <Layout pageTitle={pageTitle} breadcrumbs={breadcrumbs}>
+      <PageSubheader breadcrumbs={breadcrumbs} maxWidth="max-w-7xl">
+        {subheaderRightContent}
+        {isRefreshing && (
+          <Text size="2" color="blue" className="ml-3 animate-pulse">
+            Refreshing...
+          </Text>
+        )}
+      </PageSubheader>
       <JobDetail job={job} pipeline={pipeline} />
     </Layout>
   );