llm-mar 1.0.7 → 1.0.8

package/README.md

@@ -4,6 +4,13 @@
 
 LLM-MAR (Multi Agent Reasoning) is a compact CLI that creates LLM agents, lets them debate, answers questions, and builds workflows.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [YAML Structure](#yaml-structure)
+
 ## Installation
 
 ### Option 1: Install from npm (Recommended)
@@ -30,6 +37,74 @@ npm install -g llm-mar
    export OPENAI_API_KEY=your_api_key_here
    ```
 
+## Quick Start
+
+Get started with LLM-MAR in minutes! Create intelligent agents, form teams, and orchestrate debates—all through simple YAML configurations.
+
+### 1. Create Your First Agent
+
+Let's create an AI assistant specialized in creative writing:
+
+```bash
+llm-mar create agent writer --model gpt-4 --goal "To write engaging stories" --role "Creative Writer" --system-prompt "You are a talented fiction writer with a vivid imagination." --instructions "Use descriptive language,Build suspense,End with a twist" --output text
+```
+
+This generates a YAML configuration file that defines your agent's personality and capabilities.
+
+### 2. See the YAML Structure
+
+The command above creates `default/writer.yaml` with this structure:
+
+```yaml
+version: '1.0'
+kind: Agent
+metadata:
+  name: writer
+  description: An agent named writer
+spec:
+  id: writer
+  model: gpt-4
+  goal: To write engaging stories
+  role: Creative Writer
+  system_prompt: You are a talented fiction writer with a vivid imagination.
+  instructions:
+    - Use descriptive language
+    - Build suspense
+    - End with a twist
+  output: text
+```
+
+**Key Components:**
+- **metadata**: Basic info and description
+- **spec**: The agent's configuration including model, role, and behavior
+- **instructions**: List of guidelines for the AI's responses
+
+### 3. Run Your Agent
+
+Now let's use the agent to generate a story:
+
+```bash
+llm-mar run default/writer.yaml --input "Write a short story about a mysterious old clock in an antique shop."
+```
+
+The agent will respond with a creative story based on its configuration!
+
+### 4. Build a Team
+
+Combine multiple agents for collaborative tasks:
+
+```bash
+llm-mar create team story_team --agents "default/writer.yaml,default/editor.yaml" --output text
+```
+
+### 5. Set Up a Debate
+
+Create engaging debates between agents:
+
+```bash
+llm-mar create debate tech_debate --agents "default/optimist.yaml,default/pessimist.yaml" --judges "default/judge.yaml" --input "Will AI replace human jobs?" --output text
+```
+
 ## Usage
 
 After installation, use the `llm-mar` command (or `npx llm-mar` if installed locally).
@@ -78,4 +153,60 @@ llm-mar run default/debate1.yaml
 
 ## YAML Structure
 
-See [docs/yaml-structure-guide.md](docs/yaml-structure-guide.md) for details on YAML file formats.
+LLM-MAR uses YAML files to define agents, teams, and debates. Here's a quick overview of the structure:
+
+### Agent YAML
+
+```yaml
+version: '1.0'
+kind: Agent
+metadata:
+  name: Scientist
+  description: A scientific analysis agent
+spec:
+  id: scientist
+  model: gpt-4
+  goal: To provide scientific explanations
+  role: Research Scientist
+  system_prompt: You are an expert scientist...
+  instructions:
+    - Use evidence-based reasoning
+    - Explain complex concepts simply
+  output: text
+```
+
+### Team YAML
+
+```yaml
+version: '1.0'
+kind: Team
+metadata:
+  name: Research Team
+  description: Collaborative research team
+spec:
+  agents:
+    - default/scientist.yaml
+    - default/analyst.yaml
+  output: text
+```
+
+### Debate YAML
+
+```yaml
+version: '1.0'
+kind: Debate
+metadata:
+  name: Ethics Debate
+  description: Debate on AI ethics
+spec:
+  method: majority_vote
+  input: Should AI have rights?
+  judges:
+    - default/judge.yaml
+  agents:
+    - default/pro.yaml
+    - default/con.yaml
+  output: text
+```
+
+For detailed configuration options and advanced features, see [docs/yaml-structure-guide.md](docs/yaml-structure-guide.md).

package/commands/create.js

@@ -13,8 +13,10 @@ function setupCreate(program) {
     .option('--system-prompt <prompt>', 'system prompt', 'You are a helpful assistant.')
     .option('--instructions <instructions>', 'instructions as comma-separated list', 'Think step by step,Answer clearly and concisely')
     .option('--output <format>', 'output format', 'text')
+    .option('--output-file <path>', 'output file path')
     .action((name, options) => {
       const instructions = options.instructions.split(',').map(s => s.trim());
+      const outputFile = options.outputFile || `default/${name}.yaml`;
       const config = {
         version: '1.0',
         kind: 'Agent',
@@ -33,8 +35,8 @@ function setupCreate(program) {
         }
       };
       const yamlStr = yaml.dump(config);
-      fs.writeFileSync(`default/${name}.yaml`, yamlStr);
-      console.log(`Agent YAML created: default/${name}.yaml`);
+      fs.writeFileSync(outputFile, yamlStr);
+      console.log(`Agent YAML created: ${outputFile}`);
     });
 
   createCmd
@@ -42,12 +44,14 @@ function setupCreate(program) {
     .description('create a new team YAML')
     .option('--agents <agents>', 'comma-separated list of agent YAML file paths')
     .option('--output <format>', 'output format', 'text')
+    .option('--output-file <path>', 'output file path')
     .action((name, options) => {
       if (!options.agents) {
         console.error('Error: --agents is required');
         process.exit(1);
       }
       const agentFiles = options.agents.split(',').map(s => s.trim());
+      const outputFile = options.outputFile || `default/${name}.yaml`;
       const config = {
         version: '1.0',
         kind: 'Team',
@@ -61,8 +65,8 @@ function setupCreate(program) {
         }
       };
       const yamlStr = yaml.dump(config);
-      fs.writeFileSync(`default/${name}.yaml`, yamlStr);
-      console.log(`Team YAML created: default/${name}.yaml`);
+      fs.writeFileSync(outputFile, yamlStr);
+      console.log(`Team YAML created: ${outputFile}`);
     });
 
   createCmd
@@ -73,6 +77,7 @@ function setupCreate(program) {
     .option('--judges <judges>', 'comma-separated list of judge agent YAML file paths')
     .option('--input <input>', 'debate input topic', 'A topic to debate')
     .option('--output <format>', 'output format', 'text')
+    .option('--output-file <path>', 'output file path')
     .action((name, options) => {
       if (!options.agents || !options.judges) {
         console.error('Error: --agents and --judges are required');
@@ -80,6 +85,7 @@ function setupCreate(program) {
       }
       const agents = options.agents.split(',').map(s => s.trim());
       const judges = options.judges.split(',').map(s => s.trim());
+      const outputFile = options.outputFile || `default/${name}.yaml`;
       const config = {
         version: '1.0',
         kind: 'Debate',
@@ -96,8 +102,8 @@ function setupCreate(program) {
         }
       };
       const yamlStr = yaml.dump(config);
-      fs.writeFileSync(`default/${name}.yaml`, yamlStr);
-      console.log(`Debate YAML created: default/${name}.yaml`);
+      fs.writeFileSync(outputFile, yamlStr);
+      console.log(`Debate YAML created: ${outputFile}`);
     });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-mar",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "LLM-MAR is a compact CLI that creates LLM agents, lets them debate, answers questions, and builds workflows.",
   "main": "index.js",
   "bin": {
@@ -14,7 +14,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/renatojuniorrs/llm-mar.git"
+    "url": "git+https://github.com/llm-mar/llm-mar.git"
   },
   "publishConfig": {
     "access": "public",