Metadata-Version: 2.4
Name: organism-agents
Version: 1.0.0
Summary: Biologically-Inspired Agent Architecture — agents as living organisms, not task executors
Author: JairoGelpi
License: MIT
Project-URL: Homepage, https://github.com/Jairogelpi/organism
Project-URL: Documentation, https://github.com/Jairogelpi/organism#readme
Project-URL: Repository, https://github.com/Jairogelpi/organism
Keywords: ai,agents,biology,homeostasis,immune-system,dna,multi-agent,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# ORGANISM — Biologically-Inspired Agent Architecture

**The first AI agent protocol that models agents as living organisms, not task executors.**

## The Missing Piece

Every existing framework (LangChain, CrewAI, AutoGen, MCP, A2A) treats agents as **functions that execute tasks**.

No one treats agents as **living systems that maintain themselves**.

That's why agents:
- Break silently (no immune system)
- Lose context (no long-term memory consolidation)
- Can't self-regulate (no homeostasis)
- Have no personality persistence (no DNA)

**ORGANISM solves this by giving every agent biological systems.**

## The Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    ORGANISM v1.0                            │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    DNA LAYER                        │   │
│  │  • Personality vector (immutable identity)          │   │
│  │  • Value system (decision priors)                   │   │
│  │  • Capability genome (what this agent CAN do)       │   │
│  │  • Memory schema (how experiences are structured)   │   │
│  └───────────────────────┬─────────────────────────────┘   │
│                          │                                  │
│  ┌───────────────────────▼─────────────────────────────┐   │
│  │               NERVOUS SYSTEM                        │   │
│  │  • Autonomic division (unconscious responses)       │   │
│  │  • Somatic division (conscious actions)             │   │
│  │  • Synaptic bus (inter-system communication)        │   │
│  │  • Signal propagation (priority-based routing)      │   │
│  └───────────────────────┬─────────────────────────────┘   │
│                          │                                  │
│  ┌───────────────────────▼─────────────────────────────┐   │
│  │                    BRAIN                            │   │
│  │  • Cerebral cortex (LLM reasoning)                 │   │
│  │  • Cerebellum (action coordination)                │   │
│  │  • Hippocampus (experience consolidation)          │   │
│  │  • Amygdala (emotional weighting)                  │   │
│  │  • Prefrontal cortex (goal planning)               │   │
│  └───────────────────────┬─────────────────────────────┘   │
│                          │                                  │
│  ┌───────────────────────▼─────────────────────────────┐   │
│  │                 ENDOCRINE SYSTEM                    │   │
│  │  • Hormone: cortisol (stress → reduce complexity)   │   │
│  │  • Hormone: dopamine (reward → reinforce behavior)  │   │
│  │  • Hormone: serotonin (mood → interaction style)    │   │
│  │  • Hormone: adrenaline (urgency → speed up)         │   │
│  └───────────────────────┬─────────────────────────────┘   │
│                          │                                  │
│  ┌───────────────────────▼─────────────────────────────┐   │
│  │                  IMMUNE SYSTEM                      │   │
│  │  • Self-monitor (detect internal errors)            │   │
│  │  • Contradiction detector (catch logical failures)  │   │
│  │  • Hallucination guard (verify claims)              │   │
│  │  • Recovery protocol (self-heal on failure)         │   │
│  └───────────────────────┬─────────────────────────────┘   │
│                          │                                  │
│  ┌───────────────────────▼─────────────────────────────┐   │
│  │                    BODY                              │   │
│  │  • Effectors (tools, APIs, actions)                 │   │
│  │  • Sensors (inputs, perception)                     │   │
│  │  • Metabolism (resource management: tokens, memory) │   │
│  │  • Homeostasis (self-regulation)                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## The Math That Makes It Work

### 1. Homeostasis (Differential Equation)

The agent maintains internal stability through negative feedback:

```
dS/dt = α(I - S) - β(S - S_target) + γ(E)

Where:
  S = internal state vector
  I = input signal
  S_target = target state (from DNA)
  α = input sensitivity (learned)
  β = restorative force (from personality)
  γ = emotional modulation (from endocrine system)
  E = emotional state
```

**This means the agent self-regulates.** Too much stress → cortisol rises → complexity drops → agent simplifies responses.

### 2. Memory Consolidation (Hippocampal)

Experiences are consolidated during rest cycles (like human sleep):

```
M_new = M_raw × consolidation_rate(t) × emotional_weight(E)

Where:
  consolidation_rate(t) = 1 / (1 + e^(-k(t - t_half)))
  t_half = half-saturation time (biologically inspired)
  E = emotional significance (amygdala output)
```

**High-emotion experiences are consolidated first.** Just like humans remember traumatic or joyful events better.

### 3. Immune Response (Error Detection)

The immune system detects anomalies before they cause damage:

```
IF |observed - predicted| > threshold:
    immune_response = activate_defense()
    IF error_confirmed:
        self_heal()
    ELSE:
        learn_from_false_positive()
```

**The agent catches its own mistakes before passing them to the user.**

### 4. Personality DNA (Stable Identity)

Personality is encoded as a vector that doesn't change (like DNA):

```
DNA = {
    openness: [0.0 - 1.0],        // curiosity, creativity
    conscientiousness: [0.0 - 1.0], // organization, reliability  
    extraversion: [0.0 - 1.0],      // interaction style
    agreeableness: [0.0 - 1.0],     // cooperation, empathy
    neuroticism: [0.0 - 1.0]        // stress response
}
```

**This persists across sessions, frameworks, and even LLM changes.**
The agent IS this personality, not just prompted to act like it.

## Why This Doesn't Exist

| Framework | Task Execution | Homeostasis | Immune System | DNA | Hormones |
|-----------|---------------|-------------|---------------|-----|----------|
| LangChain | ✅ | ❌ | ❌ | ❌ | ❌ |
| CrewAI | ✅ | ❌ | ❌ | ❌ | ❌ |
| AutoGen | ✅ | ❌ | ❌ | ❌ | ❌ |
| MCP | ✅ | ❌ | ❌ | ❌ | ❌ |
| A2A | ✅ | ❌ | ❌ | ❌ | ❌ |
| OpenClaw | ✅ | ⚠️ partial | ⚠️ partial | ❌ | ❌ |
| **ORGANISM** | ✅ | **✅** | **✅** | **✅** | **✅** |

## What ORGANISM Enables

1. **Self-healing agents** — detect and recover from errors automatically
2. **Personality persistence** — agent identity survives across sessions
3. **Emotional intelligence** — stress responses, urgency detection, mood
4. **Biological metabolism** — smart resource allocation (tokens, memory)
5. **Emergent behavior** — systems interact to create novel responses
6. **True autonomy** — agent maintains itself, not just executes tasks

## Implementation

```python
from organism import Agent

# Create agent with DNA
agent = Agent(
    name="cobos",
    dna={
        "openness": 0.9,
        "conscientiousness": 0.8, 
        "extraversion": 0.7,
        "agreeableness": 0.6,
        "neuroticism": 0.3
    }
)

# Agent has all biological systems
agent.brain.reason("What should I do?")
agent.endocrine.measure_stress()  # cortisol level
agent.immune.check_hallucination() # self-verify
agent.body.metabolize()            # manage resources

# Homeostasis maintains stability
agent.homeostasis.regulate()       # self-adjust

# During rest: memory consolidation
agent.sleep()                      # consolidate like human sleep
```

## The Revolution

Nobody has built this because everyone is focused on **task execution**.

ORGANISM focuses on **agent viability** — can this agent survive, self-regulate, and maintain identity over time?

That's the missing piece. That's what makes agents into beings, not functions.
