PYGENTIC-AI

Empowering AI innovation with seamless asynchronous processing.

---

Table of Contents

• Table of Contents
• Overview
• Features
• Project Structure
  • Project Index
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Testing
• Roadmap
• Contributing
• License
• Acknowledgments

---

Overview

Pygentic-AI simplifies project setup and backend operations for developers.

Why Pygentic-AI?

This project automates Python environment setup and dependency management, ensuring a smooth development workflow. The custom logger enhances backend logging efficiency, while the RESTful API server streamlines backend operations.

• 🚀 Automated Python Setup: Simplify environment configuration and dependency management.
• 💡 Custom Logger: Efficient logging with customizable features for backend operations.
• 🌐 RESTful API Server: Facilitate seamless backend operations with a robust API server.

---

Features

	Component	Details
⚙️	Architecture	Follows a modular architecture with clear separation of concerns Utilizes FastAPI for building APIs Integrates with SQLAlchemy for database operations
🔩	Code Quality	Consistent code style following PEP8 guidelines Includes type hints for improved code readability and maintainability Uses logging extensively for debugging and monitoring
📄	Documentation	Comprehensive documentation using Sphinx and reStructuredText Includes detailed API documentation using Swagger UI README.md provides clear setup and usage instructions
🔌	Integrations	Integrates with Celery for asynchronous task processing Utilizes Pydantic for data validation and parsing Includes integration with OpenTelemetry for observability
🧩	Modularity	Organized into reusable modules for easy maintenance and extensibility Follows the SOLID principles for better code structure Uses dependency injection for decoupling components
🧪	Testing	Includes unit tests for critical components using pytest Utilizes test fixtures for reusable test setup Implements continuous integration with GitHub Actions for automated testing
⚡️	Performance	Optimizes database queries using SQLAlchemy ORM Utilizes async features for improved concurrency Includes caching mechanisms for faster data retrieval
🛡️	Security	Follows best practices for handling user authentication and authorization Implements input validation to prevent common security vulnerabilities Includes security headers and encryption for data protection
📦	Dependencies	Uses a wide range of dependencies for various functionalities Manages dependencies using pip and uv for locking versions Includes detailed dependency files for easy reproducibility

---

Project Structure

└── Pygentic-AI/
    ├── bin
    │   ├── build.sh
    │   ├── linux_build.sh
    │   ├── python_build.sh
    │   └── start.sh
    ├── compose.yaml
    ├── core_requirements.in
    ├── core_requirements.txt
    ├── dev_requirements.in
    ├── dev_requirements.txt
    ├── docker
    │   ├── celery
    │   └── ranked_jobs_ms
    ├── Dockerfile
    ├── pyproject.toml
    ├── README.md
    ├── src
    │   ├── app.py
    │   ├── backend
    │   └── cworker.py
    └── uv.lock

Project Index

PYGENTIC-AI/

__root__

⦿ __root__

File Name	Summary
compose.yaml	- Define services and configurations for web and celery_service containers, including image, resources, ports, environment variables, volumes, labels, health checks, and network settings - Services are deployed with specific memory limits and exposed ports, with web service catering to production and celery_service to staging environments - Traefik is utilized for routing and SSL termination.
core_requirements.in	Define project dependencies and requirements using the core_requirements.in file to ensure seamless integration and functionality across the codebase architecture.
core_requirements.txt	Generates a compiled list of core requirements for the project, ensuring all necessary dependencies are included for seamless functionality across various modules and components.
dev_requirements.in	- Enhance development environment by managing dependencies efficiently with dev_requirements.in - This file specifies essential tools like Alembic, Black, and Pre-commit to streamline the development process - Optimize code formatting and debugging with JupyterLab extensions, ensuring a robust and efficient workflow.
dev_requirements.txt	- Generate a list of development requirements for the project, outlining dependencies and their versions - The file was auto-generated using uv to compile the dev_requirements.in file - It includes various packages required for development, such as alembic, fastapi, and jupyter-server - Each dependency is specified with its version number for accurate package management.
Dockerfile	- Create a Docker image for Pygentic-AI project, setting up necessary environment variables, cloning the project repository, and configuring the workspace - Install dependencies, create user celery, set up directories, and make scripts executable - Finally, build and start the Python application within the designated workspace.
pyproject.toml	- Define linting rules and file exclusions for the project structure in the pyproject.toml file - Ensure code quality by enforcing specific linting standards, excluding unnecessary directories, and setting line length limits - This configuration enhances code readability and maintainability across the codebase.

bin

⦿ bin

File Name	Summary
build.sh	Update and install project dependencies using the provided build script.
linux_build.sh	- Set up a Linux environment for the project by installing essential dependencies and tools - Ensure a smooth development experience by preparing the system with required packages like build tools, Python 3.13, PostgreSQL, and more - This script streamlines the initial setup process, enabling developers to focus on building the project without worrying about environment configuration.
python_build.sh	- Automates Python environment setup and dependency management for the project - Creates a virtual environment, installs necessary packages, and syncs core and development requirements using pip-tools - Facilitates streamlined development workflow by ensuring consistent package versions across environments.
start.sh	- Launches the application using Gunicorn with specified configurations, such as the number of workers, timeout, and port - The script activates the virtual environment and starts the server to handle incoming requests.

src

⦿ src

File Name	Summary
app.py	- Define exception handlers and mount static files for the FastAPI app using the provided code - Handle validation errors and custom exceptions, logging details and returning appropriate responses - Serve static files from the specified directory for the frontend.
cworker.py	- Improve concurrency by managing worker threads efficiently - This code file in src\cworker.py orchestrates thread creation and execution within the projects architecture.

backend

⦿ src.backend

File Name	Summary
logger.py	- Implement a custom logger using Loguru for efficient logging in the backend - The logger supports various log levels and customization options, enhancing the logging experience - It includes features like log rotation, retention, and different log formats - The code ensures robust logging functionality for the project.
utils.py	- Define utility functions to retrieve database URLs based on environment and fetch values from environment variables or configuration files - The get_db_url function constructs a database URL for different environments, while get_val retrieves values with fallback options - These functions enhance flexibility and maintainability in managing configurations and environment variables.

core

⦿ src.backend.core

File Name	Summary
consts.py	- Define the AI_MODEL and default_system_prompt for the GPT-4o AI assistant in the consts.py file - The AI_MODEL specifies the model used, while the default_system_prompt outlines the AIs function of generating SWOT analyses.
core.py	- Define a SQLModel and Agent Dependencies for SWOT Analysis, creating a SwotAgent with specified parameters for AI model, system prompt, and retries - This code file in the core module plays a crucial role in structuring and managing SWOT analysis responses within the projects architecture.
main.py	Implement core functionality for backend services in the main.py file.
tools.py	- Describe how the tools.py file in src\backend\core facilitates fetching website content, analyzing competition using the Gemini model, and obtaining insights from Reddit - The functions within this file leverage various libraries and APIs to perform these tasks efficiently.
utils.py	- Define a function to report tool usage and results within the projects core architecture - The function checks and updates tool usage history, notifying an update function if available - This contributes to tracking tool usage and ensuring status updates are communicated effectively.

db

⦿ src.backend.db

File Name	Summary
base.py	- Generate base SQLModel class for project, addressing Pydantic V2.5 issue with __pydantic_extra__ attribute - Inherits from SQLModel and sets necessary attributes - Integrated with project metadata and configured for eager defaults.
consts.py	Define database constants for backend operations in the project structure.
core.py	Manage core database operations for the backend system, ensuring efficient data handling and storage.
db.py	- Create and manage async SQLA sessions, handle database operations, and ensure database schema creation - Includes functions for checking database existence, creating databases, and setting the current schema - Provides utilities for creating database engines and managing database connections - Mainly focuses on database setup and interaction for the project.
main.py	Implement database connection and query functions to manage data persistence for the backend services.
utils.py	- Enhances database operations by providing utility functions - Facilitates seamless interaction with the database layer.

server

⦿ src.backend.server

File Name	Summary
consts.py	Define and store constant values used throughout the backend server architecture.
core.py	Implement core server functionality to handle incoming requests and manage data operations within the backend architecture.
main.py	- Implement a RESTful API server in Python to handle backend operations for the project - The main.py file serves as the entry point for the server, orchestrating requests and responses - It plays a crucial role in managing the communication between the frontend and backend components of the application.
router.py	Define API routes and request handling logic for the backend server.
utils.py	- Enhances server functionality by providing utility functions - Improves codebase architecture by centralizing common operations - Facilitates streamlined development and maintenance processes - Promotes code reusability and efficiency within the backend server module.

settings

⦿ src.backend.settings

File Name	Summary
backend_options.py	- Generate SQL database connection URLs based on provided configurations for different environments using accepted dialects, including PostgreSQL and SQLite - Import these configurations into the appropriate settings file to integrate with the Django Database settings.
base.py	Define project settings including backend and frontend directories, database URL, and debug mode in the base settings file.
consts.py	Define database dialects and set secret key for project configuration.
core.py	- Enhances core settings functionality by providing centralized configuration management - Facilitates seamless access and modification of key system parameters - Improves maintainability and scalability of the project by consolidating settings logic.
dev.py	Define development settings for backend with local database configuration and debugging enabled.
main.py	- Enhances backend settings functionality by managing configurations efficiently - Facilitates seamless customization and optimization of settings across the codebase architecture.
prod.py	- Define production settings for the backend, including database configuration and debugging options - Extends base settings to inherit common configurations - Centralizes cloud database settings for easy management and maintenance.
utils.py	- Enhance backend settings functionality by providing utility functions for the codebase architecture - The utils.py file in the src\backend\settings directory plays a crucial role in enabling streamlined operations and improved performance within the project structure.

site

⦿ src.backend.site

File Name	Summary
consts.py	- Define constants and data structures for tracking analysis progress and results in the backend of the site architecture - Includes messages for analysis status, sets for running tasks, and dictionaries for storing status and results.
core.py	Implement core functionality for the site backend, facilitating key operations within the project architecture.
main.py	Improve site performance by caching API responses in the main.py file.
router.py	- Implement a backend API router for a SWOT analysis tool - The router handles URL analysis requests, updates status messages, and provides analysis results - It manages session IDs, progress tracking, and result storage - The code integrates with FastAPI, Starlette, and Jinja2 for web functionality.
utils.py	- Enhances backend functionality by providing utility functions for the site - This code file in the backend architecture aids in streamlining operations and improving overall performance.

docker

⦿ docker

celery

⦿ docker.celery

File Name	Summary
start.sh	- Initiates and manages Celery workers, beat scheduler, and Flower for the projects asynchronous task processing - Handles worker availability checks and starts necessary services within the specified project directory.

ranked_jobs_ms

⦿ docker.ranked_jobs_ms

File Name	Summary
build.sh	- Install necessary dependencies for the ranked jobs microservice in the Docker container - The script sets up essential tools like Python, PostgreSQL, and Git, ensuring a robust environment for the microservice to run smoothly.
python_build.sh	- Automates Python environment setup and dependency management for the ranked jobs microservice in the Docker architecture - Sets up virtual environment, compiles requirements, and syncs dependencies for smooth execution.
python_start.sh	- Launches the Python application using Gunicorn with specified configurations like the number of workers, timeout, and port - The script activates the virtual environment and starts the server to handle incoming requests.

---

Getting Started

Prerequisites

This project requires the following dependencies:

• Programming Language: Python
• Package Manager: Pip, Uv
• Container Runtime: Docker

Installation

Build Pygentic-AI from the source and intsall dependencies:

1. Clone the repository:

   ❯ git clone https://github.com/fsecada01/Pygentic-AI
   

2. Navigate to the project directory:

   ❯ cd Pygentic-AI
   

3. Install the dependencies:

<!-- [![docker][docker-shield]][docker-link] -->
<!-- REFERENCE LINKS -->
<!-- [docker-shield]: https://img.shields.io/badge/Docker-2CA5E0.svg?style={badge_style}&logo=docker&logoColor=white -->
<!-- [docker-link]: https://www.docker.com/ -->

**Using [docker](https://www.docker.com/):**

```sh
❯ docker build -t fsecada01/Pygentic-AI .
```

<!-- [![pip][pip-shield]][pip-link] -->
<!-- REFERENCE LINKS -->
<!-- [pip-shield]: https://img.shields.io/badge/Pip-3776AB.svg?style={badge_style}&logo=pypi&logoColor=white -->
<!-- [pip-link]: https://pypi.org/project/pip/ -->

**Using [pip](https://pypi.org/project/pip/):**

```sh
❯ pip install -r core_requirements.in, core_requirements.txt, dev_requirements.in, dev_requirements.txt
```

<!-- [![uv][uv-shield]][uv-link] -->
<!-- REFERENCE LINKS -->
<!-- [uv-shield]: https://img.shields.io/badge/uv-DE5FE9.svg?style=for-the-badge&logo=uv&logoColor=white -->
<!-- [uv-link]: https://docs.astral.sh/uv/ -->

**Using [uv](https://docs.astral.sh/uv/):**

```sh
❯ uv sync --all-extras --dev
```

Usage

Run the project with:

Using docker:

docker run -it {image_name}

Using pip:

python {entrypoint}

Using uv:

uv run python {entrypoint}

Testing

Pygentic-ai uses the {test_framework} test framework. Run the test suite with:

Using pip:

pytest

Using uv:

uv run pytest tests/

---

Roadmap

• Task 1: Implement feature one.
• Task 2: Implement feature two.
• Task 3: Implement feature three.

---

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the Pygentic-AI project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your github account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/fsecada01/Pygentic-AI
   

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x
   

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'
   

6. Push to github: Push the changes to your forked repository.

   git push origin new-feature-x
   

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

Contributor Graph

---

License

Pygentic-ai is protected under the LICENSE License. For more details, refer to the LICENSE file.

---

Acknowledgments

• Credit contributors, inspiration, references, etc.

⬆ Return

---