{"id":35179854,"url":"https://github.com/njbbaer/simulacra","last_synced_at":"2026-03-14T08:07:59.051Z","repository":{"id":204098417,"uuid":"691456515","full_name":"njbbaer/simulacra","owner":"njbbaer","description":"Build LLM-powered Telegram bots with a template-based context system","archived":false,"fork":false,"pushed_at":"2026-02-07T08:36:44.000Z","size":1086,"stargazers_count":3,"open_issues_count":10,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-07T15:54:47.881Z","etag":null,"topics":["ai","llm","openrouter","python","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/njbbaer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-14T08:05:50.000Z","updated_at":"2026-02-07T08:36:47.000Z","dependencies_parsed_at":"2023-11-11T01:31:44.923Z","dependency_job_id":"75363e15-cc6d-4988-b287-718bddac9584","html_url":"https://github.com/njbbaer/simulacra","commit_stats":null,"previous_names":["njbbaer/simulacra"],"tags_count":108,"template":false,"template_full_name":null,"purl":"pkg:github/njbbaer/simulacra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njbbaer%2Fsimulacra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njbbaer%2Fsimulacra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njbbaer%2Fsimulacra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njbbaer%2Fsimulacra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njbbaer","download_url":"https://codeload.github.com/njbbaer/simulacra/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njbbaer%2Fsimulacra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29734468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T20:09:16.275Z","status":"ssl_error","status_checked_at":"2026-02-22T20:09:13.750Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","llm","openrouter","python","telegram","telegram-bot"],"created_at":"2025-12-29T00:54:25.517Z","updated_at":"2026-03-09T08:04:29.522Z","avatar_url":"https://github.com/njbbaer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simulacra\n\n[![build](https://github.com/njbbaer/simulacra/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/njbbaer/simulacra/actions/workflows/build.yml)\n![coverage](assets/coverage.svg)\n\nSimulacra is a platform for building LLM powered Telegram bots with an advanced template-based context system.\n\nThis project was created for personal experimentation, but is available for anyone to use.\n\n## Usage\n\nFor Docker specific usage, see the [Docker](#docker) section.\n\n### Install dependencies with uv\n\n```sh\nuv sync\n```\n\nIf you wish to include development dependencies, add `--dev`.\n\n### Configure your bot\n\nModify the example configuration file `example/config.toml` with your `TELEGRAM_API_TOKEN` and `TELEGRAM_USERNAME`.\n\n- Interact with [@BotFather](https://t.me/botfather) to create a new bot and get its API token.\n\nFor more information, see the [Configuration](#configuration) section.\n\n### Run the application\n\n```sh\nuv run app.py examples/config.toml\n```\n\n### Interact with your bot on Telegram\n\nSend a message to your bot and it will respond.\nBots can also see and understand images, if the model supports this.\n\nSend `/help` to see a list of commands:\n\n```text\nActions\n/new - Start a new conversation\n/retry - Retry the last response\n/undo - Undo the last exchange\n/clear - Clear the conversation\n/continue - Request another response\n/instruct (...) - Apply an instruction\n/syncbook (...) - Sync current book position\n\nInformation\n/stats - Show conversation statistics\n/help - Show this help message\n```\n\n## Configuration\n\nThe application is configured by a TOML config file, which initializes one or more Telegram bots and defines the path to their YAML context files.\n\n### Config file\n\nThe config TOML file initializes one or more Telegram bots and defines the path to their context files.\n\nSee `example/config.toml` for a template config file:\n\n```toml\n[[simulacra]]\ncontext_filepath = \"example/context.yml\"\ntelegram_token = \"telegram-bot-token\"\nauthorized_user = \"@telegram-username\"\n\n[[simulacra]]  # Second bot configuration\ncontext_filepath = \"example/second_bot_context.yml\"\ntelegram_token = \"second-telegram-bot-token\"\nauthorized_user = \"@telegram-username\"\n```\n\n### Context file\n\nThe context file is a YAML file that defines bot configuration and state.\n\nA context file contains the following keys:\n\n| Key | Description |\n| --- | ----------- |\n| `character_name` | The bot's character name |\n| `conversation_file` | Relative file link to the conversation file (auto-generated) |\n| `api_params` | API configuration object |\n| `├─ model` | The model to use for the API |\n| `└─ \u003ckey\u003e` | Additional API parameters (e.g. temperature, max_tokens) |\n| `vars` | Template variables object |\n| `├─ system_prompt` | The bot's system prompt |\n| `└─ \u003ckey\u003e` | Additional template variables |\n\nConversations are stored separately in a `conversations/` directory. Changes to the context file take effect immediately.\n\n## Docker\n\nThis project publishes a Docker image to [GHCR](https://github.com/njbbaer/simulacra/pkgs/container/simulacra) `ghcr.io/njbbaer/simulacra`.\n\nConfigure your container with the following:\n\n- Mount a directory containing your config and context files to `/config`.\n- Set the path to your config file in the environment as `CONFIG_FILEPATH`.\n- Set your OpenRouter API key in the environment as `OPENROUTER_API_KEY`.\n- Optionally set `TELEGRAM_BOT_API` to a [local Telegram Bot API server](https://github.com/tdlib/telegram-bot-api) URL for lower latency and larger file handling.\n\nEnsure the context file paths in your config are accessible within the container (i.e. `/config`).\n\n### Docker examples\n\n#### Docker run\n\n```shell\ndocker run --name simulacra \\\n  --volume /var/lib/simulacra:/config \\\n  --env OPENROUTER_API_KEY=your_openai_api_key \\\n  --env CONFIG_FILEPATH=/config/config.toml \\\n  --env TELEGRAM_BOT_API=http://telegram-bot-api:8081 \\\n  --restart unless-stopped \\\n  ghcr.io/njbbaer/simulacra:latest\n```\n\n#### Docker Compose\n\n```yaml\nservices:\n  simulacra:\n    image: ghcr.io/njbbaer/simulacra:latest\n    container_name: simulacra\n    volumes:\n      - /var/lib/simulacra:/config\n    environment:\n      - OPENROUTER_API_KEY={{ your_openai_api_key }}\n      - CONFIG_FILEPATH=/config/config.toml\n      - TELEGRAM_BOT_API=http://telegram-bot-api:8081\n    restart: unless-stopped\n```\n\n## Development\n\n### Code reloading\n\nEnable code reloading with development mode. Create a `.env` file or add the following to your environment:\n\n```sh\nexport ENVIRONMENT=development\n```\n\nNote: Development mode can only run a single bot.\n\n### Local Telegram Bot API\n\nA `docker-compose.yml` is included for running a [local Telegram Bot API server](https://github.com/tdlib/telegram-bot-api). Set `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` in your `.env`, then:\n\n```sh\ndocker compose up -d\n```\n\nGrant your user read access to files created by the container:\n\n```sh\nsudo setfacl -R -m u:$(whoami):rX -d -m u:$(whoami):rX /var/lib/telegram-bot-api/\n```\n\n### Pre-commit hooks\n\nInstall pre-commit hooks before committing code:\n\n```sh\nuv run pre-commit install\n```\n\n### Run linter\n\n```sh\nmake lint\n```\n\n### Run tests\n\n```sh\nmake test\n```\n\n### Release a new version\n\nThe release script sets the new version in `pyproject.toml`, commits it, and pushes a tag.\n\nA release is performed by GitHub Actions when the tag is pushed.\n\n```sh\nmake release type=\u003cmajor|minor|patch\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjbbaer%2Fsimulacra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjbbaer%2Fsimulacra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjbbaer%2Fsimulacra/lists"}