Principles Framework

Principles is a powerful and flexible framework that enables you to generate specialized AI agents based on a goal or problem statement. By applying first principles thinking, Principles breaks down your goal into its most fundamental truths or components—the smallest, indivisible parts of the problem. It then generates a network of collaborating agents that address each fundamental component. This approach allows you to create highly effective AI solutions tailored to your specific needs, enabling you to process subsequent prompts with greater accuracy and efficiency than general-purpose language models.

Note: This framework was designed as an experiment, and the code may require refining in some places.

For a more exhaustive discussion of the Principles Framework, explore the blog post here.

Influences

This framework was heavily influenced by the following:

• OpenAI Swarm
• Breaking Down Complexity: A Journey into Multi-Agent Systems and the Future of Collaborative AI

Table of Contents

• Principles Framework
  • Influences
  • Table of Contents
  • Recent Enhancements
  • Features
  • Installation
    • Prerequisites
    • Steps
  • Getting Started
  • Usage
    • Generating Agents
    • Running the Agents
  • Architecture Overview
    • Agents and Their Roles
    • Orchestrator Agent and Agent Coordination
    • Agent Registry and Dynamic Agent Loading
  • How It Works
  • Detailed Workflow of Agent Generation and Execution
  • Advanced Features and Functionality
  • Extensibility and Integration
  • Error Handling and Validation
  • Simplified Example Workflow
    • Step 1: Generate Agents Based on a Goal or Problem Statement
    • Step 2: Use the Agents to Process Prompts
  • Iterative Refinement and Integration
  • Troubleshooting
    • 1. Circular Dependencies When Running Agents
    • 2. Importance of First Principles Thinking
    • 3. Accessing o1 Models on OpenAI
  • Validation and Supporting Evidence
    • 1. Dynamic Task Decomposition
    • 2. Iterative Problem-Solving and Adaptability
  • Limitations and Future Enhancements
  • Contributing
  • License

Recent Enhancements

• Iterative Refinement of Fundamental Truths and Subtasks:
  The framework can now iteratively refine both the fundamental truths and the subtasks. If initial truths prove insufficient or if subtasks are not minimal or feasible, it can re-derive truths or re-decompose tasks as needed. This ensures that the final solution is always built upon stable, minimal, and actionable components.

• Feasibility Checks for Subtasks:
  The decomposition logic now ensures that subtasks remain within the capabilities of a text-based assistant. Instead of producing unfeasible instructions (e.g., external physical actions), it focuses on tasks the agents can realistically handle, such as generating summaries, analyses, or structured proposals.

• Comprehensive Agent Descriptions for Prompt Generation:
  The final integrated output now includes exhaustively detailed agent descriptions. Each agent specification is rich in context, instructions, constraints, and examples—enabling you to directly transform these final descriptions into robust prompts for creating or configuring agents in your downstream workflows.

These enhancements maintain and build upon the original core idea of using first principles reasoning to design specialized agents, while ensuring an adaptive, iterative refinement process and producing final outputs that are both minimal and extremely prompt-ready.

Features

• First Principles Decomposition: Break down your goal into fundamental truths and minimal subtasks.
• Iterative Refinement: Dynamically re-derive truths or refine subtasks if initial attempts are insufficient or misaligned.
• Feasibility Assurance: Ensures subtasks are strictly within the realm of a text-based assistant’s capabilities.
• Rich Final Output: Produces highly detailed agent definitions, ready to be turned into prompts for agent instantiation.
• Execution Order & Dependency Management: Uses sophisticated algorithms to determine the optimal execution order of agents.
• Error Handling & Validation: Provides robust error handling, standardized JSON formats, and iterative improvements to correct issues.
• Parallel Execution: Agents without dependencies can run in parallel for performance gains.

Installation

Prerequisites

• Node.js: Version 14 or higher
• npm or Yarn: npm v6+ or Yarn v1.22+
• OpenAI API Key: Required for GPT models

Steps

1. Clone the Repository

   git clone https://github.com/miltonian/principles.git
   cd principles

2. Install Dependencies

   npm install
   # or
   yarn install

3. Set Up Environment Variables

   Create a .env file in the root directory and add your OpenAI API key:

   OPEN_AI_TOKEN=your-openai-api-key

4. Check .env in .gitignore

   Ensure .env is in .gitignore to avoid committing sensitive data.

Getting Started

Principles takes your goal or problem statement and applies first principles reasoning to identify fundamental truths and minimal subtasks. Through iterative refinement, it ensures these fundamental pieces are stable, aligned, and feasible for a text-based assistant. The final output includes a thoroughly documented set of agents, allowing you to directly generate effective prompts or seamlessly integrate the agents into your solution.

Usage

Generating Agents

npm run generate-agents "I want to design a multi-agent system using first principles thinking."

This command:

• Derives fundamental truths from your goal.
• Decomposes the goal into minimal subtasks.
• Iteratively refines truths or tasks if needed, ensuring both are minimal and actionable.
• Produces a package in packages/ containing the generated agents and all necessary configurations, complete with comprehensive agent specifications.

Running the Agents

After generating agents, you can run them against new prompts:

cd packages/<generated-agent-directory>/
npm run run-agents "How should these agents adapt if the project's constraints change?"

The agents respond with results grounded in refined truths and minimal subtasks. The final breakdown includes extensive agent descriptions, enabling you to directly craft prompts for new agents.

Architecture Overview

Agents and Their Roles

Within Principles, agents address distinct aspects of your goal’s decomposition. While the framework uses a variety of conceptual agents (such as those analyzing the problem, decomposing tasks, designing communication strategies, and generating agent designs), the newly introduced iterative refinement logic ensures that by the time you have your final agents, every fundamental assumption and subtask has been verified and adjusted if necessary.

Orchestrator Agent and Agent Coordination

The OrchestratorAgent orchestrates execution, resolves dependencies, and manages iterative refinements. If necessary, it re-derives truths or re-decomposes tasks until everything is minimal and aligned.

Agent Registry and Dynamic Agent Loading

The registry allows dynamic loading of agents, enabling flexible scaling and customization. With iterative refinement ensuring stable final outputs, you can trust that what’s loaded is coherent and ready for use.

How It Works

1. Provide a Goal: Supply a clear objective or problem statement.
2. First Principles Reasoning: Identify fundamental truths and minimal subtasks.
3. Iterative Refinement: If something’s off, re-check truths or tasks to achieve stable, minimal results.
4. Finalize Agents: Produce a final set of agents, thoroughly documented for immediate prompt generation or integration.

Detailed Workflow of Agent Generation and Execution

1. Intent Extraction & Fundamental Truths: Understand the user’s goals and establish core assumptions.
2. Task Decomposition & Iterative Refinement: Break down the goal into subtasks, and if needed, refine truths or tasks again.
3. Integration: Combine everything into a final, detail-rich agent output that can directly feed into prompt creation.

Advanced Features and Functionality

• Iterative Refinement Loops: Continues refining until minimal, feasible, and aligned conditions are met.
• Strict Feasibility: Prevents agents from receiving impossible subtasks.
• Comprehensive Agent Data: Each agent’s final definition is so thorough you can immediately create prompts from it.

Extensibility and Integration

The final result is a package of agents you can integrate into larger workflows or use as blueprints for generating agent prompts. The in-depth final specifications enable seamless adoption in any downstream application.

Error Handling and Validation

The framework uses standardized JSON errors and adheres to strict validation checks. If subtasks or truths are problematic, iterative refinement corrects them before finalization, reducing manual debugging.

Simplified Example Workflow

Step 1: Generate Agents Based on a Goal or Problem Statement

Command:

npm run generate-agents "I want to design a multi-agent system using first principles thinking."

Process:

• Extracts intent, derives fundamental truths.
• Decomposes the problem into minimal subtasks.
• Iteratively refines both truths and subtasks if initial attempts aren’t optimal.
• Produces a package with fully documented agents.

Outcome:
You get a new directory in packages/ containing your agents and their configurations.

Step 2: Use the Agents to Process Prompts

Command:

cd packages/<generated-agent-directory>/
npm run run-agents "How should these agents adapt if the project's constraints change?"

Result:

• The agents respond coherently, aligned with refined truths and minimal subtasks.
• The final breakdown includes complete agent descriptions, enabling direct prompt creation for future agents.

Iterative Refinement and Integration

Iterative refinement ensures that the fundamental truths and subtasks aren’t just derived once but revisited until stable. This process guarantees that the final agent set is minimal, accurate, and fully detailed, so you can immediately leverage the final agent descriptions as powerful prompt templates.

Troubleshooting

1. Circular Dependencies When Running Agents

If you encounter circular dependencies:

• Follow the existing guidelines to identify and remove cycles.
• The iterative refinement may help stabilize the order, but manual edits in agentsConfig.ts might still be required.

2. Importance of First Principles Thinking

First principles drive every step:

• Decompose your goal into undeniable truths and minimal tasks.
• Iterative refinement ensures these fundamentals stay correct and aligned, improving outcomes and reducing complexity.

3. Accessing o1 Models on OpenAI

If you need o1 models but encounter access issues:

• Refer to the provided instructions on contacting support or substituting another model.
• The iterative and prompt-ready nature of the framework remains effective regardless of the underlying model.

Validation and Supporting Evidence

The methodologies underpinning the Principles Framework are strongly validated by research studies demonstrating the effectiveness of decomposition-based frameworks. Key findings from these studies provide evidence for the power and utility of the Principles approach:

1. Dynamic Task Decomposition

The Principles Framework's focus on breaking down complex goals into their most fundamental components aligns with results from the TDAG (Dynamic Task Decomposition and Agent Generation) framework:

• TDAG Results:
  • Achieved up to 33% improvement in success rates on compositional reasoning tasks.
  • 28.3% increase in task completion rates in dynamic environments (ALFWorld benchmark).
  • 27% performance boost on interactive tasks (WebShop benchmark).
• Key Advantages:
  • Dynamic Adaptability: TDAG dynamically decomposes tasks and generates custom subagents, enhancing adaptability in complex, real-world tasks.
  • Error Reduction: Significant reduction in error rates, particularly in cascading task failures, due to dynamic adjustments and specialized subagents.

These results demonstrate the value of modular decomposition and dynamic agent generation, which are cornerstones of the Principles Framework.

Reference: TDAG Framework and ItineraryBench

2. Iterative Problem-Solving and Adaptability

The iterative and adaptive nature of the Principles Framework is reinforced by studies on modular problem-solving systems:

• Dynamic Role Discovery and Assignment (DRDA):
  • Improved task allocation efficiency by 20%-30% using dynamic role assignment in multi-agent systems.
  • Performance Gains: Achieved higher win rates in complex scenarios, demonstrating the effectiveness of dynamic role policies and restricted action spaces.
  • Key Insights:
    • Dynamic role assignment allows agents to adapt to changing environments and tasks.
    • Role-specific policies enhance learning efficiency by reducing action space complexity.

Reference: Dynamic Role Discovery and Assignment

• TASKBENCH:
  • Provided insights into LLM limitations and strengths in task automation.
  • Showed that advanced models like GPT-4 excel in reasoning and parameter prediction, especially in complex tasks requiring tool dependencies.
  • Performance Trends:
    • Advanced models demonstrated higher performance in tasks requiring dynamic reasoning and alignment.
    • Emphasized the importance of code pretraining, human alignment techniques, and instruction fine-tuning in enhancing task automation capabilities.

Reference: TASKBENCH

These studies highlight the effectiveness of dynamic decomposition and iterative problem-solving, which are central to the Principles Framework.

Contributing

Contributions are welcome. If you have ideas for better heuristics, improved logging, or richer final agent definitions, follow the Contributing guidelines to submit your enhancements.

License

Principles is released under the MIT License.