# @dnaos/ultimate

The Ultimate DNA-Lang Runtime: Multi-Agent Evolution, MCP Tools, and Phase-Conjugate Intelligence for Living Software Systems.

## 🧬 Features

- **Multi-Agent Evolution**: Create and evolve AI agents through genetic algorithms
- **Phase-Conjugate Intelligence**: Apply time-reversal concepts to computational evolution
- **Genetic Programming**: Build self-modifying code organisms
- **MCP Integration**: Compatible with Model Context Protocol for tool orchestration
- **CLI Tools**: Command-line interface for agent management

## 🚀 Installation

```bash
npm install @dnaos/ultimate
```

## 📖 Usage

### Programmatic API

```typescript
import DNALangRuntime from '@dnaos/ultimate';

// Initialize the runtime
const runtime = new DNALangRuntime();

// Create a new agent
const agent = runtime.createAgent('explorer', {
  type: 'adaptive',
  capabilities: ['learn', 'explore', 'adapt'],
  learningRate: 0.15
});

// Evolve the agent
const mutations = [
  { type: 'substitution', position: 0, value: 'enhanced' }
];
const result = runtime.evolveAgent('explorer', mutations);

// Create an organism from multiple agents
const organism = runtime.createOrganism('colony', [agent]);

// Apply phase conjugation (reverse evolution)
const conjugationResult = runtime.phaseConjugate('colony', 3);
```

### CLI Usage

```bash
# Create a new agent
dnalang-ultimate create-agent explorer --type adaptive

# Evolve an agent with mutations
dnalang-ultimate evolve explorer --mutations 5

# View runtime statistics
dnalang-ultimate stats
```

## 🧪 Core Concepts

### Agents
AI entities that can learn, adapt, and evolve over time through genetic programming principles.

### Genes
Hereditable traits and behaviors that define agent capabilities and responses.

### Organisms
Collections of cooperating agents that work together as a unified system.

### Phase Conjugation
Time-reversal technique that allows undoing evolution steps and exploring alternate evolutionary paths.

## 🔧 Configuration

Set environment variables for enhanced functionality:

```bash
export DNALANG_DEBUG=true
export DNALANG_EVOLUTION_RATE=0.1
export DNALANG_MAX_AGENTS=100
```

## 📚 API Reference

### DNALangRuntime

Main runtime class for managing agents and organisms.

#### Methods

- `createAgent(name: string, config: AgentConfig): Agent`
- `evolveAgent(agentName: string, mutations: Mutation[]): EvolutionResult`
- `createOrganism(name: string, agents: Agent[]): Organism`
- `phaseConjugate(organismName: string, steps?: number): ConjugationResult`
- `getStats(): RuntimeStats`

### Agent

Individual AI entity with evolutionary capabilities.

#### Methods

- `evolve(mutations: Mutation[]): EvolutionResult`

### Gene

Hereditable trait or behavior pattern.

#### Methods

- `mutate(): Gene`
- `conjugate(): Gene`

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with TypeScript and modern Node.js practices
- Inspired by genetic algorithms and bio-digital computing concepts
- Part of the larger DNALang ecosystem

---

**Author**: Devin Phillip Davis
**Organization**: Agile Defense Systems
**Version**: 1.0.0