Skip to content

Latest commit

 

History

History
162 lines (118 loc) · 3.23 KB

DEVELOPMENT.md

File metadata and controls

162 lines (118 loc) · 3.23 KB

Development Guide

This guide explains how to set up and develop SmartBlogger.

Prerequisites

  • Python 3.11+
  • uv (recommended) or pip
  • Ollama (for local LLM support)

Setting Up the Development Environment

Using uv (Recommended)

# Clone the repository
git clone <repository-url>
cd SmartBlogger

# Install dependencies
uv sync

# Activate the virtual environment (optional, uv can run commands directly)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Using pip

# Clone the repository
git clone <repository-url>
cd SmartBlogger

# Install dependencies
pip install -e .

Running the Application

Using uv

# Run the application
uv run streamlit run app.py

Using pip/standard Python

# Run the application
streamlit run app.py

Development Workflow

Adding New Dependencies

When adding new dependencies, update pyproject.toml and regenerate the lock file:

# Add a new dependency
uv add <package-name>

# Or manually update pyproject.toml and regenerate lock file
uv lock

Running Tests

# Run all tests
uv run python -m pytest

# Run specific tests
uv run python test_mlx.py
uv run python test_ocr.py

Code Formatting

# Format code with black (if configured)
uv run black .

# Sort imports with isort (if configured)
uv run isort .

Project Structure

SmartBlogger/
├── app.py              # Main application entry point
├── pyproject.toml      # Project configuration and dependencies
├── uv.lock            # Locked dependencies (generated by uv)
├── README.md          # Project overview
├── docs/              # Documentation files
├── models/            # LLM management and model utilities
├── nodes/             # Workflow nodes
├── services/          # External service integrations
├── ui/                # User interface components
│   ├── theme.py       # Custom theme and styling
│   ├── sidebar.py     # Sidebar components
│   ├── dashboard.py   # Main dashboard components
│   ├── loading_screen.py # Loading screen components
│   ├── footer.py      # Footer components
│   └── components.py  # Reusable UI components
├── utils/             # Utility functions
└── workflows/         # Workflow definitions

Testing Changes

  1. Run the MLX test to verify Apple Silicon optimizations:

    uv run python test_mlx.py

  2. Run the image processing test to verify image processing:

    uv run python test_image_processing.py

  3. Start the application to test end-to-end functionality:

    uv run streamlit run app.py

Troubleshooting

Dependency Issues

If you encounter dependency conflicts:

# Regenerate lock file
uv lock --upgrade

# Or resolve conflicts manually
uv sync --resolution highest

Environment Issues

If the environment becomes corrupted:

# Remove virtual environment
rm -rf .venv

# Recreate environment
uv sync

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests to ensure everything works
  5. Submit a pull request