<img src="logo.svg" height="200" alt="Principles Framework Logo">

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 Integ