conversationalist 0.0.3 → 0.0.4

package/dist/utilities.d.ts

@@ -1,5 +1,5 @@
 import type { MultiModalContent } from '@lasercat/homogenaize';
-import type { Message, MessageJSON, ToolCall, ToolResult } from './types';
+import type { Conversation, Message, MessageJSON, ToolCall, ToolResult } from './types';
 /**
  * Represents a paired tool call with its optional result.
  */
@@ -76,4 +76,78 @@ export declare function messageHasImages(message: Message): boolean;
  * Images are rendered as markdown image syntax.
  */
 export declare function messageToString(message: Message): string;
+/**
+ * Options for the toMarkdown function.
+ */
+export interface ToMarkdownOptions {
+    /**
+     * Whether to include metadata (YAML frontmatter with message metadata)
+     * for lossless round-trip conversion.
+     *
+     * When `true`:
+     * - Includes YAML frontmatter with conversation and message metadata
+     * - Headers include message ID: `### Role (msg-id)`
+     * - Supports lossless round-trip via `fromMarkdown`
+     *
+     * When `false` (default):
+     * - Outputs clean, human-readable markdown
+     * - Headers only include role: `### Role`
+     *
+     * @default false
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * Converts a conversation to a Markdown string representation.
+ *
+ * By default, outputs clean, human-readable markdown with:
+ * - Each message with a header containing only the role: `### Role`
+ * - Message content rendered as markdown
+ *
+ * When `options.includeMetadata` is `true`, outputs markdown with full metadata
+ * for lossless round-trip conversion:
+ * - YAML frontmatter with conversation metadata and all message metadata keyed by message ID
+ * - Headers include message ID: `### Role (msg-id)`
+ * - Full content array preserved for multi-modal messages
+ *
+ * For multi-modal content:
+ * - Text parts are appended in order
+ * - Image parts are rendered as `![alt]({url})` on their own line
+ *
+ * @param conversation - The conversation to convert
+ * @param options - Options for markdown output
+ * @returns A Markdown string representation of the conversation
+ */
+export declare function toMarkdown(conversation: Conversation, options?: ToMarkdownOptions): string;
+/**
+ * Error thrown when markdown parsing fails.
+ */
+export declare class MarkdownParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parses a Markdown string back into a Conversation object.
+ *
+ * This is the inverse of `toMarkdown` and supports both:
+ * - Lossless round-trip conversion when markdown includes metadata
+ *   (generated by `toMarkdown` with `includeMetadata: true`)
+ * - Best-effort parsing of simple markdown without metadata
+ *   (generated by `toMarkdown` with `includeMetadata: false` or hand-written)
+ *
+ * When metadata is present:
+ * - YAML frontmatter provides conversation and message metadata
+ * - Headers include message ID: `### Role (msg-id)`
+ * - Full fidelity is preserved
+ *
+ * When metadata is absent:
+ * - Conversation ID and timestamps are generated
+ * - Message IDs are generated, positions are inferred from order
+ * - Content is parsed from markdown body
+ * - Defaults: status='active', hidden=false, empty metadata/tags
+ *
+ * @param markdown - The markdown string to parse
+ * @returns A Conversation object
+ * @throws {MarkdownParseError} If the markdown format is invalid (e.g., unknown role)
+ */
+export declare function fromMarkdown(markdown: string): Conversation;
 //# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,6CAA6C;IAC7C,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAC/B,YAAY,EAAE,CAsBhB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EACpE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,GACN,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAoBzD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GACtD,iBAAiB,EAAE,CAGrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GACzD,MAAM,GAAG,iBAAiB,EAAE,GAAG,SAAS,CAI1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAc3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAO/E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,MAAe,GAAG,MAAM,CAM7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CASxD"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,OAAO,KAAK,EACV,YAAY,EAEZ,OAAO,EACP,WAAW,EAGX,QAAQ,EACR,UAAU,EACX,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,6CAA6C;IAC7C,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAC/B,YAAY,EAAE,CAsBhB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EACpE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,GACN,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAoBzD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GACtD,iBAAiB,EAAE,CAGrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GACzD,MAAM,GAAG,iBAAiB,EAAE,GAAG,SAAS,CAI1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAc3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAO/E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,MAAe,GAAG,MAAM,CAM7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CASxD;AA2ED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAQR;AAqFD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAW3D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conversationalist",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A TypeScript library for managing AI conversation state",
   "keywords": [
     "conversation",
@@ -81,7 +81,8 @@
     ]
   },
   "dependencies": {
-    "change-case": "^5.4.4"
+    "change-case": "^5.4.4",
+    "gray-matter": "^4.0.3"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.71.2",