conversationalist 0.0.3 → 0.0.4

package/README.md

@@ -218,6 +218,108 @@ const boundTruncate = history.bind(truncateToTokenLimit);
 boundTruncate(4000); // Uses tiktokenEstimator automatically
 ```
 
+### Markdown Conversion
+
+Convert conversations to human-readable Markdown format, or parse Markdown back into a conversation object.
+
+#### Basic Usage (Clean Markdown)
+
+By default, `toMarkdown` produces clean, readable Markdown without metadata:
+
+```ts
+import {
+  toMarkdown,
+  fromMarkdown,
+  createConversation,
+  appendMessages,
+} from 'conversationalist';
+
+let conversation = createConversation({ id: 'conv-1' });
+conversation = appendMessages(
+  conversation,
+  { role: 'user', content: 'What is 2 + 2?' },
+  { role: 'assistant', content: 'The answer is 4.' },
+);
+
+const markdown = toMarkdown(conversation);
+// Output:
+// ### User
+//
+// What is 2 + 2?
+//
+// ### Assistant
+//
+// The answer is 4.
+```
+
+When parsing simple Markdown without metadata, `fromMarkdown` generates new IDs and uses sensible defaults:
+
+```ts
+const parsed = fromMarkdown(markdown);
+// parsed.id is a new generated ID
+// parsed.status is 'active'
+// Message IDs are generated, positions are assigned sequentially
+```
+
+#### Lossless Round-Trip (with Metadata)
+
+For archiving or backup scenarios where you need to preserve all data, use `{ includeMetadata: true }`:
+
+```ts
+const markdown = toMarkdown(conversation, { includeMetadata: true });
+// Output includes YAML frontmatter with all metadata keyed by message ID:
+// ---
+// id: conv-1
+// status: active
+// metadata: {}
+// tags: []
+// createdAt: '2024-01-15T10:00:00.000Z'
+// updatedAt: '2024-01-15T10:01:00.000Z'
+// messages:
+//   msg-1:
+//     position: 0
+//     createdAt: '2024-01-15T10:00:00.000Z'
+//     metadata: {}
+//     hidden: false
+//   msg-2:
+//     position: 1
+//     createdAt: '2024-01-15T10:01:00.000Z'
+//     metadata: {}
+//     hidden: false
+// ---
+// ### User (msg-1)
+//
+// What is 2 + 2?
+//
+// ### Assistant (msg-2)
+//
+// The answer is 4.
+
+// Parse back with all metadata preserved
+const restored = fromMarkdown(markdown);
+// restored.id === 'conv-1'
+// restored.messages[0].id === 'msg-1'
+```
+
+#### Multi-Modal Content
+
+Both functions handle multi-modal content. Images render as Markdown images, and with metadata enabled, additional properties like `mimeType` are preserved in the YAML frontmatter:
+
+```ts
+conversation = appendMessages(conversation, {
+  role: 'user',
+  content: [
+    { type: 'text', text: 'Describe this:' },
+    { type: 'image', url: 'https://example.com/photo.png', mimeType: 'image/png' },
+  ],
+});
+
+const md = toMarkdown(conversation);
+// Describe this:
+//
+// ![image](https://example.com/photo.png)
+```
+
 ## Plugins
 
 **Conversationalist** supports a plugin system that allows you to transform messages as they are appended to a conversation. Plugins are functions that take a `MessageInput` and return a modified `MessageInput`.
@@ -688,6 +790,7 @@ Svelte 5's runes pair perfectly with **Conversationalist**. You can use the `Con
 | **Modification** | `redactMessageAtPosition`, `replaceSystemMessage`, `collapseSystemMessages`                              |
 | **Context**      | `truncateToTokenLimit`, `getRecentMessages`, `estimateConversationTokens`                                |
 | **Querying**     | `getConversationMessages`, `getMessageByIdentifier`, `computeConversationStatistics`                     |
+| **Conversion**   | `toMarkdown`, `fromMarkdown`, `toChatMessages`, `pairToolCallsWithResults`                               |
 | **History**      | `ConversationHistory`, `bindToConversationHistory`                                                       |
 
 ## Deterministic Environments (Testing)

package/dist/index.d.ts

@@ -9,8 +9,8 @@ export { withEnvironment } from './environment';
 export { createMessage } from './utilities';
 export type { ConversationalistErrorCode } from './errors';
 export { ConversationalistError, createDuplicateIdError, createInvalidInputError, createInvalidPositionError, createInvalidToolReferenceError, createLockedError, createNotFoundError, createSerializationError, createValidationError, } from './errors';
-export type { ToolCallPair } from './utilities';
-export { normalizeContent, pairToolCallsWithResults, toMultiModalArray, } from './utilities';
+export type { ToMarkdownOptions, ToolCallPair } from './utilities';
+export { fromMarkdown, MarkdownParseError, normalizeContent, pairToolCallsWithResults, toMarkdown, toMultiModalArray, } from './utilities';
 export type { ConversationDraft } from './with-conversation';
 export { pipeConversation, withConversation } from './with-conversation';
 export { bindToConversationHistory, ConversationHistory } from './history';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EACV,OAAO,IAAI,eAAe,EAC1B,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,OAAO,EACP,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,+BAA+B,EAC/B,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGxE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EACV,OAAO,IAAI,eAAe,EAC1B,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,OAAO,EACP,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,+BAA+B,EAC/B,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,UAAU,EACV,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGxE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}