levtor/README.md

Levtor — a smart, fuzzy, AI-powered chat command handler and guardian for wallets and AI integration.

# Levtor

**Levtor** — a smart, fuzzy, AI-powered chat command handler and guardian for wallets and AI integration.

---

## Features

- Command registration with optional parameters  
- Fuzzy matching using Levenshtein distance  
- Middleware support for preprocessing (sanitization, toxic word filtering, etc.)  
- Lifecycle hooks (before, after, onError, onSuccess)  
- Context and dependency injection support  
- Command caching and debouncing  
- Optional AI response formatting functions  
- Written in TypeScript with full typings

---

## Installation

```bash
bun install
```

---

## Usage

```ts
import { Levtor } from 'levtor';

const levtor = new Levtor({
  // optional dependencies and options here
});

levtor.usePreprocessor(async (msg) => {
  // sanitize or filter message
  return msg.trim().toLowerCase();
});

levtor.registerCommand({
  name: 'send',
  aliases: ['snd', 'sendt'],
  description: 'Send tokens from one wallet to another',
  execute: async (args, context) => {
    // your command logic
  }
});

const response = await levtor.handleMessage('!send 5 BTC to 0xABC123');
console.log(response);
```

---

## Tests

Run tests with:

```bash
bun run test
```

To build the project:

```bash
bun run build
```

---

## License

MIT

---

## TODO / Roadmap

- [ ] Stronger TypeScript types for context and dependencies (avoid `any`)
- [ ] Async/dynamic command registration (e.g., from DB or remote)
- [ ] Advanced fuzzy matching (configurable threshold, Levenshtein, etc.)
- [ ] Command unregistration/removal at runtime
- [ ] Built-in help command or command introspection/listing
- [ ] Middleware/preprocessor short-circuiting (block/return custom response)
- [ ] Built-in logging/debug utilities
- [ ] Per-user or per-command rate limiting/throttling
- [ ] More realistic AI formatting (LLM integration, plugin interface)
- [ ] Dual ESM/CJS packaging and npm `exports` field
- [ ] Add license file and contribution guidelines
- [ ] More real-world usage examples and advanced patterns in README
- [ ] Granular/custom error handling per command or error type
- [ ] More edge-case and error-path test coverage