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
  • Features
  • Installation
    • Prerequisites
    • Steps
  • Getting Started
  • Usage
    • Generating Agents
    • Running the Agents
  • 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
    • Importance of First Principles Thinking
  • Validation and Supporting Evidence
    • 1. Dynamic Task Decomposition
    • 2. Iterative Problem-Solving and Adaptability
  • Limitations and Future Enhancements
  • Contributing
  • License

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 18 or higher
• npm or Yarn: npm v6+ or Yarn v1.22+
• Anthropic API key (ANTHROPIC_API_KEY): Required to call Claude. All model calls run on Claude Opus 4.8 via the Claude Agent SDK.

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 Anthropic API key:

   ANTHROPIC_API_KEY=your-anthropic-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.

How It Works

1. Typed truths: The goal is decomposed into typed, falsifiable claims — facts, assumptions, constraints, definitions. Types are commitments the system checks.
2. Adversarial vetting: A skeptic pass attacks every truth. Survivors are kept, unverifiable ones are demoted to explicit assumptions (surfaced to you), broken ones are rejected with the attack recorded.
3. Decomposition with citations: Every subtask must cite the truths it serves. Coverage is computed in code: an uncited truth is a missed requirement; a subtask citing nothing is scope creep.
4. Refinement, not re-rolls: The decomposition is revised against the judge's evidence-backed critique until nothing new fails (fixed point), the same criterion fails twice (escalate — looping again would be a re-roll), or the iteration budget runs out.
5. Data, not codegen: The output package is an ontology.json plus a generic runtime. At run time, a triage step checks whether your prompt fits the frame (and answers directly if it doesn't), plans which agents to run, executes them in dependency levels over a shared blackboard, judges every output against a rubric derived from the truths, and synthesizes the final answer.

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

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.

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.