tune-sdk 0.3.0 → 0.3.1

package/README.md

@@ -14,6 +14,7 @@ install tune-sdk
 ```bash
 npm install -g tune-sdk
 
+# create ~/.tune folder and install batteries
 tune init
 ```
 
@@ -39,52 +40,15 @@ user:
 ```
 [read more](https://iovdin.github.io/tune/template-language)
 
-
-## Diagram
-
-```mermaid
-flowchart TD 
-
-  subgraph Entry[" "]
-    Editor["VSCode/Neovim/Sublime Text"]
-    CLI["CLI"]
-    App["App"]
-  end
-
-  subgraph Core[" "]
-    MD1["~/.tune/default.ctx.js"]
-    MD2["require('tune-fs')
-require('tune-models')
-"]
-    CTX["tune.makeContext(...middlewares)"]
-    F2R["ctx.file2run(params)"]
-  end
-
-  
-  MD1 --> |cli middlewares| CTX
-  MD2 --> |app middlewares| CTX
-  Editor -->| $ tune rpc | Core
-  CLI --> | $ tune --user hello | Core
-  App --> Core
-  
-  
-  
-  F2R -->|ctx.resolve #40; system.txt #124; shell #124; gpt-5  #41; | CTX
-  CTX -->| #123; type: text #124; tool #124; llm #125; | F2R
-
-  F2R --> |fetch| LLM["https://provider.com/v1/chat/completions"]
-  F2R --> |call| Tool
-```
-
 ## Extend with Middlewares
 Extend Tune with middlewares:
 
-* [tune-fs](https://www.npmjs.com/package/tune-fs) - connect tools & files from local filesystem
-* [tune-models](https://www.npmjs.com/package/tune-models) - connect llm models from Anthropic/OpenAI/Gemini/Openrouter/Mistral/Groq
-* [tune-basic-toolset](https://www.npmjs.com/package/tune-basic-toolset) - basic tools like read file, write file, shell etc.
-* [tune-s3](https://www.npmjs.com/package/tune-s3) - read/write files from s3
-* [tune-mcp](https://www.npmjs.com/package/tune-mcp) - connect tools from mcp servers
-* [maik](https://www.npmjs.com/package/@iovdin/maik) - fetch all you emails, and index them into sqlite database
+* [tune-fs](https://github.com/iovdin/tune-fs) - connect tools & files from local filesystem
+* [tune-models](https://github.com/iovdin/tune-models) - connect llm models from Anthropic/OpenAI/Gemini/Openrouter/Mistral/Groq
+* [tune-basic-toolset](https://github.com/iovdin/tune-basic-toolset) - basic tools like read file, write file, shell etc.
+* [tune-s3](https://github.com/iovdin/tune-s3) - read/write files from s3
+* [tune-mcp](https://github.com/iovdin/tune-mcp) - connect tools from mcp servers
+* [maik](https://github.com/iovdin/maik) - fetch all you emails, and index them into sqlite database
 
 
 For example:
@@ -155,27 +119,104 @@ tune --set test="hello" --user "@test" --system "You are echo you print everytht
 ## Javascript SDK
 `npm install tune-sdk`
 
-```javascript
-const tune = require("tune-sdk");
-const sonnet = require("./sonnet.llm.js");
+Tune core is middleware-based. A context resolves `@name` references into nodes like `text`, `tool`, `llm`, and `processor`.
 
-require('dotenv').config();
+```javascript
+const tune = require("tune-sdk")
 
 async function main() {
-  const ctx = tune.makeContext({
-    echo: "You are echo, you print everything back",
-    OPENROUTER_KEY: process.env.OPENROUTER_KEY,
-    "default": {
-      type: "llm",
-      exec: sonnet
+  const ctx = tune.makeContext()
+
+  ctx.use(async function middleware(name) {
+    if (name === "file.txt") {
+      return {
+        type: "text",
+        name: "file.txt",
+        read: async () => fs.readFileSync("file.txt", "utf8")
+      }
+    }
+
+    if (name === "readfile") {
+      return {
+        type: "tool",
+        name: "readfile",
+        schema: {
+          type: "object",
+          properties: {
+            filename: { type: "string" }
+          }
+        },
+        exec: async ({ filename }) => fs.readFileSync(filename, "utf8")
+      }
+    }
+
+    if (name === "gpt-5") {
+      return {
+        type: "llm",
+        name: "gpt-5",
+        exec: async (payload) => ({
+          url: "https://api.openai.com/v1/chat/completions",
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${process.env.OPENAI_KEY}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            model: "gpt-5",
+            ...payload
+          })
+        })
+      }
+    }
+
+    if (name === "tail") {
+      return {
+        type: "processor",
+        name: "tail",
+        exec: async (node, args) => {
+          if (!node) return
+          if (node.type !== "text") throw Error("tail can only modify text nodes")
+          return {
+            ...node,
+            read: async () => {
+              const content = await node.read()
+              const n = parseInt(args.trim(), 10) || 20
+              return content.split("\n").slice(-n).join("\n")
+            }
+          }
+        }
+      }
     }
   })
 
-  const text = "s: @echo\nu: hello world";
-  const messages = await tune.text2run(text, ctx)
-  console.log(tune.msg2text(messages))
-  // a: hello world
+  const content = await ctx.file2run({
+    system: "@gpt-5 @readfile",
+    user: "can you read file.txt?",
+    stream: false,
+    response: "content"
+  })
+
+  console.log(content)
 }
+
 main()
 ```
+
 [read more](https://iovdin.github.io/tune/api) about javascript sdk
+
+## Help / Manual
+
+You can access tune manuals and available middlewares manuals from 
+
+```chat
+system:
+@man include all manuals for all connected packages
+@man/ - list all the manuals, like list directory
+@man/tune - get manual for tune core package 
+@man/tune-basic-toolset - get manual for tune-basic-tool set package
+
+tool_call: rf { "filename": "man/tune-basic-toolset"}
+tool_result:
+@man/tune-basic-toolset
+
+```

package/config/default.ctx.js

@@ -1,5 +1,6 @@
 const path = require('path')
 
+const man = require("tune-sdk/man");
 const models = require("tune-models")
 const basics = require("tune-basic-toolset")
 const tunefs = require("tune-fs")
@@ -11,6 +12,7 @@ if (process.env.TUNE_PATH) {
 }
 
 module.exports = [
+  man(),
   current(),
   basics(),
   tunefs({ paths: dirs, makeSchema: true }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tune-sdk",
-  "version": "0.3.0",
-  "description": "tune - LLM chat in text file",
+  "version": "0.3.1",
+  "description": "chat with llm in a text file. core package",
   "main": "dist/tune.js",
   "module": "dist/tune.mjs",
   "bin": {
@@ -21,6 +21,9 @@
     },
     "./contextws": {
       "require": "./src/contextws.js"
+    },
+    "./man": {
+      "require": "./src/man.js"
     }
   },
   "keywords": [

package/src/man.js

@@ -0,0 +1,117 @@
+const fs = require("fs")
+const path = require("path")
+// all the registered manuals
+// { name, description, filename/content } 
+
+let mans = [
+] 
+
+/*
+  @man include all manuals for all packages included
+  @man/ - list all the manuals, like list directory
+  @man/tune - get manual for tune core package 
+  @man/tune-basic-toolset - get manual for tune-basic-tool set package
+
+  TODO:
+  @man/tune/js-api - lis
+  @man/tune/agents - lis
+*/
+
+function read({ filename, content }) {
+  if (content) {
+    return content
+  }
+  if (!fs.existsSync(filename)) {
+    return `file ${filename} not found`
+  }
+  return fs.readFileSync(filename)
+}
+
+module.exports = ({ mount } = {}) => async (name, { type }) => {
+  if ((type || "any") !== 'any' && type !== 'text' ) {
+    return
+  }
+  mount ||= "man"
+
+  // supported only with mount
+  if (!mount) {
+    return 
+  }
+
+  // @man include all the manuals
+  if (name === mount) {
+    return {
+      type: "text",
+      name,
+      read: async () => mans.map(man => `<${man.name}>\n ${read(man)} \n</${man.name}>`).join("\n")
+    }
+  }
+
+  if (!name.startsWith(mount + '/')) {
+    return 
+  }
+
+  // @man/ - list all the manuals to include
+  if (name === mount + '/') {
+    return {
+      type: "text",
+      name,
+      read: async () => mans.map(man => `${man.name} - ${man.description}`).join("\n")
+    }
+  }
+
+
+  // @man/tune - get manual for tune core package 
+  // @man/tune-basic-toolset - get manual for tune-basic-tool set package
+  
+  const actualName = name.slice(mount.length + 1);
+
+  const man = mans.find(man => man.name === actualName);
+  if (!man) return
+
+  return {
+    type: "text",
+    name,
+    read: async() => read(man.filename)
+  }
+}
+
+const addManual = (dirname) => {
+  let package = path.resolve(dirname, "package.json");
+  if (!fs.existsSync(package)){
+    dirname = path.resolve(dirname, "..")
+    package = path.resolve(dirname, "package.json");
+  }
+
+  if (!fs.existsSync(package)){
+    throw Error(`cant make manual ${package} not found`);
+  }
+
+  const { name, version, description } = JSON.parse(fs.readFileSync(package, "utf8"));
+
+  const newMans = mans.filter(man => man.name !== name)
+
+  const filename = path.resolve(dirname, "README.md")
+
+  newMans.push({name, description, filename})
+  mans = newMans
+}
+
+addManual(__dirname)
+/*
+const addManual = ({name, description, content, filename}) => {
+  const  = params;
+
+  const newMans = mans.filter(man => man.name !== name)
+  if (!name) {
+    throw Error(`name is not set for manual`)
+  }
+  if (!content && !filename) {
+    throw Error(`neither content nor filename is set for '${name}' manual`)
+  }
+
+  newMans.push({name, description, content, filename})
+}
+*/
+
+module.exports.addManual = addManual;