mirror of
https://github.com/ruvnet/RuView
synced 2026-08-04 19:31:42 +00:00
rUv
407b46b206
Add ruvnet/midstream (AIMDS real-time inference) and ruvnet/sublinear-time-solver (sublinear optimization algorithms) as vendored dependencies under vendor/.
506 lines
14 KiB
Markdown
506 lines
14 KiB
Markdown
# Lean Agentic Learning System
|
|
|
|
## Revolutionary Live Stream Learning Framework
|
|
|
|
Welcome to the **Lean Agentic Learning System** - a groundbreaking approach to real-time learning that combines formal verification, autonomous agents, and adaptive stream processing.
|
|
|
|
## Table of Contents
|
|
|
|
- [Overview](#overview)
|
|
- [Core Innovations](#core-innovations)
|
|
- [Architecture](#architecture)
|
|
- [Getting Started](#getting-started)
|
|
- [Components](#components)
|
|
- [Examples](#examples)
|
|
- [API Reference](#api-reference)
|
|
- [Performance](#performance)
|
|
- [Contributing](#contributing)
|
|
|
|
## Overview
|
|
|
|
The Lean Agentic Learning System represents a new paradigm in machine learning that integrates:
|
|
|
|
1. **Lean Theorem Proving** - Mathematical rigor and formal verification
|
|
2. **Agentic AI** - Autonomous decision-making with goal-oriented behavior
|
|
3. **Stream Learning** - Real-time online adaptation from continuous data
|
|
4. **Knowledge Evolution** - Dynamic knowledge graphs that grow with experience
|
|
|
|
### Key Features
|
|
|
|
- ✅ **Formal Verification** - Every action can be proven safe and correct
|
|
- 🎯 **Autonomous Agents** - Self-directed learning and decision-making
|
|
- 📊 **Real-Time Adaptation** - Learn from streaming data without batch processing
|
|
- 🧠 **Knowledge Graphs** - Build and evolve structured knowledge dynamically
|
|
- ⚡ **Low Latency** - Process and learn from streams in real-time
|
|
- 🔒 **Type Safe** - Full Rust implementation with TypeScript client
|
|
- 🌐 **Multi-Language** - Rust core with TypeScript, Python bindings
|
|
|
|
## Core Innovations
|
|
|
|
### 1. Lean Formal Reasoning
|
|
|
|
Inspired by the Lean theorem prover, our system provides:
|
|
|
|
```rust
|
|
use midstream::{FormalReasoner, Theorem, Proof};
|
|
|
|
let mut reasoner = FormalReasoner::new();
|
|
|
|
// Add axioms
|
|
reasoner.add_axiom(Theorem {
|
|
statement: "Actions must not cause harm".to_string(),
|
|
confidence: 1.0,
|
|
tags: vec!["safety".to_string()],
|
|
..Default::default()
|
|
});
|
|
|
|
// Verify actions before execution
|
|
let proof = reasoner.verify_action(&action, &context).await?;
|
|
|
|
if proof.is_valid() {
|
|
// Safe to execute
|
|
execute_action(&action).await?;
|
|
}
|
|
```
|
|
|
|
**Benefits:**
|
|
- Provably safe agent behavior
|
|
- Mathematical guarantees on action correctness
|
|
- Explainable decision-making
|
|
- Verified knowledge accumulation
|
|
|
|
### 2. Agentic Loop (Plan-Act-Observe-Learn)
|
|
|
|
Our autonomous agent loop enables self-directed learning:
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Agentic Learning Loop │
|
|
├─────────────────────────────────────┤
|
|
│ │
|
|
│ 1. PLAN │
|
|
│ └─ Analyze context │
|
|
│ └─ Generate action candidates│
|
|
│ └─ Rank by expected reward│
|
|
│ │
|
|
│ 2. ACT │
|
|
│ └─ Verify action (formal proof) │
|
|
│ └─ Execute highest-value │
|
|
│ │
|
|
│ 3. OBSERVE │
|
|
│ └─ Collect outcomes │
|
|
│ └─ Measure actual reward │
|
|
│ │
|
|
│ 4. LEARN │
|
|
│ └─ Update policies │
|
|
│ └─ Refine knowledge graph │
|
|
│ └─ Adapt model weights │
|
|
│ │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```rust
|
|
use midstream::{AgenticLoop, LeanAgenticConfig, Context};
|
|
|
|
let mut agent = AgenticLoop::new(config);
|
|
let context = Context::new("session_001".to_string());
|
|
|
|
// PLAN
|
|
let plan = agent.plan(&context, "Get weather for Tokyo").await?;
|
|
|
|
// ACT
|
|
let action = agent.select_action(&plan).await?;
|
|
let observation = agent.execute(&action).await?;
|
|
|
|
// OBSERVE & LEARN
|
|
let reward = agent.compute_reward(&observation).await?;
|
|
agent.learn(LearningSignal { action, observation, reward }).await?;
|
|
```
|
|
|
|
### 3. Stream Learning
|
|
|
|
Unlike traditional batch learning, our system learns continuously:
|
|
|
|
```rust
|
|
use midstream::{StreamLearner, AdaptationStrategy};
|
|
|
|
let mut learner = StreamLearner::new(0.01); // Learning rate
|
|
|
|
// Process stream in real-time
|
|
for chunk in stream {
|
|
let entities = kg.extract_entities(&chunk).await?;
|
|
kg.update(entities).await?;
|
|
|
|
let action = agent.select_action(&context).await?;
|
|
let reward = execute_and_measure(&action).await?;
|
|
|
|
// Online learning - updates happen immediately
|
|
learner.update(&action, reward, &chunk).await?;
|
|
}
|
|
```
|
|
|
|
**Adaptation Strategies:**
|
|
|
|
1. **Immediate** - Update after every experience (fastest adaptation)
|
|
2. **Batched** - Update after N experiences (stable learning)
|
|
3. **Experience Replay** - Randomly replay past experiences (better generalization)
|
|
|
|
### 4. Dynamic Knowledge Graph
|
|
|
|
Knowledge evolves as the system learns:
|
|
|
|
```rust
|
|
use midstream::{KnowledgeGraph, Entity, Relation, EntityType};
|
|
|
|
let mut kg = KnowledgeGraph::new();
|
|
|
|
// Extract entities from streaming text
|
|
let entities = kg.extract_entities("Alice works at Google").await?;
|
|
|
|
// Entities found: ["Alice" (Person), "Google" (Organization)]
|
|
|
|
// Update graph
|
|
kg.update(entities).await?;
|
|
|
|
// Add relations
|
|
kg.add_relation(Relation {
|
|
subject: "alice_id".to_string(),
|
|
predicate: "works_at".to_string(),
|
|
object: "google_id".to_string(),
|
|
confidence: 0.9,
|
|
..Default::default()
|
|
});
|
|
|
|
// Query related entities
|
|
let related = kg.find_related("alice_id", max_depth: 2);
|
|
|
|
// Time-based facts
|
|
kg.add_temporal_fact(TemporalFact {
|
|
fact: "Weather is sunny".to_string(),
|
|
valid_from: now,
|
|
valid_until: Some(now + 3600),
|
|
confidence: 0.9,
|
|
});
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ Lean Agentic Learning System │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌─────────────────────┼─────────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ Formal │ │ Agentic │ │ Knowledge │
|
|
│ Reasoning │◄──►│ Loop │◄──►│ Graph │
|
|
│ Engine │ │ (P-A-O-L) │ │ & Store │
|
|
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────┐ │
|
|
└─────────►│ Stream │◄────────────┘
|
|
│ Learning │
|
|
└──────┬───────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ MidStream │
|
|
│ Integration │
|
|
└──────────────┘
|
|
```
|
|
|
|
### Component Responsibilities
|
|
|
|
| Component | Purpose | Key Features |
|
|
|-----------|---------|--------------|
|
|
| **Formal Reasoner** | Verify action safety | Axioms, inference rules, proof construction |
|
|
| **Agentic Loop** | Autonomous decision-making | Planning, execution, learning |
|
|
| **Knowledge Graph** | Dynamic knowledge | Entities, relations, temporal facts |
|
|
| **Stream Learner** | Online adaptation | Real-time updates, experience replay |
|
|
| **MidStream Integration** | Stream processing | LLM streaming, metrics, tool integration |
|
|
|
|
## Getting Started
|
|
|
|
### Installation
|
|
|
|
#### Rust
|
|
|
|
Add to `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
midstream = { git = "https://github.com/ruvnet/midstream" }
|
|
```
|
|
|
|
#### TypeScript/JavaScript
|
|
|
|
```bash
|
|
npm install @midstream/lean-agentic
|
|
```
|
|
|
|
#### Python
|
|
|
|
```bash
|
|
pip install lean-agentic
|
|
```
|
|
|
|
### Quick Start
|
|
|
|
#### Rust
|
|
|
|
```rust
|
|
use midstream::{LeanAgenticSystem, LeanAgenticConfig, AgentContext};
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
// Create system
|
|
let config = LeanAgenticConfig::default();
|
|
let system = LeanAgenticSystem::new(config);
|
|
|
|
// Process stream chunk
|
|
let context = AgentContext::new("session_001".to_string());
|
|
let result = system.process_stream_chunk(
|
|
"Hello, what's the weather?",
|
|
context,
|
|
).await?;
|
|
|
|
println!("Action: {}", result.action.description);
|
|
println!("Reward: {}", result.reward);
|
|
println!("Verified: {}", result.verified);
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
#### TypeScript
|
|
|
|
```typescript
|
|
import { LeanAgenticClient } from '@midstream/lean-agentic';
|
|
|
|
const client = new LeanAgenticClient('http://localhost:8080');
|
|
const context = client.createContext('session_001');
|
|
|
|
const result = await client.processChunk(
|
|
'Hello, what is the weather?',
|
|
context
|
|
);
|
|
|
|
console.log('Action:', result.action.description);
|
|
console.log('Reward:', result.reward);
|
|
console.log('Verified:', result.verified);
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Complete Examples
|
|
|
|
1. **[Rust: Lean Agentic Streaming](./examples/lean_agentic_streaming.rs)**
|
|
- Full integration with MidStream
|
|
- Real-time LLM processing
|
|
- Knowledge graph evolution
|
|
|
|
2. **[TypeScript: Chat Assistant](./lean-agentic-js/examples/chat.ts)**
|
|
- Interactive conversation
|
|
- Preference learning
|
|
- Context management
|
|
|
|
3. **[Python: Data Analysis](./python/examples/analysis.py)**
|
|
- Stream analysis
|
|
- Pattern recognition
|
|
- Adaptive predictions
|
|
|
|
### Run Examples
|
|
|
|
```bash
|
|
# Rust
|
|
cargo run --example lean_agentic_streaming
|
|
|
|
# TypeScript
|
|
cd lean-agentic-js
|
|
npm run example:chat
|
|
|
|
# Python
|
|
cd python
|
|
python examples/analysis.py
|
|
```
|
|
|
|
## Performance
|
|
|
|
### Benchmarks
|
|
|
|
Tested on: AMD Ryzen 9 / 32GB RAM
|
|
|
|
| Operation | Latency | Throughput |
|
|
|-----------|---------|------------|
|
|
| Process chunk | 2-5 ms | 200-500 chunks/sec |
|
|
| Verify action | 1-2 ms | 500-1000 actions/sec |
|
|
| Update knowledge graph | 3-7 ms | 150-300 updates/sec |
|
|
| Online learning update | 1-3 ms | 300-1000 updates/sec |
|
|
| End-to-end (P-A-O-L) | 10-20 ms | 50-100 loops/sec |
|
|
|
|
### Scalability
|
|
|
|
- **Concurrent sessions**: 1000+ sessions on single node
|
|
- **Knowledge graph size**: Tested with 1M+ entities
|
|
- **Stream throughput**: 10K+ messages/second
|
|
- **Learning stability**: Convergence in <1000 iterations
|
|
|
|
## Configuration
|
|
|
|
### System Configuration
|
|
|
|
```rust
|
|
LeanAgenticConfig {
|
|
// Verify all actions with formal proofs
|
|
enable_formal_verification: true,
|
|
|
|
// Learning rate (0.0 - 1.0)
|
|
learning_rate: 0.01,
|
|
|
|
// Max depth for action planning
|
|
max_planning_depth: 5,
|
|
|
|
// Threshold for action execution (0.0 - 1.0)
|
|
action_threshold: 0.7,
|
|
|
|
// Enable multi-agent collaboration
|
|
enable_multi_agent: true,
|
|
|
|
// Knowledge graph update frequency
|
|
kg_update_freq: 100,
|
|
}
|
|
```
|
|
|
|
### Adaptation Strategies
|
|
|
|
```rust
|
|
// Immediate adaptation (fastest)
|
|
AdaptationStrategy::Immediate
|
|
|
|
// Batched updates (stable)
|
|
AdaptationStrategy::Batched { batch_size: 32 }
|
|
|
|
// Experience replay (best generalization)
|
|
AdaptationStrategy::ExperienceReplay { replay_size: 16 }
|
|
```
|
|
|
|
## Advanced Topics
|
|
|
|
### Multi-Agent Systems
|
|
|
|
```rust
|
|
let config = LeanAgenticConfig {
|
|
enable_multi_agent: true,
|
|
..Default::default()
|
|
};
|
|
|
|
// Multiple agents can share knowledge graph
|
|
// Collaborative learning and decision-making
|
|
```
|
|
|
|
### Custom Reasoning Rules
|
|
|
|
```rust
|
|
let mut reasoner = FormalReasoner::new();
|
|
|
|
reasoner.add_rule(InferenceRule {
|
|
name: "custom_rule".to_string(),
|
|
premises: vec!["A".to_string(), "B".to_string()],
|
|
conclusion: "C".to_string(),
|
|
});
|
|
```
|
|
|
|
### Knowledge Graph Queries
|
|
|
|
```rust
|
|
// Query by type
|
|
let people = kg.query_entities(EntityType::Person);
|
|
|
|
// Find related entities
|
|
let related = kg.find_related("entity_id", max_depth: 3);
|
|
|
|
// Temporal queries
|
|
let facts_now = kg.get_facts_at_time(timestamp);
|
|
|
|
// Semantic similarity
|
|
let similarity = kg.compute_similarity("entity1", "entity2");
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Rust API
|
|
|
|
See [docs.rs](https://docs.rs/midstream) for complete API documentation.
|
|
|
|
### TypeScript API
|
|
|
|
See [TypeScript API](./lean-agentic-js/docs/API.md) for complete reference.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Rust tests
|
|
cargo test
|
|
|
|
# TypeScript tests
|
|
cd lean-agentic-js
|
|
npm test
|
|
|
|
# Integration tests
|
|
cargo test --test integration
|
|
```
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md)
|
|
|
|
### Areas for Contribution
|
|
|
|
- Additional reasoning rules
|
|
- New adaptation strategies
|
|
- Enhanced entity extraction
|
|
- Performance optimizations
|
|
- Documentation improvements
|
|
- More examples
|
|
|
|
## License
|
|
|
|
MIT License - See [LICENSE](./LICENSE)
|
|
|
|
## Citation
|
|
|
|
If you use this system in research, please cite:
|
|
|
|
```bibtex
|
|
@software{lean_agentic_2025,
|
|
title = {Lean Agentic Learning System},
|
|
author = {MidStream Contributors},
|
|
year = {2025},
|
|
url = {https://github.com/ruvnet/midstream}
|
|
}
|
|
```
|
|
|
|
## Support
|
|
|
|
- **Issues**: https://github.com/ruvnet/midstream/issues
|
|
- **Discussions**: https://github.com/ruvnet/midstream/discussions
|
|
- **Documentation**: https://docs.midstream.dev
|
|
|
|
## Acknowledgments
|
|
|
|
This system draws inspiration from:
|
|
- Lean Theorem Prover
|
|
- Actor-Critic Reinforcement Learning
|
|
- Online Learning Theory
|
|
- Knowledge Graph Embeddings
|
|
- Real-time Stream Processing
|
|
|
|
---
|
|
|
|
**Built with ❤️ by the MidStream team**
|