RationalAgents

LLMs simulate reasoning. This library actually reasons.

A pure-Python formal reasoning library for AI agents. Currently implements game-theoretic reasoning — with plans to extend to other mathematical frameworks for rational decision-making.

LLM handles: understanding, communication, translation
RationalAgents handles: optimal decisions, belief updating, equilibrium finding, formal proofs

---

Why This Exists

Every AI agent framework (LangChain, CrewAI, AutoGen) orchestrates LLMs but has zero formal reasoning. They prompt and hope.

When your agent negotiates a contract, prices against competitors, or allocates resources among partners—you need math, not vibes.

RationalAgents provides:

• Consistency — math doesn't hallucinate
• Optimality guarantees — not "usually good" but "provably best given assumptions"
• Interpretability — can explain why a decision is rational
• Composability — reasoning primitives that combine

---

The Vision

Phase 1 (Current): Game-Theoretic Reasoning

• Strategic decision-making under uncertainty
• Belief updating, equilibrium computation, mechanism design
• Multi-agent interactions with competing/aligned incentives

---

Possible extensions

---

Phase 2: Extended Formal Reasoning

• Causal inference (do-calculus, counterfactuals)
• Probabilistic reasoning (Bayesian networks, credal sets)
• Constraint satisfaction and optimization
• Temporal reasoning and planning

Phase 3: Unified Reasoning Architecture

• Composable reasoning modules
• Automatic selection of appropriate reasoning framework
• Hybrid symbolic-neural integration

---

Installation

pip install rational-agents  # coming soon

# For now:
git clone https://github.com/Arvind-puthucode/rational-agents-engine
cd rational-agents
pip install -e .

---

Quick Start

Find Nash Equilibria

import numpy as np
from rational_agents.games import solve_bimatrix_game

# Prisoner's Dilemma
#        Cooperate   Defect
# Coop    (3,3)      (0,5)
# Defect  (5,0)      (1,1)

payoffs = np.array([
    [[3, 3], [0, 5]],
    [[5, 0], [1, 1]]
])

equilibria = solve_bimatrix_game(payoffs)
# Returns: [NashEquilibrium(strategy_p1=[0,1], strategy_p2=[0,1], payoff_p1=1, payoff_p2=1)]
# Both defect — the classic result

Update Beliefs (Bayesian)

from rational_agents.beliefs import DiscretePrior, update_discrete

# You think there's 50% chance opponent is "aggressive", 50% "passive"
prior = DiscretePrior(types=["aggressive", "passive"], probs=[0.5, 0.5])

# Likelihood: aggressive types bid high 80% of time, passive 20%
likelihood = {
    "aggressive": {"high_bid": 0.8, "low_bid": 0.2},
    "passive": {"high_bid": 0.2, "low_bid": 0.8}
}

# You observe a high bid
posterior = update_discrete(prior, "high_bid", likelihood)
print(posterior.to_dict())
# {'aggressive': 0.8, 'passive': 0.2}

Fair Attribution (Shapley Values)

from rational_agents.cooperative import calculate_shapley_values

# Marketing attribution: which channels drove conversions?
def conversion_value(channels):
    if not channels: return 0
    if channels == {"email"}: return 10
    if channels == {"ads"}: return 15  
    if channels == {"email", "ads"}: return 40  # synergy!
    return 0

shapley = calculate_shapley_values(["email", "ads"], conversion_value)
# {'email': 17.5, 'ads': 22.5}
# Ads get more credit, but email's synergy contribution is recognized

Mechanism Design (Auctions)

from rational_agents.mechanisms import VickreyAuction, is_incentive_compatible

# Run a second-price auction
auction = VickreyAuction()
result = auction.run({"alice": 100, "bob": 80, "charlie": 60})
# {'winner': 'alice', 'price': 80.0}  # Pays second-highest bid

# Check if a mechanism is incentive-compatible (truth-telling is optimal)
payoffs = np.array([[10, 0], [0, 10]])  # Type i values outcome i
transfers = np.array([0, 0])
is_incentive_compatible(payoffs, transfers)  # True

---

MCP Integration (for AI Agents)

RationalAgents exposes tools via Model Context Protocol:

# Run the MCP server
python -m rational_agents.mcp.server

Available tools for your AI agent:

• analyze_strategic_situation — Parse situation → optimal response
• update_beliefs — Bayesian belief updating from observations
• compute_equilibrium — Find Nash equilibria
• compute_fair_division — Shapley-based attribution
• design_mechanism — Create incentive-compatible rules

# Example: Agent updates beliefs about opponent
await mcp.call_tool("update_beliefs", {
    "prior": {"types": ["tough", "soft"], "probs": [0.5, 0.5]},
    "observation": "aggressive_offer",
    "likelihood_model": {
        "tough": {"aggressive_offer": 0.9, "fair_offer": 0.1},
        "soft": {"aggressive_offer": 0.2, "fair_offer": 0.8}
    }
})
# Returns: {"tough": 0.818, "soft": 0.182}

---

Module Reference

Currently Implemented

Module	Purpose	Status
rational_agents.games.strategic	Matrix games, Nash equilibria	✅ Complete
rational_agents.games.cooperative	Shapley values, COCO decomposition	✅ Complete
rational_agents.beliefs	Bayesian priors & updating	✅ Complete
rational_agents.mechanisms	Auctions, incentive compatibility	✅ Complete
rational_agents.mcp	MCP tools for AI agents	✅ Complete

Planned (Game Theory)

Module	Purpose	Status
rational_agents.games.extensive	Sequential games, game trees	🔜 v0.2
rational_agents.games.repeated	Repeated games, reputation	🔜 v0.2
rational_agents.games.bayesian	Incomplete information games	🔜 v0.2
rational_agents.reasoning.levelk	Level-k thinking, cognitive hierarchies	🔜 v0.3
rational_agents.learning	Fictitious play, regret minimization	🔜 v0.3

Planned (Beyond Game Theory)

Module	Purpose	Status
rational_agents.causal	Causal inference, do-calculus	🔮 v0.4+
rational_agents.probabilistic	Bayesian networks, credal sets	🔮 v0.4+
rational_agents.temporal	Planning, temporal logic	🔮 v0.5+
rational_agents.constraints	CSP, optimization	🔮 v0.5+

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        AI AGENT                             │
│  (LLM: understands context, communicates with humans)       │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Tools
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    RATIONAL AGENTS                          │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              REASONING MODULES                       │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │   │
│  │  │  games  │ │ beliefs │ │mechanism│ │ causal  │   │   │
│  │  │         │ │         │ │ design  │ │ (future)│   │   │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘   │   │
│  │       └───────────┴──────────┴───────────┘         │   │
│  └──────────────────────┬──────────────────────────────┘   │
│                         ▼                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 CORE PRIMITIVES                      │   │
│  │   • Probability distributions                        │   │
│  │   • Optimization solvers                             │   │
│  │   • Type-safe game representations                   │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

The COCO Decomposition

A unique feature: every game is decomposed into cooperative and competitive components (Kalai & Kalai, 2013).

from rational_agents.games import vendor_game

game = vendor_game()  # Classic pricing game

# At strategy profile (high_price, low_price):
game.get_potential_at_profile((0, 1))  # 100 — cooperative "pie"
game.get_zero_sum_at_profile((0, 1), 0)  # -100 — P1's competitive loss
game.get_zero_sum_at_profile((0, 1), 1)  # +100 — P2's competitive gain

This decomposition helps agents understand:

• How much value is being created vs. fought over
• When to cooperate vs. compete
• Fair divisions of jointly-created value

---

Foundational Papers

This library implements established mathematics. Key references:

Game Theory

• Nash, J. (1950). "Equilibrium Points in N-Person Games"
• Shapley, L. (1953). "A Value for N-Person Games"
• Harsanyi, J. (1967). "Games with Incomplete Information"
• Kalai, A. & Kalai, E. (2013). "Cooperation in Strategic Games Revisited"
• Myerson, R. (1981). "Optimal Auction Design"

Future Modules

• Pearl, J. (2009). "Causality: Models, Reasoning, and Inference"
• Koller & Friedman (2009). "Probabilistic Graphical Models"

---

Roadmap

v0.1 — Core Game Theory ← Current

• Strategic form games
• Nash equilibrium (support enumeration)
• Bayesian belief updating
• Shapley values, COCO decomposition
• Basic mechanism design
• MCP server

v0.2 — Sequential & Repeated Games

• Extensive form representation
• Backward induction solver
• Subgame perfect equilibrium
• Repeated game utilities
• Folk theorem applications

v0.3 — Advanced Strategic Reasoning

• Level-k thinking
• Cognitive hierarchies
• Fictitious play
• Counterfactual regret minimization (CFR)
• Opponent modeling

v0.4 — Beyond Game Theory

• Causal reasoning primitives
• Probabilistic inference
• Integration with game-theoretic modules

v1.0 — Unified Reasoning

• Automatic reasoning module selection
• Composable reasoning pipelines
• Production-ready API

---

Demo: Rational vs Naive Agent

from rational_agents import NegotiationReasoner
from rational_agents.beliefs import UniformPrior

# Setup: Agent negotiating salary
reasoner = NegotiationReasoner(
    my_reservation=80000,  # Walk away below this
    prior_on_opponent=UniformPrior(70000, 120000),  # Their budget
    discount_factor=0.95  # Time pressure
)

# They offer 75k
reasoner.observe_offer(75000)
print(reasoner.beliefs)  # Updated: they probably have low budget

# What should I counter?
optimal_counter = reasoner.compute_optimal_response()
print(optimal_counter)  # Based on math, not vibes

# Compare to naive LLM:
# LLM: "Based on typical negotiations, counter with 90k"
# RationalAgents: "Given their offer reveals budget ~85k, counter with 82k"

---

Contributing

We welcome contributions! Areas where help is especially valuable:

1. New game types — Implement games from the taxonomy
2. Solvers — Lemke-Howson, linear programming methods
3. Tests — More test cases from academic literature
4. Documentation — Examples and tutorials
5. New reasoning modules — Causal, probabilistic, temporal

# Run tests
pytest tests/

# Type checking
mypy src/rational_agents

# Formatting
black src/ tests/

---

License

MIT

---

Philosophy

"The rational agent doesn't hope for good outcomes. It computes them."

We believe the future of AI agents requires hybrid architectures: LLMs for understanding and communication, formal methods for reasoning.

RationalAgents is the reasoning layer — starting with game theory, expanding to encompass the full toolkit of mathematical rationality.

---