deepclause-sdk 0.0.1 → 0.0.2

package/README.md

@@ -1,15 +1,16 @@
-# DeepClause
+# DeepClause CLI and SDK
 
-Compile markdown specs into Prolog agents. Guaranteed execution semantics for agentic workflows.
+Compile markdown specs into executable logic programs. Guaranteed execution semantics for agentic workflows.
 
 ## What This Is
 
 AI skills and tools are everywhere—but most are just prompts. When a prompt fails, you tweak it. When you need branching logic, you write wrapper code. When you want retry behavior, you build it yourself.
 
-DeepClause takes a different approach: **compile task descriptions into Prolog-based programs** that handle control flow, error recovery, and tool orchestration automatically.
+DeepClause takes a different approach: **compile task descriptions into DML programs**—a Prolog-based language that handles control flow, error recovery, and tool orchestration automatically.
+
 
 ```
-Markdown description  →  compile  →  Logic program (DML)  →  run  →  Output
+Markdown description  →  compile  →  Logic program  →  run  →  Output
 ```
 
 ## Sandboxed by Default
@@ -19,7 +20,7 @@ Everything runs in WebAssembly—no native code execution, no container setup re
 - **[AgentVM](https://github.com/deepclause/agentvm)**: A lightweight WASM-based Linux environment for shell commands, file operations, and Python/Node execution
 - **Prolog runtime**: The logic engine itself runs in WASM (SWI-Prolog compiled to WebAssembly)
 
-This means that DML tools and agents can execute arbitrary shell commands without escaping to your host system.
+This means that DML tools and agents can execute arbitrary shell commands with minimal chance of escaping to your host system.
 
 ## Beyond Markdown: Why Logic Programming?
 
@@ -122,12 +123,12 @@ deepclause run .deepclause/tools/explain.dml "function fib(n) { return n < 2 ? n
 
 ## Use Cases
 
-### Coding agents building their own tools
+### Reliable tools for coding agents
 
-AI coding assistants can compile task descriptions on the fly:
+Give your AI coding assistant more deterministic, inspectable tools instead of hoping prompts work:
 
 ```bash
-# Agent writes a task description
+# Define a tool the agent can use
 cat > .deepclause/tools/api-docs.md << 'EOF'
 # API Documentation Lookup
 Search for API documentation and summarize usage patterns.
@@ -143,14 +144,14 @@ Search for API documentation and summarize usage patterns.
 - Summarize usage patterns and examples
 EOF
 
-# Compile it
+# Compile it once
 deepclause compile .deepclause/tools/api-docs.md
 
-# Use it whenever needed
+# Now your coding agent can run it reliably
 deepclause run .deepclause/tools/api-docs.dml "Stripe PaymentIntent"
 ```
 
-The compiled `.dml` files are deterministic—same input, same execution path. The agent builds up a library of reliable tools.
+The compiled `.dml` files execute the same way every time—no prompt variance, no skipped steps. Build up a library of tools your agent can trust.
 
 ### Automation pipelines
 
@@ -234,6 +235,8 @@ Skills can use these built-in tools:
 
 Configure tools in `.deepclause/config.json`.
 
+MCP support is on the roadmap.
+
 ## CLI Reference
 
 ```bash
@@ -250,7 +253,7 @@ deepclause set-model <model>       # Change default model
 
 ```bash
 deepclause run skill.dml "input" \
-  --model google/gemini-2.5-flash \   # Override model
+  --model google/gemini-2.5-flash \   # Override model (e.g. use cheaper model for execution, SOTA model for planning/compilation)
   --stream \                           # Stream output
   --verbose \                          # Show tool calls
   --workspace ./data                   # Set working directory
@@ -327,7 +330,7 @@ agent_main(Question) :-
     answer("Done").
 ```
 
-If `validate_answer` fails, Prolog backtracks and tries the second clause. No explicit if/else needed.
+If `validate_answer` fails, Prolog backtracks and tries the second clause. No explicit if/else needed. Backtracking resets the execution state (including LLM context) to the original choice point!
 
 ### Recursion: Processing Lists
 
@@ -402,18 +405,6 @@ agent_main(Topic) :-
     answer(Final).
 ```
 
-### When to Use DML Directly
-
-| Use Markdown When... | Use DML When... |
-|---------------------|-----------------|
-| Linear, single-task workflow | Complex control flow needed |
-| No error handling needed | Need retry/fallback logic |
-| Simple input → output | Processing collections |
-| Quick prototyping | Production reliability |
-| Non-programmers writing skills | Fine-grained tool control |
-
-Start with Markdown. Graduate to DML when you need the power.
-
 ## Using as a Library
 
 Embed DeepClause in your own applications:

package/dist/cli/compile.d.ts

@@ -1,7 +1,8 @@
 /**
  * DeepClause CLI - Compilation Module
  *
- * Compiles Markdown task descriptions to DML programs using LLM.
+ * Compiles Markdown task descriptions to DML programs using an agentic loop
+ * with LLM generation and Prolog validation.
  */
 import { type Provider } from './config.js';
 export interface CompileOptions {
@@ -10,6 +11,9 @@ export interface CompileOptions {
     model?: string;
     provider?: Provider;
     temperature?: number;
+    maxAttempts?: number;
+    verbose?: boolean;
+    stream?: boolean;
 }
 export interface CompileResult {
     output: string;
@@ -18,6 +22,8 @@ export interface CompileResult {
     valid: boolean;
     dml?: string;
     meta?: MetaFile;
+    explanation?: string;
+    attempts?: number;
 }
 export interface CompileAllResult {
     compiled: number;
@@ -53,7 +59,7 @@ export interface MetaFile {
     }>;
 }
 /**
- * Compile a Markdown task description to DML
+ * Compile a Markdown task description to DML using an agentic loop
  */
 export declare function compile(sourcePath: string, outputDir: string, options?: CompileOptions): Promise<CompileResult>;
 /**
@@ -62,7 +68,6 @@ export declare function compile(sourcePath: string, outputDir: string, options?:
 export declare function compileAll(sourceDir: string, outputDir: string, options?: CompileOptions): Promise<CompileAllResult>;
 /**
  * Extract tool dependencies from DML code
- * Only extracts external tools called via exec/2
  */
 export declare function extractToolDependencies(dml: string): string[];
 /**
@@ -75,11 +80,11 @@ export declare function extractParameters(dml: string): Array<{
     required?: boolean;
 }>;
 /**
- * Extract description from markdown (first heading or paragraph)
+ * Extract description from markdown
  */
 export declare function extractDescription(markdown: string): string;
 /**
- * Basic DML syntax validation
+ * Basic DML syntax validation (exported for backwards compatibility)
  */
 export declare function validateDMLSyntax(dml: string): {
     valid: boolean;

package/dist/cli/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQrE,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CACJ;AAMD;;GAEG;AACH,wBAAsB,OAAO,CAC3B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAmHxB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B;AAoFD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAW7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAwBlI;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmB3D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA+CnF"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"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"}