@output.ai/core 0.1.9-dev.pr156.0 → 0.1.10

package/README.md

@@ -1,247 +1,98 @@
-# Core
+# @output.ai/core
 
-Provides tools to develop and run a workflow, which is a well defined logical unit of work.
+Workflow orchestration and worker runtime for building durable LLM applications with Temporal.
 
-## Structure
+[![npm version](https://img.shields.io/npm/v/@output.ai/core)](https://www.npmjs.com/package/@output.ai/core)
+[![Documentation](https://img.shields.io/badge/docs-docs.output.ai-blue)](https://docs.output.ai/packages/core)
 
-Workflows are defined using core functions ("workflow", "step", "evaluator"), these are defined in separate files, and must be placed within the same folder:
-
-```
-└ workflows
-  └ example
-    ├ workflow.ts|js <- workflow entry point
-    ├ steps.ts|js <- file containing steps used by the workflow
-    ├ evaluators.ts|js <- file containing evaluating functions
-    └ prompt.prompt <- a prompt file
-  └ other-example
+## Installation
 
+```bash
+npm install @output.ai/core
 ```
 
-Workflows are the orchestrator and steps are executors. So the workflow only call the steps and the steps call the IO operations, like APIs, DBs, LLMs, etc. Evaluators are just another different flavor for steps, they work the same, but must return an `EvaluationResult` object.
-
-## Components
+## Quick Start
 
-### Workflow
+```typescript
+// workflow.ts
+import { workflow, z } from '@output.ai/core';
+import { processData } from './steps.js';
 
-The main code, must contain only deterministic orchestration code.
-
-File: `workflow.js`
-
-Example:
-```js
-import { workflow, z } from '@output.ai/workflow';
-import { guessByName } from './steps.js';
-
-export default workflow( {
-  name: 'guessMyProfession',
-  description: 'Guess a person profession by its name',
-  inputSchema: z.object( {
-    name: z.string()
-  } ),
-  outputSchema: z.object( {
-    profession: z.string()
-  } ),
-  fn: async input => {
-    const profession = await guessByName( input.name );
-    return { profession };
+export default workflow({
+  name: 'myWorkflow',
+  inputSchema: z.object({ text: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+  fn: async (input) => {
+    const result = await processData(input.text);
+    return { result };
   }
-})
+});
 ```
 
-Workflows can only import the following files
-
-#### Components
-- `evaluators.js`
-- `shared_steps.js`
-- `steps.js`
-- `workflow.js`
+```typescript
+// steps.ts
+import { step, z } from '@output.ai/core';
 
-#### Core library
-- `@output.ai.core`
-
-#### Whitelisted files
-- `types.js`
-- `consts.js`
-- `constants.js`
-- `vars.js`
-- `variables.js`
-- `utils.js`
-- `tools.js`
-- `functions.js`
-- `shared.js`
-
-### Step
-
-Re-usable units of work that can contain IO, used by the workflow.
-
-File: `steps.js`
-
-Example:
-```js
-import { api } from './api.js'
-
-export const guessByName = step( {
-  name: 'guessByName',
+export const processData = step({
+  name: 'processData',
   inputSchema: z.string(),
   outputSchema: z.string(),
-  fn: async name => {
-    const res = await api.consumer( name );
-    return res.body;
-  }
-} )
-```
-
-### Shared Steps
-
-By default, steps are exclusive to the workflow, so it is not passible to use these steps from elsewhere. In order to have shared steps and make them accessible in different workflows, create a shared steps file. This file can be relatively imported anywhere.
-
-File: `shared_steps.js`
-
-Example:
-```js
-export const mySharedStep = step( {
-  name: 'mySharedStep',
-  ...
-} )
-```
-
-And the usage is the same as any step:
-`workflow.js`
-```js
-import { mySharedStep } from '../../tools/shared_steps.js'
-```
-
-### Evaluators
-
-Steps that analyze LLM response, or take other measurements are contained in evaluators.
-
-File: `evaluators.js`
-
-Example:
-```js
-import { evaluator, EvaluationStringResult } from './api.js'
-
-export const judgeResult = evaluator( {
-  name: 'judgeResult',
-  inputSchema: z.string(),
-  fn: async name => {
-    ...
-    return new EvaluationStringResult({
-      value: 'good',
-      confidence: .95
-    });
+  fn: async (text) => {
+    return text.toUpperCase();
   }
-} )
+});
 ```
 
-Its usage is the same as steps:
-`workflow.js`
-```js
-import { workflow, z } from '@output.ai/workflow';
-import { judgeResult } from './evaluators.js';
-
-export default workflow( {
-  name: 'guessMyProfession',
-  inputSchema: z.object( {
-    name: z.string()
-  } ),
-  outputSchema: z.object( {
-    result: z.string()
-  } ),
-  fn: async input => {
-    const judgment = await judgeResult( input.name );
-    return { result: judgement.value };
-  }
-})
-```
-
-## Webhooks
-
-Workflows can call webhooks that will stop their execution until an answer is given back.
-
-```js
-import { workflow, createWebhook } from '@output.ai/workflow';
-import { guessByName } from './steps.js';
-
-export default workflow( {
-  ...
-  fn: async input => {
-    ...
-
-    const result = await createWebhook( {
-      url: 'http://xxx.xxx/feedback',
-      payload: {
-        progressSoFar: 'plenty'
-      }
-    } );
-
-  }
-})
-```
-
-The url of the example will receive the payload, plus the workflowId:
-
-```js
-{
-  workflowId: '', // alphanumerical id of the workflow execution,
-  payload: { }, // the payload sent using tools.webhook()
-}
-```
-
-To resume the workflow, a POST has to be made with a response payload and the workflowId.
-
-- Production: `https://output-api-production.onrender.com/workflow/feedback`
-- Staging: `https://output-api-staging.onrender.com/workflow/feedback`
-- Local: `http://localhost:3001/workflow/feedback`
-
-Example:
-
-```bash
-POST http://locahost:3001/workflow/feedback
-  {
-    workflowId,
-    payload: {}
-  }
-```
-
-## Options
-
-All core interface functions: workflow, step, evaluator have similar signature, with the following options:
-- name: The function name, used to call it internally and identify it in the trace files, must be a code friendly string;
-- description: Human description of the workflow/step, used for the catalog;
-- inputSchema: a zod object indicating the type of the argument received by the `fn` function. It is validated. Omit if it doesn't have input arguments;
-- outputSchema: a zod object indicating the type of that the `fn` function returns. It is validated. Omit if it is void. Evaluators do not have this option, since they must always return an EvaluationResult object;
-- fn: The actual implementation of the workflow/step, including all its logic.
-- options: Advanced options that will overwrite Temporal's ActivityOptions when calling activities.
-
-  If used on `workflow()` it will apply for all activities. If used on `step()` or `evaluator()` it will apply only to that underlying activity. If changed in both places, the end value will be a merge between the initial values, workflow values and the step values.
-
-  Order of precedence
-  `step options > workflow options > default options`
-
-## Developing
-
-To develop workflows you need the code, which will be called the worker, the API and the engine (Temporal).
-
-After having the API and the engine running, to start the worker just run:
-
-```js
-`npm run outputai`
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `workflow` | Define orchestration logic that coordinates steps |
+| `step` | Define reusable units of work that handle I/O |
+| `evaluator` | Define steps that return evaluation results |
+| `createWebhook` | Pause workflow execution until external input |
+| `z` | Zod schema library for input/output validation |
+
+## File Structure
+
+Each workflow lives in its own directory:
+
+```text
+src/workflows/
+└── my-workflow/
+    ├── workflow.ts           # Workflow definition
+    ├── steps.ts              # Step implementations
+    ├── evaluators.ts         # Evaluators (optional)
+    ├── prompts/              # LLM prompt templates
+    │   └── prompt@v1.prompt
+    └── scenarios/            # Test scenarios
+        └── test_input.json
 ```
 
-## Env variables
-
-Necessary env variables to run the worker locally:
-
-- `TEMPORAL_ADDRESS`: The temporal backend address, prefer the remote;
-- `TEMPORAL_NAMESPACE`: The name of the namespace, if using remote, use: "output-staging.i0jzq";
-- `TEMPORAL_API_KEY`: The API key to access remote temporal. If using local temporal, leave it blank;
-- `CATALOG_ID`: The name of the local catalog, always set this. Use your email;
-- `API_AUTH_KEY`: The API key to access the Framework API. Local can be blank, remote use the proper API Key;
-- `TRACE_LOCAL_ON`: A "stringbool" value indicating if traces should be saved locally, needs REDIS_URL;
-- `TRACE_REMOTE_ON`: A "stringbool" value indicating if traces should be saved remotely, needs REDIS_URL and AWS_* secrets;
-- `REDIS_URL`: The redis address to connect. Only necessary when any type of trace is enabled;
-- `TRACE_REMOTE_S3_BUCKET`: The AWS S3 bucket to send the traces. Only necessary when remote trace is enabled;
-- `AWS_REGION`: AWS region to connect to send the traces, must match the bucket region. Only necessary when remote trace is enabled;
-- `AWS_ACCESS_KEY_ID`: AWS key id. Only necessary when remote trace is enabled;
-- `AWS_SECRET_ACCESS_KEY`: AWS secrete. Only necessary when remote trace is enabled;
+## Environment Variables
+
+The worker reads these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `TEMPORAL_ADDRESS` | Temporal backend address |
+| `TEMPORAL_NAMESPACE` | Temporal namespace name |
+| `TEMPORAL_API_KEY` | API key for remote Temporal (leave blank for local) |
+| `CATALOG_ID` | **Required.** Name of the local catalog (use your email) |
+| `API_AUTH_KEY` | API key for Framework API (blank for local, required for remote) |
+| `TRACE_LOCAL_ON` | Enable local trace saving (requires `REDIS_URL`) |
+| `TRACE_REMOTE_ON` | Enable remote trace saving (requires `REDIS_URL` and AWS secrets) |
+| `REDIS_URL` | Redis address (required when tracing is enabled) |
+| `TRACE_REMOTE_S3_BUCKET` | AWS S3 bucket for traces (required for remote tracing) |
+| `AWS_REGION` | AWS region matching the S3 bucket (required for remote tracing) |
+| `AWS_ACCESS_KEY_ID` | AWS key ID (required for remote tracing) |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key (required for remote tracing) |
+
+## Documentation
+
+For comprehensive documentation, visit:
+
+- [Package Reference](https://docs.output.ai/packages/core)
+- [Workflows Guide](https://docs.output.ai/core/workflows)
+- [Steps Guide](https://docs.output.ai/core/steps)
+- [Getting Started](https://docs.output.ai/quickstart)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.1.9-dev.pr156.0",
+  "version": "0.1.10",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -40,7 +40,10 @@
     "stacktrace-parser": "0.1.11",
     "zod": "4.1.12"
   },
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "imports": {
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",

package/src/tracing/processors/local/index.js

@@ -4,32 +4,67 @@ import { fileURLToPath } from 'url';
 import buildTraceTree from '../../tools/build_trace_tree.js';
 import { EOL } from 'node:os';
 
-const oneWeekInMS = 1000 * 60 * 60 * 24 * 7;
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
-const tempDir = join( __dirname, 'temp', 'traces' );
+
+const PURGE_TEMP_FILES_THRESHOLD = 1000 * 60 * 60 * 24 * 7; // 1 week in milliseconds
+
+// The path to the project root
+const LOCAL_PROJECT_ROOT_PATH = process.argv[2] || process.cwd();
+
+// The path to the local trace logs
+const LOCAL_TRACE_LOG_PATH = join( LOCAL_PROJECT_ROOT_PATH, 'logs' );
+
+// The path to the temporary trace logs
+const TMP_TRACE_LOG_PATH = join( __dirname, 'temp', 'traces' );
 
 const accumulate = ( { entry, executionContext: { workflowId, startTime } } ) => {
-  const path = join( tempDir, `${startTime}_${workflowId}.trace` );
+  const path = join( TMP_TRACE_LOG_PATH, `${startTime}_${workflowId}.trace` );
   appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
   return readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
 };
 
-const cleanupOldTempFiles = ( threshold = Date.now() - oneWeekInMS ) =>
-  readdirSync( tempDir )
+const cleanupOldTempFiles = ( threshold = Date.now() - PURGE_TEMP_FILES_THRESHOLD ) =>
+  readdirSync( TMP_TRACE_LOG_PATH )
     .filter( f => +f.split( '_' )[0] < threshold )
-    .forEach( f => rmSync( join( tempDir, f ) ) );
+    .forEach( f => rmSync( join( TMP_TRACE_LOG_PATH, f ) ) );
+
+/**
+ * Get the host trace log path, which is used for reporting trace locations.
+ * In containerized environments (e.g., Docker), this can be different from the local path
+ * to map container paths to host filesystem paths.
+ * @returns {string} The host trace log path from HOST_TRACE_PATH env var, or local path as fallback
+ */
+const getHostTraceLogPath = () => {
+  return process.env.HOST_TRACE_PATH || LOCAL_TRACE_LOG_PATH;
+};
 
 /**
  * Init this processor
  */
 export const init = () => {
-  mkdirSync( tempDir, { recursive: true } );
+  mkdirSync( TMP_TRACE_LOG_PATH, { recursive: true } );
   cleanupOldTempFiles();
 };
 
-const getOutputDir = workflowName => join( process.argv[2], 'logs', 'runs', workflowName );
+/**
+ * Get the local file system path for ALL file I/O operations (read/write)
+ * Uses the project root path passed as argv[2], falls back to cwd
+ * @param {string} workflowName - The name of the workflow
+ * @returns {string} The local filesystem path for file operations
+ */
+const getLocalOutputDir = workflowName => {
+  return join( LOCAL_PROJECT_ROOT_PATH, 'logs', 'runs', workflowName );
+};
 
-const getRelativeOutputDir = workflowName => join( 'logs', 'runs', workflowName );
+/**
+ * Get the host path for reporting trace file locations to users
+ * Uses HOST_TRACE_PATH if set (for Docker), otherwise uses project root
+ * @param {string} workflowName - The name of the workflow
+ * @returns {string} The path to report to users/API
+ */
+const getReportOutputDir = workflowName => {
+  return join( getHostTraceLogPath(), 'runs', workflowName );
+};
 
 const buildOutputFileName = ( { startTime, workflowId } ) => {
   const timestamp = new Date( startTime ).toISOString().replace( /[:T.]/g, '-' );
@@ -50,7 +85,8 @@ export const exec = ( { entry, executionContext } ) => {
   const { workflowId, workflowName, startTime } = executionContext;
   const content = buildTraceTree( accumulate( { entry, executionContext } ) );
 
-  const dir = getOutputDir( workflowName );
+  // Always use local path for writing files
+  const dir = getLocalOutputDir( workflowName );
   const path = join( dir, buildOutputFileName( { startTime, workflowId } ) );
 
   mkdirSync( dir, { recursive: true } );
@@ -58,12 +94,14 @@ export const exec = ( { entry, executionContext } ) => {
 };
 
 /**
- * Returns where the trace is saved (as a relative path)
+ * Returns where the trace is saved as an absolute path
  * @param {object} args
  * @param {string} args.startTime - The start time of the workflow
  * @param {string} args.workflowId - The id of the workflow execution
  * @param {string} args.workflowName - The name of the workflow
- * @returns {string} The relative path where the trace will be saved
+ * @returns {string} The absolute path where the trace will be saved
  */
-export const getDestination = ( { startTime, workflowId, workflowName } ) =>
-  join( getRelativeOutputDir( workflowName ), buildOutputFileName( { workflowId, startTime } ) );
+export const getDestination = ( { startTime, workflowId, workflowName } ) => {
+  // Use report path for reporting to users/API
+  return join( getReportOutputDir( workflowName ), buildOutputFileName( { workflowId, startTime } ) );
+};

package/src/tracing/processors/local/index.spec.js

@@ -29,6 +29,7 @@ describe( 'tracing/processors/local', () => {
     vi.clearAllMocks();
     store.files.clear();
     process.argv[2] = '/tmp/project';
+    delete process.env.HOST_TRACE_PATH; // Clear HOST_TRACE_PATH for clean tests
   } );
 
   it( 'init(): creates temp dir and cleans up old files', async () => {
@@ -39,6 +40,7 @@ describe( 'tracing/processors/local', () => {
 
     init();
 
+    // Should create temp dir relative to module location using __dirname
     expect( mkdirSyncMock ).toHaveBeenCalledWith( expect.stringMatching( /temp\/traces$/ ), { recursive: true } );
     expect( rmSyncMock ).toHaveBeenCalledTimes( 1 );
   } );
@@ -60,11 +62,12 @@ describe( 'tracing/processors/local', () => {
 
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 3 );
     const [ writtenPath, content ] = writeFileSyncMock.mock.calls.at( -1 );
-    expect( writtenPath ).toMatch( /\/logs\/runs\/WF\// );
+    // Changed: Now uses process.cwd() + '/logs' fallback when HOST_TRACE_PATH not set
+    expect( writtenPath ).toMatch( /\/runs\/WF\// );
     expect( JSON.parse( content.trim() ).count ).toBe( 3 );
   } );
 
-  it( 'getDestination(): returns relative path', async () => {
+  it( 'getDestination(): returns absolute path', async () => {
     const { getDestination } = await import( './index.js' );
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
@@ -73,9 +76,74 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Should return a relative path, not an absolute path
-    expect( destination ).not.toMatch( /^\/|^[A-Z]:\\/i ); // Not starting with / or Windows drive letter
-    expect( destination ).toBe( 'logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
+    // Should return an absolute path
+    expect( destination ).toMatch( /^\/|^[A-Z]:\\/i ); // Starting with / or Windows drive letter
+    expect( destination ).toContain( '/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
+  } );
+
+  it( 'exec(): writes to container path regardless of HOST_TRACE_PATH', async () => {
+    const { exec, init } = await import( './index.js' );
+
+    // Set HOST_TRACE_PATH to simulate Docker environment
+    process.env.HOST_TRACE_PATH = '/host/path/logs';
+
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
+    const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
+
+    // Should write to process.cwd()/logs, NOT to HOST_TRACE_PATH
+    expect( writtenPath ).not.toContain( '/host/path/logs' );
+    expect( writtenPath ).toMatch( /logs\/runs\/WF\// );
+  } );
+
+  it( 'getDestination(): returns HOST_TRACE_PATH when set', async () => {
+    const { getDestination } = await import( './index.js' );
+
+    // Set HOST_TRACE_PATH to simulate Docker environment
+    process.env.HOST_TRACE_PATH = '/host/path/logs';
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const workflowId = 'workflow-id-123';
+    const workflowName = 'test-workflow';
+
+    const destination = getDestination( { startTime, workflowId, workflowName } );
+
+    // Should return HOST_TRACE_PATH-based path for reporting
+    expect( destination ).toBe( '/host/path/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
+  } );
+
+  it( 'separation of write and report paths works correctly', async () => {
+    const { exec, getDestination, init } = await import( './index.js' );
+
+    // Set HOST_TRACE_PATH to simulate Docker environment
+    process.env.HOST_TRACE_PATH = '/Users/ben/project/logs';
+
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const workflowId = 'workflow-id-123';
+    const workflowName = 'test-workflow';
+    const ctx = { executionContext: { workflowId, workflowName, startTime } };
+
+    // Execute to write file
+    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+
+    // Get destination for reporting
+    const destination = getDestination( { startTime, workflowId, workflowName } );
+
+    // Verify write path is local
+    const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
+    expect( writtenPath ).not.toContain( '/Users/ben/project' );
+    expect( writtenPath ).toMatch( /logs\/runs\/test-workflow\// );
+
+    // Verify report path uses HOST_TRACE_PATH
+    expect( destination ).toBe( '/Users/ben/project/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 } );
 

package/src/tracing/trace_engine.js

@@ -9,11 +9,13 @@ const traceBus = new EventEmitter();
 const processors = [
   {
     isOn: isStringboolTrue( process.env.TRACE_LOCAL_ON ),
+    name: 'LOCAL',
     init: localProcessor.init,
     exec: localProcessor.exec
   },
   {
     isOn: isStringboolTrue( process.env.TRACE_REMOTE_ON ),
+    name: 'REMOTE',
     init: s3Processor.init,
     exec: s3Processor.exec
   }
@@ -25,7 +27,13 @@ const processors = [
 export const init = async () => {
   for ( const p of processors.filter( p => p.isOn ) ) {
     await p.init();
-    traceBus.addListener( 'entry', p.exec );
+    traceBus.addListener( 'entry', async ( ...args ) => {
+      try {
+        await p.exec( ...args );
+      } catch ( error ) {
+        console.error( `[Tracing] "${p.name}" processor execution error.`, error );
+      }
+    } );
   }
 };