thoughtgear 0.1.1 → 0.1.3

package/README.md

@@ -116,8 +116,8 @@ Notes:
 
 - The `sessionId` is just a string you choose (e.g. a user ID, a chat thread ID, a UUID).
 - Without `sessionId`, each `handlePrompt` is isolated — the model only sees that single prompt and the loop's own tool calls.
-- Session history is loaded via `orm.getSessionHistory(sessionId)`. The in-memory adapter implements this; the Mongo / SQL adapters are stubs (one-liner query you fill in).
-- Resume a session in a different process by passing the same `sessionId` and pointing at the same persistent DB (e.g. `db: { type: "mongodb", ... }`).
+- Session history is loaded via `orm.getSessionHistory(sessionId)`. The in-memory, files, and S3 adapters fully implement this; the Mongo / SQL adapters are stubs (one-liner query you fill in).
+- Resume a session in a different process by passing the same `sessionId` and pointing at the same persistent DB (e.g. `db: { type: "files", path: "./.thoughtgear" }` or `db: { type: "s3", bucket: "my-bucket" }`).
 
 ## Streaming callbacks
 
@@ -134,7 +134,7 @@ callbacks: {
 
 ## Persistence: `orm` or `db`
 
-`PromptHandler` accepts **either** a pre-built `orm` **or** raw `db` settings. The `db` form is just a shortcut — internally the handler constructs an `ORM` from your `DbConfig` and picks the right adapter (`memory` / `mongodb` / `sql`).
+`PromptHandler` accepts **either** a pre-built `orm` **or** raw `db` settings. The `db` form is just a shortcut — internally the handler constructs an `ORM` from your `DbConfig` and picks the right adapter (`memory` / `files` / `s3` / `mongodb` / `sql`).
 
 ### Shortcut: pass `db` settings
 
@@ -153,10 +153,69 @@ Other supported `db` shapes:
 
 ```ts
 db: { type: "memory" }
+db: { type: "files", path: "./.thoughtgear" }
+db: { type: "s3", bucket: "my-bucket", path: "thoughtgear/prod", region: "us-east-1" }
 db: { type: "mongodb", uri: "...", database: "..." }
 db: { type: "sql", dialect: "postgres", uri: "..." }
 ```
 
+### Files adapter (`type: "files"`)
+
+Zero-dependency, on-disk JSON persistence — ideal for local development, CLIs, and single-process apps that don't want to stand up a database. Pass a directory and the adapter writes:
+
+```
+{path}/
+  sessions/{sessionId}.json   # all messages + run states for the session
+  runs/{runId}.json           # for runs without a sessionId
+  cache.json
+  memory.json
+```
+
+```ts
+const handler = new PromptHandler({
+  sessionId: "user-42",
+  context: "You are a helpful assistant.",
+  tools: [],
+  model: { name: "gpt-4o-mini", provider: "openai", apiKey: process.env.OPENAI_API_KEY! },
+  db: { type: "files", path: "./.thoughtgear" },
+});
+```
+
+Writes are atomic (write-temp-then-rename) but there is no cross-process locking — concurrent writers to the same session file can race. That's fine for single-process use; reach for `s3` / `mongodb` if you need a multi-writer story.
+
+### S3 adapter (`type: "s3"`)
+
+Same layout as the files adapter, but keys live in an S3 bucket under an optional prefix:
+
+```
+{bucket}/{path}/
+  sessions/{sessionId}.json
+  runs/{runId}.json
+  cache.json
+  memory.json
+```
+
+```ts
+const handler = new PromptHandler({
+  sessionId: "user-42",
+  context: "You are a helpful assistant.",
+  tools: [],
+  model: { name: "gpt-4o-mini", provider: "openai", apiKey: process.env.OPENAI_API_KEY! },
+  db: {
+    type: "s3",
+    bucket: "my-bucket",
+    path: "thoughtgear/prod",        // optional key prefix
+    region: "us-east-1",              // optional — falls back to AWS_REGION env
+    credentials: {                    // optional — omit to use the default credential chain
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    },
+  },
+});
+```
+
+`region` and `credentials` are both optional. When omitted, the AWS SDK's default credential chain (env vars, shared config file, IAM role) is used — typical for apps running on EC2 / ECS / Lambda. Same race caveat as the files adapter applies (S3 has no atomic compare-and-swap).
+
 ### Bring your own ORM
 
 Use this when you want to share one ORM across multiple handlers, or you need to read the transcript back yourself:
@@ -184,7 +243,121 @@ const history = await orm.getHistory(runId);
 const state   = await orm.getRunState(runId);
 ```
 
-Mongo collections used: `messages`, `run_states`, `cache`, `memory`. The Mongo and SQL adapters are stubbed in `src/classes/PromptHandler.ts` — fill in the eight `OrmAdapter` methods using the `mongodb` / `pg` / `kysely` drivers to make them live.
+Adapter status:
+- `memory`, `files`, `s3` — fully implemented.
+- `mongodb`, `sql` — stubbed in `src/classes/PromptHandler.ts`; fill in the eight `OrmAdapter` methods using the `mongodb` / `pg` / `kysely` drivers to make them live. Mongo collections used: `messages`, `run_states`, `cache`, `memory`.
+
+## Executors
+
+Each iteration of the agent loop is **stateless against the ORM** — the run, transcript, and tool results are persisted before the iteration returns. An **Executor** decides *how* the next iteration gets driven. Same loop semantics either way; the choice is operational.
+
+```ts
+interface Executor {
+  scheduleNextIteration(runId: string): Promise<void>;
+}
+```
+
+Two are built in. You pass one via `executor` on the constructor; the default is `LocalExecutor`.
+
+### `LocalExecutor` (default)
+
+Drives the next iteration in the same process by awaiting `handler.continueRun(runId)`. This is what you want for any single-process app — a script, a server handling a request end-to-end, a CLI, tests.
+
+```ts
+import { PromptHandler, LocalExecutor } from "thoughtgear";
+
+const handler = new PromptHandler({
+  context: "...",
+  tools: [...],
+  model: { ... },
+  db: { type: "memory" },
+  // executor: new LocalExecutor(),   // implicit — this is the default
+});
+
+await handler.handlePrompt({ text: "..." });   // resolves when the whole run finishes
+```
+
+`handlePrompt` / `continueRun` resolve only once the model is done iterating, so callers can `await` the full run.
+
+### `LambdaExecutor`
+
+Persists state, fires a **fresh invocation** of your Lambda with `{ runId, action: "continue" }`, and returns immediately. The next tick of the loop runs in a new invocation that loads state from the shared ORM.
+
+```ts
+import { PromptHandler, LambdaExecutor, makeLambdaHandler } from "thoughtgear";
+import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";
+
+const lambda = new LambdaClient({});
+const executor = new LambdaExecutor(async (payload) => {
+  await lambda.send(new InvokeCommand({
+    FunctionName: process.env.SELF_FUNCTION_NAME!,   // this function's own ARN/name
+    InvocationType: "Event",                          // fire-and-forget
+    Payload: Buffer.from(JSON.stringify(payload)),
+  }));
+});
+
+const handler = new PromptHandler({
+  context: "...",
+  tools: [...],
+  model: { ... },
+  db: { type: "s3", bucket: "my-bucket", path: "thoughtgear/prod" },
+  executor,
+});
+
+export const lambdaHandler = makeLambdaHandler(handler);
+```
+
+`makeLambdaHandler` routes events for you:
+
+```ts
+type LambdaEvent =
+  | { action: "start";    text: string; files?: FileAttachment[] }
+  | { action: "continue"; runId: string };
+```
+
+So one Lambda function serves both the initial prompt (`action: "start"`) and every continuation tick (`action: "continue"`).
+
+Requirements:
+- **Shared persistence.** Use `s3`, `mongodb`, or `sql` — `memory` won't survive an invocation boundary and `files` is single-host.
+- **Self-invoke permission.** The Lambda's IAM role needs `lambda:InvokeFunction` on its own ARN, plus whatever the persistence adapter needs.
+- **Idempotency.** With fire-and-forget invocations, an upstream retry could in theory schedule the same `runId` twice; the ORM has no atomic compare-and-swap on `files`/`s3`. In practice this is rare, but worth knowing if you're at high volume.
+
+### When to pick which
+
+| Scenario | Executor | Why |
+| --- | --- | --- |
+| Local script, CLI, single-process server | `LocalExecutor` | No infra needed; awaitable end-to-end. |
+| HTTP server returning the final answer in one response | `LocalExecutor` | The request handler awaits the whole loop. |
+| HTTP server returning `runId` immediately, client polls | either | Use `Local` with a background worker, or `Lambda` for serverless. |
+| Long-running agent runs (many tool calls, big chains) | `LambdaExecutor` | Each iteration fits inside one invocation — no 15-min Lambda cap risk. |
+| Bursty workloads, scale-to-zero | `LambdaExecutor` | Pay only for active iterations; no idle worker. |
+| Same code in dev and prod | both | Swap the executor at construction time; everything else stays identical. |
+
+### Custom executors
+
+Anything that implements `scheduleNextIteration(runId)` works. Useful scenarios:
+
+- **Queue-backed worker** — push `{ runId, action: "continue" }` to SQS / Redis / Cloud Tasks; a separate worker pool dequeues and calls `continueRun(runId)`. Buys you backpressure and retries the framework doesn't give you natively.
+- **Cron / scheduled continuation** — schedule the next tick instead of firing it immediately (e.g. to throttle, or wait on an external event).
+- **Cross-region failover** — invoke a Lambda in a different region when the primary is degraded.
+
+Skeleton:
+
+```ts
+import { Executor, PromptHandler } from "thoughtgear";
+
+class SqsExecutor implements Executor {
+  constructor(private queueUrl: string, private sqs: SQSClient) {}
+  async scheduleNextIteration(runId: string) {
+    await this.sqs.send(new SendMessageCommand({
+      QueueUrl: this.queueUrl,
+      MessageBody: JSON.stringify({ runId, action: "continue" }),
+    }));
+  }
+}
+```
+
+Your worker then reads the queue and calls `handler.continueRun(runId)` per message.
 
 ## Switching providers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoughtgear",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Minimal agent loop: send a prompt, the model can call tools, and the loop persists transcript + state until the model is done.",
   "type": "module",
   "main": "./dist/index.js",