LiChat

Conversational AI agents that replace forms with natural dialogue

LiChat is a TypeScript library that transforms static forms into dynamic AI-powered conversations. Define your data requirements in JSON, and LiChat handles the rest—intelligent question sequencing, file processing with OCR, auto-extraction from documents, and flexible storage backends.

Traditional Form                    LiChat Conversation
┌─────────────────────┐            ┌─────────────────────────────────────┐
│ Name: [__________]  │            │ Agent: "Hi! I'm Sarah. What's your  │
│ Email: [_________]  │     →      │         name?"                      │
│ Resume: [Browse]    │            │ User:  "John Smith"                 │
│ [Submit]            │            │ Agent: "Nice! Can you share your    │
└─────────────────────┘            │         resume? I'll extract the    │
                                   │         details automatically."     │
                                   └─────────────────────────────────────┘

Key Features

• Configuration-driven — Define agents via JSON, no code changes needed
• Multimodal file processing — Resume parsing, ID validation, OCR, image analysis
• Auto-extraction — Upload a resume, auto-fill name/email/phone/skills
• Security-first — Prompt injection protection, session isolation, rate limiting
• Flexible storage — PostgreSQL, SQLite, webhooks with auto-schema creation
• Multiple interfaces — Web API, CLI, programmatic library

Quick Start

Installation

npm install lichat

Basic Usage

import Lichat from 'lichat';

const agent = new Lichat({
  name: "job_application",
  persona: "friendly HR assistant named Sarah",
  dataPoints: [
    { name: "name", type: "string", description: "Full name" },
    { name: "email", type: "email", description: "Email address" },
    { name: "resume", type: "resume", description: "Resume document" }
  ],
  rules: [],
  target: { type: "webhook", url: "https://api.example.com/applications" }
}, {
  apiKey: process.env.LLM_API_KEY,
  model: 'gpt-4'
});

// Start conversation
const greeting = await agent.getNextQuestion();
// → "Hi! I'm Sarah. What's your name?"

await agent.processResponse("John Smith");
const next = await agent.getNextQuestion();
// → "Nice to meet you John! What's your email?"

Run the Demo

git clone https://github.com/Skelf-Research/lichat.git
cd lichat
npm install
cp .env.example .env  # Add your LLM_API_KEY
npm run web           # Open http://localhost:3000

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              LiChat                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐              │
│  │   Security   │    │  Extraction  │    │   Planning   │              │
│  │   Gateway    │───▶│    Engine    │───▶│    Engine    │              │
│  │              │    │              │    │              │              │
│  │ • Injection  │    │ • LLM calls  │    │ • Question   │              │
│  │   detection  │    │ • Structured │    │   sequencing │              │
│  │ • Input      │    │   templates  │    │ • Progress   │              │
│  │   sanittic   │    │              │    │   tracking   │              │
│  └──────────────┘    └──────────────┘    └──────────────┘              │
│         │                   │                   │                       │
│         ▼                   ▼                   ▼                       │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐              │
│  │    File      │    │   Response   │    │   Storage    │              │
│  │  Processor   │    │  Generator   │    │    Layer     │              │
│  │              │    │              │    │              │              │
│  │ • OCR        │    │ • Persona    │    │ • PostgreSQL │              │
│  │ • Resume     │    │   adaptation │    │ • SQLite     │              │
│  │   parsing    │    │ • Template   │    │ • Webhooks   │              │
│  │ • Image      │    │   caching    │    │              │              │
│  │   analysis   │    │              │    │              │              │
│  └──────────────┘    └──────────────┘    └──────────────┘              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Core Components

| Component | Path | Purpose | |-----------|------|---------| | Lichat | src/index.ts | Main API facade | | ConversationEngine | src/engine/conversation.ts | Session & flow management | | FileProcessor | src/files/file-processor.ts | Multimodal document handling | | LLMClient | src/llm/client.ts | OpenAI-compatible API client | | WebServer | src/web/server.ts | Express.js REST API | | EmailProcessor | src/email/processor.ts | Email-to-lead extraction |

Configuration

Configurations are JSON files that define agent behavior.

{
  "name": "job_application",
  "persona": "friendly HR assistant named Sarah",
  "dataPoints": [
    {
      "name": "name",
      "type": "string",
      "description": "Applicant's full name"
    },
    {
      "name": "email",
      "type": "email",
      "description": "Email address"
    },
    {
      "name": "resume",
      "type": "resume",
      "description": "Resume document",
      "fileConfig": {
        "allowedTypes": ["pdf", "doc", "docx"],
        "maxSize": "10MB",
        "analysis": {
          "extractText": true,
          "extractData": ["name", "email", "phone", "skills"]
        },
        "processing": {
          "autoFill": true
        }
      }
    }
  ],
  "rules": [
    {
      "condition": "email must be valid format",
      "errorMessage": "Please provide a valid email"
    }
  ],
  "target": {
    "type": "postgresql",
    "connectionString": "postgresql://user:pass@localhost/db"
  }
}

Data Types

| Type | Description | |------|-------------| | string, number, boolean, date | Primitives | | email, phone, url | Validated formats | | multiline-text, json, array | Complex types | | resume | Auto-extracts name, email, phone, skills | | photo-id | Face detection, ID data extraction | | document, pdf | OCR, content analysis | | image | Object recognition, quality validation |

Storage Targets

PostgreSQL (auto-creates tables):

{ "type": "postgresql", "connectionString": "postgresql://..." }

SQLite (auto-creates tables):

{ "type": "sqlite", "path": "./data.db" }

Webhook (POSTs JSON payload):

{ "type": "webhook", "url": "https://api.example.com/leads" }

API Reference

Web Server Endpoints

Start a conversation:

POST /api/chat/start
Body: { "configuration": { ... } }
Response: { "sessionId": "abc123", "response": "Hi! I'm Sarah..." }

Send a message:

POST /api/chat
Body: { "sessionId": "abc123", "message": "John Smith" }
Response: { "response": "Nice to meet you John!", "isComplete": false }

Upload a file:

POST /api/upload/:sessionId/:dataPoint
Response: { "success": true, "extractedData": { "name": "...", "email": "..." } }

Get session state:

GET /api/session/:sessionId
Response: { "collectedData": { ... }, "isComplete": true }

Programmatic API

import Lichat, { Configuration } from 'lichat';

const config: Configuration = { /* ... */ };
const agent = new Lichat(config, { apiKey, model });

// Conversation flow
await agent.getNextQuestion();
await agent.processResponse("user input");
await agent.processFileUpload(file, 'resume');
agent.isDataCollectionComplete();
await agent.saveData();

CLI

# Interactive conversation
npm run cli configs/job_application.json

# Email processing mode
npm run cli configs/job_application.json email

Environment Variables

# Required
LLM_API_KEY=your_openai_api_key

# Optional
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4
PORT=3000
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=50MB
SESSION_TIMEOUT=1800000

Development

npm run build     # Compile TypeScript
npm run dev       # Development mode
npm run web       # Start web server
npm run cli       # Run CLI

License

MIT

Documentation | GitHub | Issues