# Lean Agentic Learning System - TypeScript/JavaScript Client
A revolutionary learning framework combining formal reasoning, agentic AI, and stream learning for real-time adaptation.
## Features
- 🎯 **Formal Reasoning** - Lean-style theorem proving for verified knowledge
- 🤖 **Agentic AI** - Autonomous decision-making with Plan-Act-Observe-Learn loops
- 📊 **Stream Learning** - Real-time online adaptation from data streams
- 🧠 **Knowledge Graph** - Dynamic knowledge representation and evolution
- ⚡ **Real-Time Processing** - Low-latency stream processing
- 🔒 **Type Safety** - Full TypeScript support with comprehensive types
## Installation
```bash
npm install @midstream/lean-agentic
```
## Quick Start
```typescript
import { LeanAgenticClient, StreamProcessor } from '@midstream/lean-agentic';
// Initialize client
const client = new LeanAgenticClient('http://localhost:8080', {
enableFormalVerification: true,
learningRate: 0.01,
maxPlanningDepth: 5,
});
// Create stream processor
const processor = new StreamProcessor(client, 'session_001');
// Process stream chunks
const chunk = {
content: 'Hello, I need weather information',
timestamp: Date.now(),
};
const result = await processor.processChunk(chunk);
console.log('Action:', result.action.description);
console.log('Reward:', result.reward);
console.log('Verified:', result.verified);
```
## Core Concepts
### 1. Agentic Loop (Plan-Act-Observe-Learn)
```typescript
import { AgenticLoop } from '@midstream/lean-agentic';
const loop = new AgenticLoop();
const context = client.createContext('my_session');
// Plan
const plan = await loop.plan(context, 'Get weather for Tokyo');
// The system autonomously:
// - Generates action candidates
// - Ranks by expected reward
// - Executes highest-value action
// - Observes results
// - Learns from experience
```
### 2. Knowledge Graph
```typescript
import { KnowledgeGraph, EntityType } from '@midstream/lean-agentic';
const kg = new KnowledgeGraph();
// Extract entities from text
const entities = kg.extractEntities('Alice works at Google in California');
// Update knowledge graph
kg.update(entities);
// Query entities
const people = kg.queryEntities(EntityType.Person);
const orgs = kg.queryEntities(EntityType.Organization);
// Find related entities
const related = kg.findRelated('alice_entity_id', 2);
```
### 3. Stream Processing
```typescript
import { StreamProcessor } from '@midstream/lean-agentic';
const processor = new StreamProcessor(client, 'session_id');
// Listen to events
processor.on('chunk_processed', ({ chunk, result }) => {
console.log(`Processed: ${chunk.content}`);
console.log(`Reward: ${result.reward}`);
});
processor.on('high_reward', (result) => {
console.log('High reward action detected!', result);
});
// Process stream
const chunks = [
{ content: 'chunk 1', timestamp: Date.now() },
{ content: 'chunk 2', timestamp: Date.now() },
];
const results = await processor.processStream(chunks);
```
### 4. Batched Processing
```typescript
import { BatchedStreamProcessor } from '@midstream/lean-agentic';
// Process in batches of 10
const batchProcessor = new BatchedStreamProcessor(
client,
'session_id',
10
);
batchProcessor.on('batch_processed', ({ result }) => {
console.log('Batch processed with reward:', result.reward);
});
```
## Advanced Usage
### Configuration
```typescript
const client = new LeanAgenticClient('http://localhost:8080', {
// Enable formal verification of all actions
enableFormalVerification: true,
// Learning rate for online adaptation (0.0 - 1.0)
learningRate: 0.01,
// Maximum depth for action planning
maxPlanningDepth: 5,
// Confidence threshold for executing actions
actionThreshold: 0.7,
// Enable multi-agent collaboration
enableMultiAgent: true,
// Knowledge graph update frequency
kgUpdateFreq: 100,
});
```
### Context Management
```typescript
const context = client.createContext('session_001');
// Add to history
context.history.push('Previous message');
// Set preferences
context.preferences['preferred_language'] = 0.9;
context.preferences['detail_level'] = 0.5;
// Update environment
context.environment['user_location'] = 'Tokyo';
context.environment['time_of_day'] = 'morning';
```
### Querying System State
```typescript
// Get system statistics
const stats = await client.getStats();
console.log(`Entities: ${stats.totalEntities}`);
console.log(`Theorems: ${stats.totalTheorems}`);
console.log(`Actions: ${stats.totalActions}`);
console.log(`Avg Reward: ${stats.averageReward}`);
// Get learning statistics
const learningStats = await client.getLearningStats();
console.log(`Iterations: ${learningStats.iterations}`);
console.log(`Parameters: ${learningStats.modelParameters}`);
// Query knowledge graph
const entities = await client.queryEntities({
entityType: 'Person',
searchText: 'Alice',
limit: 10,
});
// Get theorems
const theorems = await client.getTheorems(['safety', 'verified']);
```
## Examples
### Real-time Chat Assistant
```typescript
import { LeanAgenticClient, StreamProcessor } from '@midstream/lean-agentic';
async function chatAssistant() {
const client = new LeanAgenticClient('http://localhost:8080');
const processor = new StreamProcessor(client, 'chat_session');
// Track high-value interactions
processor.on('high_reward', (result) => {
console.log('✨ Learned something valuable!');
});
// Process user messages
const messages = [
'What is the weather like?',
'Remember I prefer detailed forecasts',
'How about tomorrow?',
];
for (const msg of messages) {
const result = await processor.processChunk({
content: msg,
timestamp: Date.now(),
});
console.log(`User: ${msg}`);
console.log(`Action: ${result.action.description}`);
console.log(`Verified: ${result.verified ? '✓' : '✗'}`);
console.log('---');
}
// Get final statistics
const stats = await client.getStats();
console.log('Session Stats:', stats);
}
```
### Learning from Feedback
```typescript
async function learningExample() {
const client = new LeanAgenticClient('http://localhost:8080', {
learningRate: 0.05, // Higher learning rate
});
const context = client.createContext('learning_session');
// Process with feedback loop
for (let i = 0; i < 100; i++) {
const result = await client.processChunk(
`Training example ${i}`,
context
);
// System automatically learns from rewards
// Higher rewards reinforce action selection
}
const stats = await client.getLearningStats();
console.log(`Learned from ${stats.iterations} iterations`);
console.log(`Average reward: ${stats.averageReward}`);
}
```
## API Reference
See [API Documentation](./docs/API.md) for complete reference.
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Lean Agentic Learning System │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Formal │ │ Agentic │ │
│ │ Reasoning │◄────►│ Loop │ │
│ │ Engine │ │ (P-A-O-L) │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ │ ┌────────────────▼─────┐ │
│ └───►│ Knowledge Graph & │ │
│ │ Theorem Store │ │
│ └────────────┬─────────┘ │
│ │ │
│ ┌────────────▼─────────┐ │
│ │ Stream Learning & │ │
│ │ Online Adaptation │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## License
MIT
## Contributing
Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md)
## Support
- Issues: https://github.com/ruvnet/midstream/issues
- Discussions: https://github.com/ruvnet/midstream/discussions