Quick start

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.11 or 3.13 (recommended versions for compatibility)
Visual Studio Code (or your preferred code editor)
pip (Python package manager)
Git (for cloning the repository)

This guide is optimized for Ubuntu/Linux systems. Windows and macOS users may need to adjust some commands.

Installation

Download the repository

Clone or download the repository from GitHub:

# Clone with git
git clone <repository-url>

# Or download as ZIP
# Navigate to the repository on GitHub
# Click "Code" > "Download ZIP"
# Extract the ZIP file to your desired location

Navigate to the project directory:

cd grupo-de-anda

Install Python and VS Code

Download and install the required software:Python 3.11.14:

Visit https://www.python.org/
Download Python 3.11.14 or Python 3.13.x
Follow the installation instructions for your operating system

Visual Studio Code:

Visit https://code.visualstudio.com/download
Download and install VS Code for your platform
Install the Python extension for VS Code

For detailed installation instructions, watch this setup tutorial.

Create a virtual environment (Ubuntu users)

Ubuntu users: Creating a virtual environment is critical to avoid breaking system Python packages. Ubuntu’s system code relies on Python, and installing libraries globally can cause system instability.

Create and activate a virtual environment:

# Navigate to your project directory
cd /path/to/grupo-de-anda

# Create virtual environment
python3 -m venv .venv

# Activate the virtual environment
# On Linux/macOS:
source .venv/bin/activate

# On Windows PowerShell:
# .venv\Scripts\Activate.ps1

# On Windows Command Prompt:
# .venv\Scripts\activate.bat

You should see (.venv) prefix in your terminal prompt, indicating the virtual environment is active.To deactivate later:

deactivate

Install Python dependencies

With your virtual environment activated, install the core dependencies:

pip install --upgrade pip

For AI/ML projects (includes PyTorch with CPU support):

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install transformers datasets peft accelerate

For general projects (GUI apps, voice assistants, utilities):

pip install customtkinter keyboard gpt4all requests llama-cpp-python
pip install gTTS pygame torch librosa numpy sounddevice pydub

Install only the libraries needed for your specific project to save time and disk space. Check each project’s imports to determine requirements.

Configure API keys (if needed)

Some projects require API keys for external services:Google Gemini API (for AI assistant projects):

Visit Google AI Studio
Generate an API key
Add it to the project file:

# In proyectos/ai creator/asistantkamutini.py
API_KEY_GEMINI = "your-api-key-here"

Google Search API (for search functionality):

Obtain a Google Custom Search API key
Get a Search Engine ID
Configure in the project:

API_KEY_GOOGLE_SEARCH = "your-search-api-key"
SEARCH_ENGINE_ID = "your-search-engine-id"

Google Text-to-Speech (gTTS):

No API key required
Uses: https://translate.google.com/translate_tts

Running your first project

AI Voice Assistant
miPOS System
Custom AI Model

Run the AI assistant with Google Gemini integration:

cd proyectos/"ai creator"
python asistantkamutini.py

What it does:

Voice-based AI assistant
Uses Google Gemini for conversational AI
Text-to-speech responses with gTTS
Web search integration
Intent detection

Make sure you’ve configured your API_KEY_GEMINI before running this project.

Launch the point-of-sale desktop application:

cd proyectos/"mipunto -"
python inicio.py

Features:

Inventory management (inventario.py)
Sales processing (ventas.py)
Reporting system (reporte.py)
AI-powered analytics (ai.py)
CustomTkinter GUI interface

The application window will open with buttons for:

Inventario (Inventory)
Nueva venta (New Sale)
Reporte (Report)
Reporte con AI (AI Report)

Train or use a custom transformer model:

cd proyectos/"ai creator"/kamutini
python modelo.py

Features:

Custom PyTorch transformer architecture
Automatic device detection (CUDA/MPS/CPU)
Dataset normalization from JSON/CSV files
Configurable hyperparameters
Intent detection model

Model configuration:

CONFIG = {
    "batch_size": 16,
    "block_size": 256,
    "n_embd": 512,
    "n_head": 8,
    "n_layer": 8,
    "dropout": 0.1,
    "learning_rate": 5e-4,
    "max_steps": 2000,
    "temperature": 0.7,
    "top_k": 50
}

Training AI models is resource-intensive. The model automatically uses GPU (CUDA/MPS) if available, otherwise falls back to CPU.

Running projects in VS Code

Once you have a project open in Visual Studio Code:

Open the Python file you want to run (e.g., inicio.py, asistantkamutini.py)
Press F5 to run the program with debugging
Or use the terminal:
```
python filename.py
```

Some programs open a GUI window, while others run in the terminal. Check the project’s code to understand its interface.

Arduino/Hardware projects

For hardware projects in proyectos hadwere/arduino nano/:

Install Arduino IDE

Download and install the Arduino IDE:

Visit https://www.arduino.cc/en/software
Install for your operating system

Open the .ino file

Navigate to the hardware project:

cd "proyectos hadwere/arduino nano/lampara_solar/v2"

Open codigo.ino in the Arduino IDE.

Configure and upload

Select your board: Tools > Board > Arduino Nano
Select the processor: Tools > Processor > ATmega328P (or your variant)
Select the port: Tools > Port > [Your Arduino Port]
Click Upload (→ button) to flash the code to your Arduino

Understanding AI commands

The AI Creator project includes custom commands for the voice assistant:

Command	Format	Description
Search	`search=[topic]`	AI researches a topic on the internet
Weather	`clma=[location]`	AI retrieves weather for a specific location
Location	`ubicacion=[]`	Provides location data to the AI

Intent detection categories:

investigar (research)
clima (weather)
conversacion_ai (AI conversation)

Troubleshooting

Module not found error

If you see ModuleNotFoundError: No module named 'xxx':

# Make sure your virtual environment is activated
source .venv/bin/activate

# Install the missing package
pip install xxx

Ubuntu: Permission denied or system Python errors

You’re trying to modify system Python packages. Always use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install [packages]

API key errors

If projects fail with API authentication errors:

Check that you’ve added your API key to the Python file
Ensure the API key is valid and not expired
Verify you have internet connectivity
Check API usage limits/quotas

PyTorch/CUDA issues

To check if PyTorch detects your GPU:

import torch
print(torch.cuda.is_available())  # Should print True if CUDA is available
print(torch.cuda.device_count())  # Number of GPUs

For CPU-only installation:

pip install torch --index-url https://download.pytorch.org/whl/cpu

For CUDA 12.1:

pip install torch --index-url https://download.pytorch.org/whl/cu121

Arduino upload failed

Common Arduino issues:

Wrong port selected: Check Tools > Port and select the correct USB port
Board not recognized: Install CH340 drivers if using clone boards
Bootloader issue: Try holding reset while uploading
Processor mismatch: Verify your Arduino Nano variant (ATmega328P vs ATmega328P Old Bootloader)

Next steps

Now that you’re set up:

Explore projects

Browse detailed documentation for each project

API references

Learn about the APIs and libraries used

Hardware guides

Circuit diagrams and hardware setup guides

Development guides

Learn how to set up your development environment

Having issues? Remember that this code is designed for Ubuntu with Python 3.11/3.13. Adjust paths and commands for your operating system.

Get Started

Software Projects

Hardware Projects

Development Guides

Prerequisites

Installation

Running your first project

Running projects in VS Code

Arduino/Hardware projects

Understanding AI commands

Troubleshooting

Next steps

Explore projects

API references

Hardware guides

Development guides

Build docs developers (and LLMs) love

Get Started

Software Projects

Hardware Projects

Development Guides

​Prerequisites

​Installation

​Running your first project

​Running projects in VS Code

​Arduino/Hardware projects

​Understanding AI commands

​Troubleshooting

​Next steps

Explore projects

API references

Hardware guides

Development guides

Build docs developers (and LLMs) love

Prerequisites

Installation

Running your first project

Running projects in VS Code

Arduino/Hardware projects

Understanding AI commands

Troubleshooting

Next steps