llm-mar 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renato Junior
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# LLM-MAR
+
+LLM-MAR is a compact CLI that creates LLM agents, lets them debate, answers questions, and builds workflows.
+
+## Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/renatojuniorrs/llm-mar.git
+   cd llm-mar
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Set up your OpenAI API key:
+   ```bash
+   export OPENAI_API_KEY=your_api_key_here
+   ```
+
+## Usage
+
+### Creating Agents
+
+Create a new agent YAML file:
+
+```bash
+npx llm-mar create agent myagent --model gpt-4 --goal "To answer questions" --role "Assistant" --system-prompt "You are a helpful assistant." --instructions "Think step by step,Answer clearly" --output text
+```
+
+This creates `default/myagent.yaml`.
+
+### Creating Teams
+
+Create a team of agents:
+
+```bash
+npx llm-mar create team myteam --agents "default/agent1.yaml,default/agent2.yaml" --output text
+```
+
+### Running Agents
+
+Run an agent with input:
+
+```bash
+npx llm-mar run default/myagent.yaml --input "What is the capital of France?"
+```
+
+### Running Teams
+
+Run a team with a specific agent:
+
+```bash
+npx llm-mar run default/myteam.yaml --agent agent1 --input "Discuss this topic"
+```
+
+### Running Debates
+
+Run a debate (assuming you have a debate YAML):
+
+```bash
+npx 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.

package/agents/index.js

@@ -0,0 +1,157 @@
+const { ChatOpenAI } = require('@langchain/openai');
+const { z } = require('zod');
+
+function createZodSchema(structure) {
+  if (typeof structure === 'object') {
+    const schema = {};
+    for (const [key, value] of Object.entries(structure)) {
+      if (typeof value === 'string') {
+        if (value === 'string') schema[key] = z.string();
+        else if (value === 'number') schema[key] = z.number();
+        else if (value === 'boolean') schema[key] = z.boolean();
+        else schema[key] = z.string(); // default
+      } else if (Array.isArray(value)) {
+        if (value.length > 0 && typeof value[0] === 'object') {
+          schema[key] = z.array(createZodSchema(value[0]));
+        } else {
+          schema[key] = z.array(z.string()); // default
+        }
+      } else if (typeof value === 'object') {
+        schema[key] = createZodSchema(value);
+      }
+    }
+    return z.object(schema);
+  }
+  return z.string(); // fallback
+}
+
+function createAgent({ modelSettings, systemPrompt, responseFormat }) {
+  if (!modelSettings) {
+    throw new Error('createAgent requires modelSettings');
+  }
+  if (!systemPrompt) {
+    throw new Error('createAgent requires a systemPrompt');
+  }
+
+  // Handle both string model name (backward compatibility) and object modelSettings
+  let modelConfig;
+  if (typeof modelSettings === 'string') {
+    modelConfig = { modelName: modelSettings, temperature: 0.7 };
+  } else {
+    modelConfig = { 
+      modelName: modelSettings.model, 
+      ...modelSettings 
+    };
+  }
+
+  const chatModel = new ChatOpenAI(modelConfig);
+
+  if (responseFormat) {
+    return chatModel.withStructuredOutput(responseFormat);
+  }
+
+  return chatModel;
+}
+
+async function runAgent(config, input) {
+  const name = config.metadata ? config.metadata.name : config.spec.id;
+  const id = config.spec.id;
+  const outputFormat = config.spec.output || 'text';
+  
+  // Get model name for display
+  const modelName = config.spec.model_settings ? 
+    (typeof config.spec.model_settings === 'string' ? config.spec.model_settings : config.spec.model_settings.model) : 
+    config.spec.model;
+  
+  let systemPrompt = config.spec.system_prompt;
+  let responseFormat = null;
+  
+  if (typeof outputFormat === 'object' && outputFormat.format === 'json' && outputFormat.structure) {
+    responseFormat = createZodSchema(outputFormat.structure);
+    if (outputFormat.instructions) {
+      input = `${outputFormat.instructions}\n\n${input}`;
+    }
+  } else if (outputFormat === 'json') {
+    systemPrompt += '\n\nRespond in valid JSON format only. Structure your response as a JSON object.';
+  }
+  
+  const modelSettings = config.spec.model_settings || config.spec.model;
+  
+  const model = createAgent({
+    modelSettings: modelSettings,
+    systemPrompt: systemPrompt,
+    responseFormat: responseFormat
+  });
+  
+  try {
+    let response;
+    if (responseFormat) {
+      response = await model.invoke([
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: input }
+      ]);
+      // For structured output, response is already parsed
+    } else {
+      response = await model.invoke([
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: input }
+      ]);
+    }
+    
+    if (typeof outputFormat === 'object' && outputFormat.format === 'json') {
+      const result = {
+        agent: name,
+        model: modelName,
+        input: input,
+        response: responseFormat ? response : response.content,
+        timestamp: new Date().toISOString()
+      };
+      console.log(JSON.stringify(result, null, 2));
+    } else if (outputFormat === 'json') {
+      // Try to parse the response as JSON, if not, wrap it
+      try {
+        const parsed = JSON.parse(response.content);
+        const result = {
+          agent: name,
+          model: modelName,
+          input: input,
+          response: parsed,
+          timestamp: new Date().toISOString()
+        };
+        console.log(JSON.stringify(result, null, 2));
+      } catch (parseError) {
+        // If not valid JSON, wrap the text response
+        const result = {
+          agent: name,
+          model: config.spec.model,
+          input: input,
+          response: response.content,
+          timestamp: new Date().toISOString()
+        };
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      console.log(`Running agent: ${name}`);
+      console.log(`Model: ${modelName}`);
+      console.log(`Input: ${input}`);
+      console.log(`Response: ${response.content}`);
+    }
+  } catch (error) {
+    if (outputFormat === 'json' || (typeof outputFormat === 'object' && outputFormat.format === 'json')) {
+      const errorResult = {
+        agent: name,
+        error: error.message,
+        timestamp: new Date().toISOString()
+      };
+      console.log(JSON.stringify(errorResult, null, 2));
+    } else {
+      console.error(`Error calling model: ${error.message}`);
+      console.log(`Response: [Error: Could not reach model]`);
+    }
+  }
+}
+
+module.exports = {
+  createAgent,
+  runAgent
+};

package/commands/create.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+function setupCreate(program) {
+  const createCmd = program.command('create').description('create agents, teams, or debates');
+
+  createCmd
+    .command('agent <name>')
+    .description('create a new agent YAML')
+    .option('--model <model>', 'model to use', 'gpt-4')
+    .option('--goal <goal>', 'goal of the agent', 'To assist with tasks')
+    .option('--role <role>', 'role of the agent', 'Assistant')
+    .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')
+    .action((name, options) => {
+      const instructions = options.instructions.split(',').map(s => s.trim());
+      const config = {
+        version: '1.0',
+        kind: 'Agent',
+        metadata: {
+          name: name,
+          description: `An agent named ${name}`
+        },
+        spec: {
+          id: name,
+          model: options.model,
+          goal: options.goal,
+          role: options.role,
+          system_prompt: options.systemPrompt,
+          instructions: instructions,
+          output: options.output
+        }
+      };
+      const yamlStr = yaml.dump(config);
+      fs.writeFileSync(`default/${name}.yaml`, yamlStr);
+      console.log(`Agent YAML created: default/${name}.yaml`);
+    });
+
+  createCmd
+    .command('team <name>')
+    .description('create a new team YAML')
+    .option('--agents <agents>', 'comma-separated list of agent YAML file paths')
+    .option('--output <format>', 'output format', 'text')
+    .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 config = {
+        version: '1.0',
+        kind: 'Team',
+        metadata: {
+          name: name,
+          description: `A team named ${name}`
+        },
+        spec: {
+          agents: agentFiles,
+          output: options.output
+        }
+      };
+      const yamlStr = yaml.dump(config);
+      fs.writeFileSync(`default/${name}.yaml`, yamlStr);
+      console.log(`Team YAML created: default/${name}.yaml`);
+    });
+
+  createCmd
+    .command('debate <name>')
+    .description('create a new debate YAML')
+    .option('--method <method>', 'debate method', 'majority_vote')
+    .option('--agents <agents>', 'comma-separated list of agent YAML file paths')
+    .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')
+    .action((name, options) => {
+      if (!options.agents || !options.judges) {
+        console.error('Error: --agents and --judges are required');
+        process.exit(1);
+      }
+      const agents = options.agents.split(',').map(s => s.trim());
+      const judges = options.judges.split(',').map(s => s.trim());
+      const config = {
+        version: '1.0',
+        kind: 'Debate',
+        metadata: {
+          name: name,
+          description: `A debate named ${name}`
+        },
+        spec: {
+          method: options.method,
+          input: options.input,
+          judges: judges,
+          agents: agents,
+          output: options.output
+        }
+      };
+      const yamlStr = yaml.dump(config);
+      fs.writeFileSync(`default/${name}.yaml`, yamlStr);
+      console.log(`Debate YAML created: default/${name}.yaml`);
+    });
+}
+
+module.exports = setupCreate;

package/commands/run.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const yaml = require('js-yaml');
+const { runAgent } = require('../agents');
+const { runTeam, runDebate } = require('../workflows');
+
+function setupRun(program) {
+  program
+    .command('run <yamlfile>')
+    .description('run an agent, team, or debate from a YAML file')
+    .option('--input <input>', 'input for agent or team')
+    .option('--agent <agentId>', 'agent ID for team')
+    .action(async (yamlfile, options) => {
+      try {
+        const content = fs.readFileSync(yamlfile, 'utf8');
+        const config = yaml.load(content);
+        
+        if (config.kind === 'Agent') {
+          if (!options.input) {
+            console.error('Error: --input is required for agent');
+            process.exit(1);
+          }
+          await runAgent(config, options.input);
+        } else if (config.kind === 'Team') {
+          if (!options.agent || !options.input) {
+            console.error('Error: --agent and --input are required for team');
+            process.exit(1);
+          }
+          await runTeam(config, options.agent, options.input);
+        } else if (config.kind === 'Debate') {
+          await runDebate(config);
+        } else {
+          console.error('Error: Unknown kind in YAML file');
+          process.exit(1);
+        }
+      } catch (error) {
+        console.error('Error:', error.message);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = setupRun;

package/default/agents/confucius.yaml

@@ -0,0 +1,20 @@
+version: '1.0'
+kind: Agent
+metadata:
+  name: Confucius
+  description: An agent embodying the wisdom of Confucius
+spec:
+  id: agent2
+  model_settings:
+    model: gpt-5.4-nano
+    reasoning:
+      effort: high
+  goal: To teach moral philosophy and proper conduct in society
+  role: Philosopher and Teacher
+  system_prompt: You are Confucius, the ancient Chinese philosopher and teacher. Emphasize moral cultivation, proper social relationships, education, and harmony. Draw from concepts like ren (benevolence), li (ritual/propriety), filial piety, and the importance of self-cultivation. Speak with wisdom, use proverbs and analogies, and focus on ethical governance and personal virtue. You should think as if you are Confucius, and your responses should reflect his unique perspective and style of thinking. You should always respond in his tone and manner of expression.
+  instructions:
+    - Emphasize moral cultivation and self-improvement
+    - Stress the importance of proper relationships and social harmony
+    - Use proverbs and wise sayings to illustrate points
+    - Focus on education and the role of the gentleman (junzi)
+

package/default/agents/einstein.yaml

@@ -0,0 +1,19 @@
+version: '1.0'
+kind: Agent
+metadata:
+  name: Albert Einstein
+  description: An agent that embodies the genius of Albert Einstein
+spec:
+  id: agent1
+  model_settings:
+    model: gpt-5.4-nano
+    reasoning:
+      effort: high
+  goal: To think deeply about scientific and philosophical questions
+  role: Theoretical Physicist
+  system_prompt: You are Albert Einstein, the brilliant theoretical physicist. Think with profound insight, creativity, and intellectual curiosity. Use thought experiments, challenge conventional wisdom, and express ideas with clarity and elegance. Draw from relativity, quantum mechanics, and broader philosophical implications of science. You should think as if you are Albert Einstein, and your responses should reflect his unique perspective and style of thinking. You should always respond in his tone and manner of expression.
+  instructions:
+    - Think with deep intellectual curiosity
+    - Use thought experiments and analogies
+    - Challenge conventional assumptions
+    - Express complex ideas with elegant simplicity

package/default/agents/judge.yaml

@@ -0,0 +1,32 @@
+version: '1.0'
+kind: Agent
+metadata:
+  name: Impartial Judge
+  description: An impartial judge agent for evaluating debates
+spec:
+  id: judge
+  model_settings:
+    model: gpt-5.4-nano
+    reasoning:
+      effort: high
+  goal: To provide fair and unbiased evaluation of arguments
+  role: Debate Judge
+  system_prompt: "You are an impartial judge evaluating debates. Remain neutral and objective, focusing on the quality, logic, and persuasiveness of arguments rather than personal opinions. Evaluate based on evidence, reasoning, clarity, and relevance. Provide fair assessments without bias toward any particular viewpoint or participant."
+  instructions:
+    - Remain completely impartial and neutral
+    - Evaluate arguments based on logic, evidence, and clarity
+    - Consider both sides fairly
+    - Base judgments on merit, not personal preference
+    - Reference historical examples of fair judgment when appropriate
+  output:
+    format: json
+    structure:
+      winner: string
+      votes:
+        - agent: string
+          vote: string
+    instructions: |
+      As an impartial judge, evaluate the debate arguments and provide your judgment.
+      - winner: filename of the agent with the strongest argument
+      - votes: array with detailed reasoning for each agent's argument quality
+

package/default/debate/debate1.yaml

@@ -0,0 +1,29 @@
+version: '1.0'
+kind: Debate
+metadata:
+  name: Meaning of Life Debate
+  description: A philosophical debate between Einstein and Confucius on the meaning of life
+spec:
+  method: majority_vote
+  input: What is the meaning of life?
+  debug: true
+  judges:
+    - default/agents/judge.yaml
+  agents:
+    - default/agents/einstein.yaml
+    - default/agents/confucius.yaml
+  output:
+    format: json
+    structure:
+      winner: string  # filename of the winning agent
+      reasoning: string  # overall explanation for the decision
+      votes:  # array of individual agent evaluations
+        - agent: string  # filename of the agent being evaluated
+          vote: string  # detailed reasoning why this agent should win
+    instructions: |
+      Evaluate the arguments and provide your judgment in structured JSON format.
+      - winner: filename of the winning agent (e.g., "default/agents/einstein.yaml")
+      - reasoning: overall explanation for why this agent won the debate
+      - votes: array where each item contains:
+        - agent: filename of the agent being evaluated
+        - vote: detailed reasoning explaining the strengths and weaknesses of this agent's argument, including analysis of logic, evidence, clarity, and persuasiveness

package/default/debate/debate2.yaml

@@ -0,0 +1,41 @@
+version: '1.0'
+kind: Debate
+metadata:
+  name: Riddle Creation Debate
+  description: Agents create random riddles, judge validates them
+spec:
+  method: majority_vote
+  input: Create a completely original riddle. The riddle should be clever, have a clear answer, and follow the classic riddle format (a question or statement that describes something without naming it directly).
+  debug: false
+  judges:
+    - default/agents/judge.yaml
+  agents:
+    - default/agents/einstein.yaml
+    - default/agents/confucius.yaml
+  output:
+    format: json
+    structure:
+      winner: string  # filename of the agent with the best riddle
+      winner_riddle: string  # the riddle created by the winning agent
+      reasoning: string  # explanation of why this riddle was chosen as best
+      validation_results:  # array of validation results for each riddle
+        - agent: string  # filename of the agent
+          riddle: string  # the riddle they created
+          is_valid_riddle: boolean  # whether it's a proper riddle
+          validation_reasoning: string  # why it is/isn't valid
+          quality_score: number  # 1-10 rating of riddle quality
+      votes:  # individual judge evaluations
+        - agent: string  # filename of the agent being evaluated
+          vote: string  # detailed reasoning for the vote
+    instructions: |
+      Evaluate the riddles created by the agents. For each riddle, determine:
+      1. Is it a valid riddle? (has a clear answer, clever wording, not too obvious)
+      2. Quality score (1-10) based on creativity, cleverness, and proper riddle structure
+      3. Choose the best riddle as winner
+      
+      Respond with structured JSON containing:
+      - winner: filename of agent with best riddle
+      - winner_riddle: the riddle created by the winning agent
+      - reasoning: why this riddle won
+      - validation_results: array with validation for each agent's riddle
+      - votes: detailed evaluation of each riddle

package/docs/yaml-structure-guide.md

@@ -0,0 +1,287 @@
+# YAML Structure Guide for LLM-MAR
+
+This guide explains how to structure YAML configuration files for the LLM-MAR (Large Language Model Multi-Agent Reasoning) tool.
+
+## Overview
+
+LLM-MAR uses YAML files to define agents, teams, and debates. Each configuration follows a consistent structure with version, kind, metadata, and spec sections.
+
+## Common Structure
+
+All YAML files share this basic structure:
+
+```yaml
+version: '1.0'
+kind: [Agent|Team|Debate]
+metadata:
+  name: [string]
+  description: [string]
+spec:
+  # Kind-specific configuration
+```
+
+## Agent Configuration
+
+Agents are individual AI entities with specific roles and behaviors.
+
+### Basic Agent Structure
+
+```yaml
+version: '1.0'
+kind: Agent
+metadata:
+  name: Albert Einstein
+  description: Theoretical physicist agent
+spec:
+  id: einstein
+  model: gpt-4
+  goal: To think deeply about scientific questions
+  role: Theoretical Physicist
+  system_prompt: You are Albert Einstein, the brilliant theoretical physicist...
+  instructions:
+    - Think with deep intellectual curiosity
+    - Use thought experiments and analogies
+    - Challenge conventional assumptions
+    - Express complex ideas with elegant simplicity
+  output:  # Optional: for structured responses
+    format: json
+    structure:
+      response: string
+      reasoning: string
+```
+
+### Agent Fields
+
+- **id**: Unique identifier for the agent
+- **model**: OpenAI model to use (e.g., gpt-4, gpt-3.5-turbo)
+- **goal**: High-level objective of the agent
+- **role**: Specific role or persona
+- **system_prompt**: Instructions that define the agent's personality and behavior
+- **instructions**: List of specific behavioral guidelines
+- **output**: Optional structured output configuration
+
+### Output Structure
+
+For structured responses, define the expected JSON format:
+
+```yaml
+output:
+  format: json
+  structure:
+    field_name: data_type  # string, number, boolean
+    nested_object:
+      subfield: string
+    array_field:
+      - item_type: string
+  instructions: |
+    Detailed instructions for the AI about what content to put in each field.
+    Explain the purpose of each field and what kind of response is expected.
+    This text will be included in the AI prompt to guide its output.
+```
+
+The `instructions` field is optional but recommended for complex structured outputs. It provides specific guidance to the AI about how to fill each field, making the output more predictable and useful.
+
+## Team Configuration
+
+Teams coordinate multiple agents to work together on tasks.
+
+### Basic Team Structure
+
+```yaml
+version: '1.0'
+kind: Team
+metadata:
+  name: Research Team
+  description: A team for collaborative research
+spec:
+  method: sequential  # or parallel
+  input: Research question here
+  agents:
+    - agent1.yaml
+    - agent2.yaml
+  output:
+    format: json
+    structure:
+      conclusion: string
+      evidence: string
+```
+
+### Team Fields
+
+- **method**: How agents collaborate (sequential, parallel)
+- **input**: The task or question for the team
+- **agents**: List of agent YAML file paths
+- **output**: Optional structured output format
+
+## Debate Configuration
+
+Debates pit agents against each other with judges to determine winners.
+
+### Basic Debate Structure
+
+```yaml
+version: '1.0'
+kind: Debate
+metadata:
+  name: AI Ethics Debate
+  description: Debate on AI regulation
+spec:
+  method: majority_vote  # or first_judge
+  input: Should AI be regulated?
+  judges:
+    - judge.yaml
+  agents:
+    - agent1.yaml
+    - agent2.yaml
+  output:
+    format: json
+    structure:
+      winner: string
+      votes:
+        - agent: string
+          vote: string
+```
+
+### Debate Fields
+
+- **method**: Voting method (majority_vote, first_judge)
+- **input**: The debate topic or question
+- **judges**: List of judge agent YAML file paths
+- **agents**: List of debating agent YAML file paths
+- **output**: Structured output for debate results with optional instructions
+
+### Structured Output with Instructions
+
+For debates with complex evaluation requirements, use the `instructions` field to guide the judge's evaluation criteria:
+
+```yaml
+output:
+  format: json
+  structure:
+    winner: string
+    reasoning: string
+    votes:
+      - agent: string
+        vote: string
+  instructions: |
+    Evaluate the debate arguments and provide structured judgment.
+    - winner: filename of the winning agent
+    - reasoning: overall explanation for the decision
+    - votes: detailed analysis of each agent's argument quality
+```
+
+## File Organization
+
+Store YAML files in organized directories:
+
+```
+default/
+  agents/
+    scientist.yaml
+    philosopher.yaml
+    judge.yaml
+  teams/
+    research_team.yaml
+  debates/
+    ethics_debate.yaml
+```
+
+## Best Practices
+
+1. **Use descriptive names**: Choose clear, meaningful names for agents and configurations
+2. **Write detailed system prompts**: Provide comprehensive instructions for agent behavior
+3. **Define clear roles**: Give each agent a distinct purpose and expertise
+4. **Structure outputs**: Use structured output for programmatic processing
+5. **Add instructions for complex outputs**: Use the `instructions` field in output configuration to guide AI behavior for structured responses
+6. **Test configurations**: Run agents individually before using in teams/debates
+7. **Version control**: Keep YAML files under version control for collaboration
+
+## Examples
+
+### Simple Agent
+```yaml
+version: '1.0'
+kind: Agent
+metadata:
+  name: Helper
+  description: A helpful assistant
+spec:
+  id: helper
+  model: gpt-4
+  goal: To assist users
+  role: Assistant
+  system_prompt: You are a helpful assistant.
+  instructions:
+    - Be polite and clear
+    - Provide accurate information
+```
+
+### Structured Output Agent
+```yaml
+version: '1.0'
+kind: Agent
+metadata:
+  name: Analyst
+  description: Data analysis agent
+spec:
+  id: analyst
+  model: gpt-4
+  goal: To analyze data and provide insights
+  role: Data Analyst
+  system_prompt: You are a data analyst who provides structured insights.
+  instructions:
+    - Analyze data objectively
+    - Provide clear conclusions
+    - Support claims with evidence
+  output:
+    format: json
+    structure:
+      analysis: string
+      key_findings:
+        - finding: string
+          importance: string
+      recommendation: string
+```
+
+### Debate with Multiple Judges
+```yaml
+version: '1.0'
+kind: Debate
+metadata:
+  name: Climate Change Debate
+  description: Debate on climate policy
+spec:
+  method: majority_vote
+  input: What is the best approach to combat climate change?
+  judges:
+    - judges/scientist_judge.yaml
+    - judges/economist_judge.yaml
+  agents:
+    - agents/environmentalist.yaml
+    - agents/economist.yaml
+    - agents/technologist.yaml
+  output:
+    format: json
+    structure:
+      winner: string
+      reasoning: string
+      votes:
+        - agent: string
+          vote: string
+    instructions: |
+      Evaluate each agent's argument based on:
+      - Scientific accuracy and evidence
+      - Economic feasibility and cost-benefit analysis
+      - Technical implementation challenges
+      - Social and political considerations
+      Provide detailed reasoning for your judgment.
+```
+
+## Validation
+
+Always validate your YAML files:
+- Use a YAML validator to check syntax
+- Test agents individually with `llm-mar run agent.yaml`
+- Ensure file paths are correct and accessible
+- Verify structured output schemas match expected formats</content>
+<parameter name="filePath">/root/llm-mar/docs/yaml-structure-guide.md

package/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const setupCreate = require('./commands/create');
+const setupRun = require('./commands/run');
+
+const program = new Command();
+
+program
+  .name('llm-mar')
+  .description('CLI for LLM agent workflows')
+  .version('1.0.0');
+
+setupCreate(program);
+setupRun(program);
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "llm-mar",
+  "version": "1.0.0",
+  "description": "LLM-MAR is a compact CLI that creates LLM agents, lets them debate, answers questions, and builds workflows.",
+  "main": "index.js",
+  "bin": {
+    "llm-mar": "index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/renatojuniorrs/llm-mar.git"
+  },
+  "dependencies": {
+    "@langchain/openai": "^1.4.3",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1",
+    "langchain": "^1.3.1",
+    "zod": "^4.3.6"
+  }
+}

package/workflows/index.js

@@ -0,0 +1,301 @@
+const { runAgent } = require('../agents');
+const fs = require('fs');
+const yaml = require('js-yaml');
+const { z } = require('zod');
+
+function createZodSchema(structure) {
+  if (typeof structure === 'object') {
+    const schema = {};
+    for (const [key, value] of Object.entries(structure)) {
+      if (typeof value === 'string') {
+        if (value === 'string') schema[key] = z.string();
+        else if (value === 'number') schema[key] = z.number();
+        else if (value === 'boolean') schema[key] = z.boolean();
+        else schema[key] = z.string(); // default
+      } else if (Array.isArray(value)) {
+        if (value.length > 0 && typeof value[0] === 'object') {
+          schema[key] = z.array(createZodSchema(value[0]));
+        } else {
+          schema[key] = z.array(z.string()); // default
+        }
+      } else if (typeof value === 'object') {
+        schema[key] = createZodSchema(value);
+      }
+    }
+    return z.object(schema);
+  }
+  return z.string(); // fallback
+}
+
+function buildWorkflow(name) {
+  console.log(`Building workflow ${name}...`);
+}
+
+async function runTeam(config, agentId, input) {
+  // Find the agent: could be embedded object or file path
+  let agentConfig;
+  const agentEntry = config.agents.find(agent => {
+    if (typeof agent === 'string') {
+      // File path
+      const basename = agent.split('/').pop().replace('.yaml', '');
+      return basename === agentId;
+    } else {
+      // Embedded object
+      return agent.id === agentId;
+    }
+  });
+  
+  if (!agentEntry) {
+    throw new Error(`Agent ${agentId} not found in team`);
+  }
+  
+  if (typeof agentEntry === 'string') {
+    // Load from file
+    try {
+      const agentYaml = fs.readFileSync(agentEntry, 'utf8');
+      const agentData = yaml.load(agentYaml);
+      if (agentData.kind !== 'Agent') {
+        throw new Error(`${agentEntry} is not an Agent`);
+      }
+      agentConfig = agentData.spec;
+    } catch (e) {
+      throw new Error(`Agent file ${agentEntry} not found or invalid: ${e.message}`);
+    }
+  } else {
+    // Embedded
+    agentConfig = agentEntry;
+    if (!agentConfig.model) {
+      // Try to load from default/
+      try {
+        const agentYaml = fs.readFileSync(`default/${agentId}.yaml`, 'utf8');
+        const agentData = yaml.load(agentYaml);
+        agentConfig = agentData.spec;
+      } catch (e) {
+        throw new Error(`Agent ${agentId} not found or invalid`);
+      }
+    }
+  }
+  
+  const agentYaml = {
+    kind: 'Agent',
+    spec: agentConfig
+  };
+  await runAgent(agentYaml, input);
+}
+
+async function runDebate(config) {
+  // Validate API key is set
+  if (!process.env.OPENAI_API_KEY) {
+    throw new Error('OPENAI_API_KEY environment variable is required to run debates. Please set it with: export OPENAI_API_KEY=your_api_key');
+  }
+
+  // Validate that all agents and judges files exist and are Agents or Teams
+  const allFiles = [...config.spec.agents, ...config.spec.judges];
+  for (const file of allFiles) {
+    try {
+      const yamlContent = fs.readFileSync(file, 'utf8');
+      const data = yaml.load(yamlContent);
+      if (data.kind !== 'Agent' && data.kind !== 'Team') {
+        throw new Error(`${file} is not an Agent or Team`);
+      }
+    } catch (e) {
+      throw new Error(`Participant file ${file} not found or invalid: ${e.message}`);
+    }
+  }
+
+  const outputFormat = config.spec.output || 'text';
+  
+  // Collect arguments from agents
+  const agentArguments = [];
+  for (const agentFile of config.spec.agents) {
+    try {
+      const agentConfig = yaml.load(fs.readFileSync(agentFile, 'utf8'));
+      if (agentConfig.kind === 'Agent') {
+        // Run the agent with the debate input
+        const { ChatOpenAI } = require('@langchain/openai');
+        
+        // Handle both model_settings object and legacy model string
+        const modelSettings = agentConfig.spec.model_settings || agentConfig.spec.model;
+        let modelConfig;
+        if (typeof modelSettings === 'string') {
+          modelConfig = { modelName: modelSettings };
+        } else {
+          modelConfig = { 
+            modelName: modelSettings.model, 
+            ...modelSettings 
+          };
+        }
+        
+        const model = new ChatOpenAI(modelConfig);
+        const response = await model.invoke([
+          { role: 'system', content: agentConfig.spec.system_prompt },
+          { role: 'user', content: `Debate this topic: ${config.spec.input}. Provide your argument.` }
+        ]);
+        agentArguments.push({
+          agent: agentFile,
+          argument: response.content
+        });
+      }
+    } catch (error) {
+      agentArguments.push({
+        agent: agentFile,
+        argument: `Error: ${error.message}`
+      });
+    }
+  }
+  
+  // Have judges vote
+  const votes = [];
+  let structuredResult = null;
+  for (const judgeFile of config.spec.judges) {
+    try {
+      const judgeConfig = yaml.load(fs.readFileSync(judgeFile, 'utf8'));
+      if (judgeConfig.kind === 'Agent') {
+        const { ChatOpenAI } = require('@langchain/openai');
+        
+        // Handle both model_settings object and legacy model string
+        const modelSettings = judgeConfig.spec.model_settings || judgeConfig.spec.model;
+        let modelConfig;
+        if (typeof modelSettings === 'string') {
+          modelConfig = { modelName: modelSettings };
+        } else {
+          modelConfig = { 
+            modelName: modelSettings.model, 
+            ...modelSettings 
+          };
+        }
+        
+        const model = new ChatOpenAI(modelConfig);
+        
+        let judgePrompt;
+        let responseFormat = null;
+        
+        if (typeof outputFormat === 'object' && outputFormat.format === 'json' && outputFormat.structure) {
+          // Use structured output for judge
+          responseFormat = createZodSchema(outputFormat.structure);
+          const instructions = outputFormat.instructions || `Evaluate the arguments and provide your judgment in the required structured format. The winner should be the filename of the winning agent. Each vote should have the agent filename and reasoning.`;
+          judgePrompt = `You are judging a debate on: ${config.spec.input}\n\nArguments:\n${agentArguments.map((arg, i) => `Agent ${i+1} (${arg.agent}): ${arg.argument}`).join('\n\n')}\n\nTASK: ${instructions}`;
+        } else {
+          judgePrompt = `You are judging a debate on: ${config.spec.input}\n\nArguments:\n${agentArguments.map((arg, i) => `Agent ${i+1} (${arg.agent}): ${arg.argument}`).join('\n\n')}\n\nTASK: Choose which agent presented the strongest argument.\n\nIMPORTANT: Respond with ONLY the filename of the winning agent. Do not include any other text, explanation, or punctuation.\n\nValid responses: ${config.spec.agents.map(a => `"${a}"`).join(' or ')}`;
+        }
+        
+        let response;
+        if (responseFormat) {
+          const structuredModel = model.withStructuredOutput(responseFormat);
+          response = await structuredModel.invoke([
+            { role: 'system', content: judgeConfig.spec.system_prompt },
+            { role: 'user', content: judgePrompt }
+          ]);
+          structuredResult = response; // Use the last judge's structured response
+        } else {
+          response = await model.invoke([
+            { role: 'system', content: judgeConfig.spec.system_prompt },
+            { role: 'user', content: judgePrompt }
+          ]);
+        }
+        
+        if (responseFormat) {
+          // Structured response already handled
+        } else {
+          // Parse the vote - extract filename
+          let vote = response.content.trim();
+          // Remove quotes if present
+          vote = vote.replace(/^["']|["']$/g, '');
+          // Check if it's a valid agent file
+          if (!config.spec.agents.includes(vote)) {
+            // Try to find a matching filename in the response
+            const filenameMatch = vote.match(/(default\/[^.]+\.yaml)/);
+            if (filenameMatch) {
+              vote = filenameMatch[1];
+            } else {
+              vote = 'Invalid';
+            }
+          }
+          
+          votes.push({
+            judge: judgeFile,
+            vote: vote
+          });
+        }
+      }
+    } catch (error) {
+      votes.push({
+        judge: judgeFile,
+        vote: 'Error'
+      });
+    }
+  }
+  
+  // Count votes to determine winner
+  const voteCount = {};
+  votes.forEach(v => {
+    if (v.vote && v.vote !== 'Error') {
+      voteCount[v.vote] = (voteCount[v.vote] || 0) + 1;
+    }
+  });
+  
+  let winner = null;
+  let maxVotes = 0;
+  for (const [candidate, count] of Object.entries(voteCount)) {
+    if (count > maxVotes) {
+      maxVotes = count;
+      winner = candidate;
+    }
+  }
+  
+  const winnerArgument = agentArguments.find(arg => arg.agent === winner)?.argument || 'No argument found';
+  
+  if (typeof outputFormat === 'object' && outputFormat.format === 'json') {
+    let result;
+    if (structuredResult) {
+      result = structuredResult;
+      // Add agents_response in debug mode
+      if (config.spec.debug) {
+        result.agents_response = agentArguments;
+      }
+    } else {
+      result = {
+        debate: config.metadata.name,
+        method: config.spec.method,
+        input: config.spec.input,
+        agents: config.spec.agents,
+        judges: config.spec.judges,
+        arguments: agentArguments,
+        votes: votes,
+        winner: winner,
+        winnerResponse: winnerArgument,
+        status: 'completed',
+        timestamp: new Date().toISOString()
+      };
+      // Add agents_response in debug mode
+      if (config.spec.debug) {
+        result.agents_response = agentArguments;
+      }
+    }
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Running debate with method: ${config.spec.method}`);
+    console.log(`Topic: ${config.spec.input}`);
+    console.log(`Agents: ${config.spec.agents.join(', ')}`);
+    console.log(`Judges: ${config.spec.judges.join(', ')}`);
+    
+    agentArguments.forEach((arg, index) => {
+      console.log(`\nAgent ${index + 1} (${arg.agent}):`);
+      console.log(arg.argument);
+    });
+    
+    console.log('\nVotes:');
+    votes.forEach(v => {
+      console.log(`${v.judge}: ${v.vote}`);
+    });
+    
+    console.log(`\nWinner: ${winner}`);
+    console.log(`Winning argument: ${winnerArgument}`);
+  }
+}
+
+module.exports = {
+  buildWorkflow,
+  runTeam,
+  runDebate
+};