Documentation

🔗 [GitHub Repository]

Directory Structure

LinkolnOS/
├── assets/
│   ├── disclaimer.jpg
│   ├── linkolnintro.jpg
│   └── projectintro.jpg
├── commands/
│   ├── adminActions.js
│   ├── adminCommands.js
│   ├── adminStateHelper.js
│   ├── adminVerification.js
│   ├── deleteAgent.js
│   ├── passwordManagement.js
│   └── userCommands.js
├── node_modules/        (installed dependencies)
├── .env                 (to be created by you) 
├── app.js
├── config.js
├── crawler.js
├── db.js
├── deeplinkWelcome.js
├── llm.js
├── package.json
├── package-lock.json
├── personality.json
├── projectCreation.js
├── README.md
├── resetAgent.js
├── stateManager.js
├── testllm.js
└── utils.js

Key Files

app.js

• Main entry point. Initializes the Telegram bot in polling mode and routes messages.

commands/ Contains modularized admin and user command logic:

• adminCommands.js (the router for admin tasks)

• adminActions.js (manages website add/remove/list)

• adminVerification.js (handles admin password checks)

• deleteAgent.js, passwordManagement.js, userCommands.js

crawler.js

• Fetches & extracts website content (axios + cheerio).

llm.js

• Integrates with large language models for dynamic responses.

stateManager.js

• Maintains project data, user states, and references to the PostgreSQL database.

resetAgent.js

• Resets the agent and sends the initial introduction message (linkolnintro.jpg).

utils.js

• Contains helper functions like withTyping to show a typing indicator.

Prerequisites & Dependencies

• Node.js (v14+ recommended)

• npm (or yarn)

• PostgreSQL (for conversation history, project names, etc.)

When you run npm install, it will fetch all required dependencies, including:

• axios for HTTP requests

• cheerio for HTML parsing

• pg (or another PostgreSQL client) for database interactions

• openai (if using GPT-based LLMs)

• request, request-promise, or similar libraries as needed

Note: The exact list of dependencies is in your package.json.

Configuration

Create a .env file in the project root. Below is an example reflecting your current variables:

# Telegram & LLM
TELEGRAM_BOT_TOKEN=
OPENAI_API_KEY=
LLM_PROVIDER=openai
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_MAX_TOKENS=500
OPENAI_TEMPERATURE=0.9

# Website Limits
MAX_WEBSITES=50

# PostgreSQL Configuration
DB_USER=postgres
DB_HOST=localhost
DB_NAME=postgres
DB_PASSWORD=
DB_PORT=5432

• TELEGRAM_BOT_TOKEN: The token for your Telegram bot.

• OPENAI_API_KEY: The API key for your LLM provider (e.g., OpenAI).

• LLM_PROVIDER: Set to openai (or another provider in the future).

• OPENAI_MODEL: Model name (e.g., gpt-3.5-turbo).

• OPENAI_MAX_TOKENS: Maximum tokens to generate in responses (default fallback: 150).

• OPENAI_TEMPERATURE: Controls creativity (0.0 = deterministic, 2.0 = highly creative).

• MAX_WEBSITES: Maximum number of websites an admin can add to the knowledge base.

• DB_USER, DB_HOST, DB_NAME, DB_PASSWORD, DB_PORT: PostgreSQL credentials. Make sure a PostgreSQL instance is running with these parameters.

Running the Bot

1. Install Dependencies

npm install

1. Start the Bot

node app.js

or

npm start

The bot will begin polling for updates on Telegram. You can then interact with it in your chosen Telegram client.

Usage & Workflow

/start

• Triggers the initial intro (resetAgent). If no project is set up, it guides you through creating a new project.

Admin Mode

• Tap “For Admin” to verify your password and access admin features (adding websites, removing websites, changing password, deleting agent, etc.).

User Mode

• Regular users ask questions about the project’s knowledge base. The bot crawls relevant websites (via crawler.js) and fuses that data with LLM-based context.

Deployment

Stable production deployment:

• Use webhooks instead of polling for improved efficiency and reliability. (codes are in webhooks)

• Use a hosting provider like Render, Railway, or AWS with HTTPS support.

• Use a process manager (e.g., PM2) to keep the bot running and automatically restart on crashes.

Future Enhancements

Advanced Logging

Add structured logging (e.g., Winston) to track admin/user actions more comprehensively.

File Upload Support

Integrate advanced features for reading PDFs, CSVs, or doc files.

Robust Security

Harden admin password policies and add role-based access if needed.

Webhook Migration

Switch from polling to webhooks for lower latency and resource usage.

Contributing

We welcome pull requests, feature suggestions, and bug reports. Feel free to fork the repository, create feature branches, and submit PRs.

License

MIT License

Acknowledgements

• Volaris Games for pioneering the idea of LinkolnOS.

• OpenAI for powering the LLM-based responses.

• Cheerio & Axios for streamlined web crawling.

• PostgreSQL for robust database management.

Closing Notes

This README is intended as a living document. You’re encouraged to add new sections or update existing ones as LinkolnOS evolves—whether you integrate new features, refine your PostgreSQL setup, or overhaul the admin flow.

Enjoy building with LinkolnOS!