thoughtgear 0.1.1 → 0.1.2

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,9 @@ 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`.
 
 ## Switching providers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoughtgear",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",