Documentation in Readme

CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to the Project
+
+## Table of Contents
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Code Style and Standards](#code-style-and-standards)
+- [Pull Request Process](#pull-request-process)
+
+## Getting Started
+
+Thank you for considering contributing to our project! This document will guide you through the process of making contributions.
+
+
+## Development Workflow
+
+1. **Find an Issue**
+   - Browse through the [GitHub Issues](https://github.com/issues) section
+   - Look for issues labeled as "good first issue" or "help wanted"
+   - If you want to work on something new, create an issue first to discuss it
+
+2. **Fork and Clone**
+   - Fork the repository to your GitHub account
+   - Clone your fork locally:
+     ```bash
+     git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git
+     ```
+
+3. **Create a Branch**
+   - Create a new branch for your work:
+     ```bash
+     git checkout -b feature/issue-number-brief-description
+     ```
+   - Use meaningful branch names, preferably referencing the issue number
+
+4. **Make Changes**
+   - Write your code
+   - Follow the project's coding standards
+   - Keep commits atomic and write meaningful commit messages
+   - Test your changes thoroughly
+
+5. **Push Changes**
+   - Push your changes to your fork:
+     ```bash
+     git push origin feature/issue-number-brief-description
+     ```
+
+## Code Style and Standards
+
+### Formatting
+- Code must be properly formatted according to project standards
+- Run formatting checks before committing:
+  ```bash
+  make format
+  ```
+
+### Code Quality
+- All code must pass the automated linting checks
+- The project uses CI/CD pipelines to verify code quality
+- Ensure all linting checks pass locally before pushing:
+  ```bash
+  make lint
+  ```
+
+## Pull Request Process
+
+1. **Create Pull Request**
+   - Go to the original repository on GitHub
+   - Click "New Pull Request"
+   - Select your branch
+   - Fill in the PR template with all required information
+
+2. **PR Requirements**
+   - Reference the related issue(s)
+   - Provide a clear description of changes
+   - Include any necessary documentation updates
+   - Ensure all CI checks pass
+   - Screenshots/GIFs for UI changes (if applicable)
+
+3. **Code Review**
+   - Request review from maintainers
+   - Address any feedback promptly
+   - Make requested changes if necessary
+   - Maintain a respectful and collaborative attitude
+
+4. **Merging**
+   - PRs will be merged once they:
+     - Have required approvals
+     - Pass all CI checks (including linting)
+     - Meet project quality standards
+     - Have no unresolved discussions
+
+---
+
+Remember that all contributions are valued, no matter how small. If you're unsure about anything, don't hesitate to ask for help in the issue comments or PR discussion.

README.md

@@ -4,24 +4,77 @@
 ## Table of Contents
 
 - [Overview](#overview)
-- [Features](#features)
+- [Code structure](#code-structure)
+- [Prebuilt tech features](#prebuilt-tech-features)
 - [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Overview
 
 This is a simple autonomous agent that uses Q-learning to make decisions, integrates with 
 Telegram and Twitter, and uses Qdrant for vector storage as a memory module.
 
-## Features
+Description of the agent in bullet points:
 
-### 1. Pyenv and Pipenv
+- This autonomous agent is designed to perform the tasks on his own. 
+- The core of the agent is implemented by planning, feedback and memory modules. 
+- The real intelligence is powered by the OpenAI LLMs. 
+- The actions of the agent are defined in workflows, which encapsulate logic of performing the task.
+- Different 3rd party services are integrated with the agent via tools, which are used in the workflows. Example of the tools:
+  - Telegram
+  - Twitter
+  - Some API for getting news (not implemented yet)
+  - Perplexity for research (not implemented yet)
 
-The project uses Pyenv for managing Python versions and Pipenv for managing dependencies. Find more
-details in the [Development](#development) section.
+Some more details about some modules:
+
+### Planning module
+
+The planning module is responsible for making decisions and planning the next action. It uses the Q-learning algorithm to make decisions. The details can be found in code at the [planning_module.py](src/planning/planning_module.py) file.
+
+### Feedback module
+
+The feedback module is responsible for providing feedback to the agent and updating the Q-learning model (in Planning module). It uses the feedback from the previous action, such as the result of the action and type of the action, to evaluate the result of the action and give this result to the Planning module (to update the Q-learning model). The details can be found in code at the [feedback_module.py](src/feedback/feedback_module.py) file.
+
+### Memory module
+
+The memory module is responsible for storing the memories of the agent: what actions were performed, what was the result of the action, etc. It uses Qdrant for storing the memories. The details can be found in code at the [memory_module.py](src/memory/memory_module.py) file.  
+
+### Workflows
+
+The workflows are responsible for stating "actions" to the agent. The details can be found in code at the [workflows](src/workflows) folder. This is the place where you define what actually the agent will perform. Currently, we implement the following workflows:
+
+- Analyze signal
+- Research news
+
+See the code for more details.
+
+## Code structure
+
+The code can be found in the [src](src) folder.
+
+Overview of the `src` folder:
+
+- [main.py](src/main.py) - the main entry point of the agent
+- [agent.py](src/agent.py) - the definition of the agent
+- [core](src/core) - the core of the project, which defines settings, definitions and exceptions
+- [memory](src/memory) - the memory module
+- [planning](src/planning) - the planning module
+- [feedback](src/feedback) - the feedback module
+- [tools](src/tools) - the tools module
+- [llm](src/llm) - the logic of interacting with LLMs
+- [workflows](src/workflows) - the workflows
+
+## Prebuilt tech Features
+
+### 1. Pyenv, Pipenv and Docker
+
+The project uses Pyenv for managing Python versions and Pipenv for managing dependencies. Find more details in the [Development](#development) section. Also we need to have Docker installed for running the Qdrant container. Install this software first (follow the official documentation).
 
 ### 2. Pydantic
 
-The project uses `Pydantic` for data validation and settings management.
+The project uses `Pydantic` for data validation and settings management. Is relatively simple and easy to use.
 
 ### 3. Ruff, Isort, Mypy
 
@@ -45,32 +98,24 @@ The provided Makefile includes the following commands:
 make deps    # Install dependencies
 make format  # Format code
 make lint    # Lint code
+make run     # Run the agent
 ```
 
 ## Development
 
 ### Pyenv and Pipenv
 
-#### Overview
-
 You will need to have Python 3.12 and pipenv installed. The next step is to checkout the repository 
 and install the Python dependencies. Then, you will be able to utilize the CLI and run the tests. 
 The following assumes a Debian/Ubuntu machine; your mileage may vary.
 
-#### Prerequisites
+### Docker
 
-You can use pyenv for getting a specific python version. Once you have pyenv installed, you can 
-install a specific python version:
+You need to have Docker installed for running the Qdrant container. Install this software first (follow the official documentation).
 
-```
-pyenv install 3.12
-```
+### Quickstart
 
-Install pipenv:
-
-```
-pip install --user pipenv
-```
+Follow these steps to get the project running.
 
 #### Install Dependencies
 
@@ -121,3 +166,11 @@ Alternatively, you can run the agent manually:
 ```bash
 pipenv run python -m src.main
 ```
+
+## Contributing
+
+Contributions are welcome! Please follow the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.