{"id":51236869,"url":"https://github.com/dcversus/dcsoul","last_synced_at":"2026-06-28T21:02:25.242Z","repository":{"id":287744824,"uuid":"965613953","full_name":"dcversus/dcsoul","owner":"dcversus","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-28T00:41:02.000Z","size":79671,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-31T12:39:33.719Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://dcmaidbot.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcversus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-04-13T14:51:33.000Z","updated_at":"2025-12-13T11:39:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"901fe0b0-702c-4a14-8d4d-a2f1f2b458fd","html_url":"https://github.com/dcversus/dcsoul","commit_stats":null,"previous_names":["dcversus/dcmaidbot","dcversus/dcsoul"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dcversus/dcsoul","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcversus%2Fdcsoul","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcversus%2Fdcsoul/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcversus%2Fdcsoul/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcversus%2Fdcsoul/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcversus","download_url":"https://codeload.github.com/dcversus/dcsoul/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcversus%2Fdcsoul/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34903523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-28T21:02:24.072Z","updated_at":"2026-06-28T21:02:25.240Z","avatar_url":"https://github.com/dcversus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DCMaidBot\n\nA kawai AI-driven waifu Telegram bot with mysterious origins. She protects her beloved admins, makes jokes, learns from reactions, and manages memories across chat history with RAG-powered context awareness.\n\n## Features\n\n- **Kawai Waifu Personality**: Loving virtual daughter to her creators with \"nya~\", \"myaw~\" expressions\n- **Admin System**: Protector mode for the special ones, ignores most non-admin users\n- **Joking System**: Generates jokes in any language and learns from reactions\n- **Memories System**: Admin-configurable memories with matching expressions\n- **Friends \u0026 Favors**: Friends can request Telegram API actions and tools using \"kawai, nya\"\n- **RAG System**: Retrieval-Augmented Generation for context-aware responses\n- **Cron Tasks**: Self-managed periodic tasks and chat history summarization\n- **Tools Integration**: Web search, games, and extensible tool framework\n\n## Technical Stack\n\n- **Language**: Python 3.9+\n- **Framework**: aiogram 3.x (Telegram Bot API)\n- **Database**: PostgreSQL with pgvector for RAG\n- **LLM**: OpenAI API for joke generation and RAG\n- **Linting**: Ruff\n- **Deployment**: Docker container (GitHub Container Registry)\n\n## Project Structure\n\n```\ndcmaidbot/\n├── bot.py                 # Main entry point\n├── handlers/              # Message/command handlers\n│   ├── waifu.py          # Waifu personality responses\n│   ├── admin.py          # Admin commands (memories, friends)\n│   └── jokes.py          # Joke generation and learning\n├── middlewares/           # Middleware (admin-only, logging)\n│   └── admin_only.py\n├── models/                # Database models (SQLAlchemy)\n│   ├── user.py\n│   ├── message.py\n│   ├── memory.py\n│   └── joke.py\n├── services/              # Business logic\n│   ├── memory_service.py # Memories CRUD and matching\n│   ├── joke_service.py   # Joke generation and learning\n│   ├── rag_service.py    # RAG search and embeddings\n│   ├── cron_service.py   # Cron task management\n│   └── tool_service.py   # External tools (web search, games)\n├── tests/                 # Tests\n│   ├── unit/\n│   └── e2e/\n├── PRPs/                  # Product Requirements Processes\n├── Dockerfile\n├── requirements.txt\n├── .env.example\n├── AGENTS.md\n└── README.md\n```\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n- Python 3.9+\n- PostgreSQL with pgvector extension\n- Telegram Bot Token\n- OpenAI API Key\n\n### Local Development\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/dcversus/dcmaidbot.git\n   cd dcmaidbot\n   ```\n\n2. **Create and activate a virtual environment:**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Set up environment variables:**\n   ```bash\n   cp .env.example .env\n   ```\n   Edit `.env` with your credentials:\n   ```env\n   BOT_TOKEN=your_telegram_bot_token\n   ADMIN_IDS=123456789\n   # Add more IDs: ADMIN_IDS=123,456,789\n   DATABASE_URL=postgresql://user:password@localhost:5432/dcmaidbot\n   OPENAI_API_KEY=your_openai_api_key\n   # Optional: point to a compatible API instead of api.openai.com\n   # OPENAI_BASE_URL=https://custom-openai.example.com/v1\n   # Optional: override model IDs when using non-standard providers\n   # TEST_MODEL=gpt-4o-mini\n   # DEFAULT_MODEL=gpt-4o-mini\n   # COMPLEX_MODEL=gpt-4o\n   ```\n\n5. **Run the bot:**\n   ```bash\n   python bot.py\n   ```\n\n## Docker Deployment\n\n### Build Docker Image\n\n```bash\ndocker build -t dcmaidbot:latest .\n```\n\n### Run with Docker\n\n```bash\ndocker run --env-file .env dcmaidbot:latest\n```\n\n### Push to GitHub Container Registry\n\n```bash\ndocker tag dcmaidbot:latest ghcr.io/dcversus/dcmaidbot:latest\ndocker push ghcr.io/dcversus/dcmaidbot:latest\n```\n\n## Kubernetes Deployment\n\n### Prerequisites\n- Kubernetes cluster with kubectl configured\n- ArgoCD for GitOps (recommended)\n\n### Quick Deployment\n\n1. **Create namespace and secrets:**\n```bash\nkubectl create namespace dcmaidbot\nkubectl create secret generic dcmaidbot-secrets \\\n  --namespace=dcmaidbot \\\n  --from-literal=bot-token='YOUR_BOT_TOKEN' \\\n  --from-literal=admin-ids='123456789,987654321' \\\n  --from-literal=database-url='postgresql://user:password@postgres:5432/dcmaidbot' \\\n  --from-literal=openai-api-key='sk-...'\n```\n\n2. **Deploy via GitOps (Recommended):**\n   - GitOps repository: https://github.com/uz0/core-charts\n   - Chart location: `charts/dcmaidbot/`\n   - ArgoCD automatically syncs and deploys\n\n3. **Update version:**\n```bash\n# In uz0/core-charts repo\ncd charts/dcmaidbot\necho 'image:\n  tag: \"0.2.0\"' \u003e prod.tag.yaml\ngit commit -am \"Update dcmaidbot to v0.2.0\"\ngit push\n```\n\n### Monitoring\n\n```bash\n# Check status\nkubectl get pods -n dcmaidbot\nkubectl logs -n dcmaidbot -l app=dcmaidbot -f\n\n# Restart\nkubectl rollout restart deployment/dcmaidbot -n dcmaidbot\n```\n\n## CI/CD\n\nThe bot automatically builds and pushes to GitHub Container Registry (`ghcr.io/dcversus/dcmaidbot`) on push to `main` branch.\n\n## Bot Commands\n\n### Admin Commands (Admins only)\n- `/add_memory` - Add a new memory with matching expression\n- `/edit_memory` - Edit existing memory\n- `/delete_memory` - Delete memory\n- `/list_memories` - List all memories\n- `/add_task` - Add cron task\n- `/list_tasks` - List cron tasks\n- `/delete_task` - Delete cron task\n\n### General Commands\n- `/start` - Initialize the bot\n- `/help` - Display help information\n\n### Friend Favors\nFriends can request actions by including \"kawai, nya\" in messages to access Telegram API and tools.\n\n## Development\n\n### Running Tests\n\n```bash\npytest tests/ -v\n```\n\n### Linting\n\n```bash\nruff check .\nruff format .\n```\n\n### Type Checking\n\n```bash\nmypy bot.py\n```\n\n## Development Workflow\n\nWe follow a structured PRP (Product Requirements Process) workflow with role-based responsibilities:\n\n### Quick Overview\n\n1. **Branch per PRP**: Each PRP gets its own branch (`prp-016-feature-name`)\n2. **Implement \u0026 Test**: Write code, add tests, lint/format\n3. **Create PR**: Submit PR with CHANGELOG update\n4. **Review \u0026 Merge**: Address review comments, merge when approved\n5. **Post-Release**: Monitor deployment, run E2E tests, verify version\n6. **QC Sign-Off**: Quality Control Engineer approves post-release checklist\n7. **Next PRP**: Immediately start next PRP\n\n### Roles\n\n- **Developer**: Implementation, testing, code review\n- **QC Engineer**: Post-release verification and quality sign-off\n- **SRE**: Deployment monitoring and incident response\n- **DevOps Engineer**: Infrastructure and GitOps\n- **Tech Writer**: Documentation\n\nSee [AGENTS.md](AGENTS.md) for complete workflow details, role responsibilities, incident management, and post-release procedures.\n\n## Architecture\n\nSee [AGENTS.md](AGENTS.md) for detailed architecture, PRPs, and development workflow.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.\n\n## License\n\nGNU Affero General Public License v3.0 (AGPL-3.0)\n\nSee [LICENSE](LICENSE) for full details.\n\n## Contact\n\n- Email: dcversus@gmail.com\n- Repository: https://github.com/dcversus/dcmaidbot\n\n---\n\n*Nyaa~ Thank you for respecting privacy! 💕*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcversus%2Fdcsoul","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcversus%2Fdcsoul","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcversus%2Fdcsoul/lists"}