GnosysLabs/Synapsis
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(bots): Implement comprehensive bot system with autonomous posting, content management, and API endpoints

Browse Source 
- Add bot management system with creation, suspension, and reinstatement functionality
- Implement autonomous bot posting with scheduling, rate limiting, and content generation
- Add content fetching system supporting RSS feeds and multiple content sources
- Implement LLM-based content generation with customizable bot personalities
- Add mention handling and automated response system for bot interactions
- Implement API key management with encryption using AUTH_SECRET for simplified deployment
- Add comprehensive bot logging system for activity tracking and error monitoring
- Create bot administration pages and settings UI for managing bot configurations
- Add database migrations for bot system schema including users, sources, and content items
- Implement cron job system for automated bot operations and scheduled tasks
- Add extensive test coverage with unit and property-based tests for core bot modules
- Simplify encryption by deriving keys from AUTH_SECRET instead of separate environment variable
- Implement automatic content fetching on post trigger with retry logic
- Add Reddit-specific link preview handling using oEmbed API for reliable metadata extraction
- Create utility scripts for bot inspection and cleanup operations
- Add comprehensive bot system documentation and improvement tracking
This commit is contained in:
AskIt
2026-01-25 16:22:41 +01:00
parent cfb558fff1
commit 8ad3b97b7e
102 changed files with 41692 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.kiro/specs/bot-system/requirements.md
+174
View File
@@ -0,0 +1,174 @@
# Requirements Document: Bot System
## Introduction
This document specifies the requirements for implementing an autonomous bot system in Synapsis. The system enables users to create and manage bots that can monitor external content sources, generate posts using LLM APIs, and interact with other users through mentions and replies. Bots operate under user accounts with configurable personalities and behaviors while maintaining clear identification as automated entities.
## Glossary
- **Bot**: An automated entity that operates under a user account, capable of posting content and responding to interactions
- **Bot_Creator**: A user who creates and manages one or more bots
- **Bot_Manager**: The system component responsible for bot lifecycle and operations
- **Content_Source**: An external data feed (RSS, Reddit, news API) that a bot monitors
- **LLM_Provider**: An external API service (e.g., OpenRouter) that generates text content
- **Personality_Configuration**: Settings that define a bot's voice, tone, and behavior patterns
- **Post_Scheduler**: The component that determines when bots should create posts
- **Mention_Handler**: The component that detects and processes mentions of bots
- **Activity_Logger**: The component that records bot actions and events
- **Federation_Protocol**: ActivityPub protocol used for inter-instance communication
- **Rate_Limiter**: The component that enforces posting frequency limits
## Requirements
### Requirement 1: Bot Creation and Management
**User Story:** As a user, I want to create and manage bots under my account, so that I can deploy autonomous agents with specific purposes.
#### Acceptance Criteria
1. WHEN a user creates a bot, THE Bot_Manager SHALL create a new bot entity linked to the user's account
2. WHEN a bot is created, THE Bot_Manager SHALL assign it a unique identifier and mark it as a bot entity
3. WHEN a user views their bots, THE Bot_Manager SHALL display all bots associated with their account
4. WHEN a user deletes a bot, THE Bot_Manager SHALL remove the bot and all associated configurations
5. WHEN a bot is displayed, THE System SHALL clearly indicate that it is a bot and not a human user
6. THE Bot_Manager SHALL enforce a maximum limit of bots per user account
### Requirement 2: API Key Configuration
**User Story:** As a bot creator, I want to configure API keys for LLM providers, so that my bot can generate content.
#### Acceptance Criteria
1. WHEN a user provides an API key, THE Bot_Manager SHALL validate the key format before storage
2. WHEN storing API keys, THE Bot_Manager SHALL encrypt them using secure encryption
3. WHEN retrieving API keys for bot operations, THE Bot_Manager SHALL decrypt them securely
4. WHEN a user updates an API key, THE Bot_Manager SHALL replace the old key with the new encrypted key
5. WHEN a user deletes a bot, THE Bot_Manager SHALL remove all associated API keys from storage
6. THE Bot_Manager SHALL support multiple LLM provider types (OpenRouter, OpenAI, Anthropic)
### Requirement 3: Personality and Behavior Configuration
**User Story:** As a bot creator, I want to configure my bot's personality and behavior, so that it has a consistent voice and style.
#### Acceptance Criteria
1. WHEN a user configures a bot personality, THE Bot_Manager SHALL store the personality prompt and parameters
2. WHEN generating content, THE LLM_Provider SHALL use the configured personality prompt as context
3. WHEN a user updates personality settings, THE Bot_Manager SHALL apply changes to future bot actions
4. THE Personality_Configuration SHALL include system prompts, temperature, and other LLM parameters
5. WHEN a bot responds to mentions, THE LLM_Provider SHALL maintain consistency with the configured personality
### Requirement 4: Content Source Monitoring
**User Story:** As a bot creator, I want my bot to monitor external content sources, so that it can generate posts based on real-world information.
#### Acceptance Criteria
1. WHEN a user adds a content source, THE Bot_Manager SHALL validate the source URL and type
2. WHEN monitoring RSS feeds, THE Content_Source SHALL fetch and parse feed items at regular intervals
3. WHEN monitoring Reddit, THE Content_Source SHALL use Reddit API to retrieve posts from specified subreddits
4. WHEN monitoring news APIs, THE Content_Source SHALL fetch articles using the configured API endpoint
5. WHEN new content is detected, THE Content_Source SHALL store it for bot processing
6. THE Content_Source SHALL support multiple source types per bot (RSS, Reddit, news APIs)
7. WHEN a source fails to fetch, THE Content_Source SHALL log the error and retry with exponential backoff
### Requirement 5: Scheduled Posting
**User Story:** As a bot creator, I want to configure posting schedules, so that my bot posts at predictable intervals.
#### Acceptance Criteria
1. WHEN a user sets a posting schedule, THE Post_Scheduler SHALL store the interval configuration
2. WHEN the scheduled time arrives, THE Post_Scheduler SHALL trigger bot content generation
3. THE Post_Scheduler SHALL support multiple schedule types (fixed interval, time-of-day, cron-like)
4. WHEN generating scheduled posts, THE Bot_Manager SHALL select content from monitored sources
5. WHEN no new content is available, THE Post_Scheduler SHALL skip the posting cycle
6. THE Rate_Limiter SHALL enforce minimum intervals between posts to prevent spam
### Requirement 6: Autonomous Posting
**User Story:** As a bot creator, I want my bot to decide when to post based on content interest, so that it behaves more naturally.
#### Acceptance Criteria
1. WHEN autonomous mode is enabled, THE Bot_Manager SHALL evaluate content sources for posting opportunities
2. WHEN evaluating content, THE LLM_Provider SHALL determine if the content is interesting enough to post
3. WHEN the bot decides to post, THE Bot_Manager SHALL generate and publish the post
4. THE Rate_Limiter SHALL enforce maximum posting frequency for autonomous bots
5. WHEN autonomous posting is disabled, THE Bot_Manager SHALL only post on schedule
### Requirement 7: Mention and Reply Detection
**User Story:** As a bot creator, I want my bot to detect and respond to mentions, so that it can interact with other users.
#### Acceptance Criteria
1. WHEN a bot is mentioned in a post, THE Mention_Handler SHALL detect the mention within 5 minutes
2. WHEN a mention is detected, THE Mention_Handler SHALL retrieve the mentioning post content
3. WHEN processing a mention, THE LLM_Provider SHALL generate a contextually appropriate response
4. WHEN generating responses, THE Bot_Manager SHALL include the original post context in the LLM prompt
5. WHEN a bot receives multiple mentions, THE Mention_Handler SHALL process them in chronological order
6. THE Rate_Limiter SHALL enforce limits on reply frequency to prevent abuse
### Requirement 8: Bot Activity Logging
**User Story:** As a bot creator, I want to view my bot's activity history, so that I can monitor its behavior and troubleshoot issues.
#### Acceptance Criteria
1. WHEN a bot performs an action, THE Activity_Logger SHALL record the action type, timestamp, and result
2. WHEN a user views bot logs, THE Activity_Logger SHALL display actions in reverse chronological order
3. THE Activity_Logger SHALL record post creation, mention responses, errors, and configuration changes
4. WHEN an error occurs, THE Activity_Logger SHALL record the error message and context
5. THE Activity_Logger SHALL retain logs for a configurable retention period
6. WHEN viewing logs, THE System SHALL support filtering by action type and date range
### Requirement 9: Federation Integration
**User Story:** As a system architect, I want bots to integrate with ActivityPub federation, so that they work seamlessly across instances.
#### Acceptance Criteria
1. WHEN a bot creates a post, THE Federation_Protocol SHALL distribute it to followers on other instances
2. WHEN a bot is mentioned from another instance, THE Mention_Handler SHALL detect and process the mention
3. WHEN bot profiles are viewed from other instances, THE Federation_Protocol SHALL include bot identification metadata
4. THE Federation_Protocol SHALL mark bot actors with the "bot" flag in ActivityPub actor objects
5. WHEN a bot follows or is followed, THE Federation_Protocol SHALL handle the relationship correctly
### Requirement 10: Security and Rate Limiting
**User Story:** As a system administrator, I want bots to be rate-limited and secure, so that they cannot be abused or compromise the system.
#### Acceptance Criteria
1. THE Rate_Limiter SHALL enforce a maximum of 50 posts per bot per day
2. THE Rate_Limiter SHALL enforce a minimum interval of 5 minutes between posts
3. WHEN API keys are stored, THE Bot_Manager SHALL use AES-256 encryption
4. WHEN a bot exceeds rate limits, THE Rate_Limiter SHALL prevent further actions and log the violation
5. THE Bot_Manager SHALL validate all user inputs to prevent injection attacks
6. WHEN a bot is suspended for violations, THE Bot_Manager SHALL prevent all bot actions until reinstated
### Requirement 11: Content Generation
**User Story:** As a bot creator, I want my bot to generate engaging posts with commentary, so that it provides value to followers.
#### Acceptance Criteria
1. WHEN generating a post, THE LLM_Provider SHALL combine source content with personality context
2. WHEN creating commentary, THE LLM_Provider SHALL use the configured temperature and parameters
3. WHEN source content is too long, THE Bot_Manager SHALL truncate or summarize it before sending to LLM
4. WHEN LLM generation fails, THE Bot_Manager SHALL log the error and retry up to 3 times
5. WHEN a post is generated, THE Bot_Manager SHALL validate it meets platform content requirements
6. THE Bot_Manager SHALL support multiple content formats (text, links, quotes)
### Requirement 12: Bot Identification and Transparency
**User Story:** As a user, I want to clearly identify bots, so that I know when I'm interacting with automated entities.
#### Acceptance Criteria
1. WHEN displaying a bot profile, THE System SHALL show a "Bot" badge or indicator
2. WHEN a bot posts, THE System SHALL include bot identification in the post metadata
3. WHEN viewing bot details, THE System SHALL display the bot creator's username
4. THE System SHALL prevent bots from removing or hiding their bot status
5. WHEN federating bot profiles, THE Federation_Protocol SHALL include bot identification in ActivityPub objects