ai-software-factory/ai_software_factory/README.md

# AI Software Factory

Automated software generation service powered by Ollama LLM. This service allows users to specify via Telegram what kind of software they would like, and an agent hosted in Ollama will create it iteratively, testing it while building out the source code and committing to gitea.

## Features

- **Telegram Integration**: Receive software requests via Telegram bot
- **Ollama LLM**: Uses Ollama-hosted models for code generation
- **Git Integration**: Automatically commits code to gitea
- **Pull Requests**: Creates PRs for user review before merging
- **Web UI**: Beautiful dashboard for monitoring project progress
- **n8n Workflows**: Bridges Telegram with LLMs via n8n webhooks
- **Comprehensive Testing**: Full test suite with pytest coverage

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌──────────┐     ┌─────────┐
│   Telegram  │────▶│   n8n Webhook│────▶│ FastAPI  │────▶│  Ollama │
└─────────────┘     └──────────────┘     └──────────┘     └─────────┘
                                                                         │
                                                                         ▼
                                                                 ┌──────────────┐
                                                                 │   Git/Gitea  │
                                                                 └──────────────┘
```

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Ollama running locally or on same network
- Gitea instance with API token
- n8n instance for Telegram webhook

### Configuration

Create a `.env` file in the project root:

```bash
# Server
HOST=0.0.0.0
PORT=8000

# Ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3

# Gitea
GITEA_URL=https://gitea.yourserver.com
GITEA_TOKEN= analyze your_gitea_api_token
GITEA_OWNER=ai-software-factory
GITEA_REPO=ai-software-factory

# n8n
N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram

# Telegram
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_chat_id
```

### Build and Run

```bash
# Build Docker image
docker build -t ai-software-factory -f Containerfile .

# Run with Docker Compose
docker-compose up -d
```

### Usage

1. **Send a request via Telegram:**

   ```
   Name: My Awesome App
   Description: A web application for managing tasks
   Features: user authentication, task CRUD, notifications
   ```

2. **Monitor progress via Web UI:**

   Open `http://yourserver:8000` to see real-time progress

3. **Review PRs in Gitea:**

   Check your gitea repository for generated PRs

## API Endpoints

| Endpoint | Method | Description |
|------|------|-------|
| `/` | GET | API information |
| `/health` | GET | Health check |
| `/generate` | POST | Generate new software |
| `/status/{project_id}` | GET | Get project status |
| `/projects` | GET | List all projects |

## Development

### Makefile Targets

```bash
make help          # Show available targets
make setup         # Initialize repository
make fmt           # Format code
make lint          # Run linters
make test          # Run tests
make test-cov      # Run tests with coverage report
make release       # Create new release tag
make build         # Build Docker image
```

### Running in Development

```bash
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### Testing

Run the test suite:

```bash
# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run specific test file
pytest tests/test_main.py -v

# Run tests with verbose output
pytest tests/ -v --tb=short
```

### Test Coverage

View HTML coverage report:

```bash
make test-cov
open htmlcov/index.html
```

### Test Structure

```
tests/
├── conftest.py              # Pytest fixtures and configuration
├── test_main.py             # Tests for main.py FastAPI app
├── test_config.py           # Tests for config.py settings
├── test_git_manager.py      # Tests for git operations
├── test_ui_manager.py       # Tests for UI rendering
├── test_gitea.py            # Tests for Gitea API integration
├── test_telegram.py         # Tests for Telegram integration
├── test_orchestrator.py     # Tests for agent orchestrator
├── test_integration.py      # Integration tests for full workflow
├── test_config_integration.py # Configuration integration tests
├── test_agents_integration.py # Agent integration tests
├── test_edge_cases.py       # Edge case tests
└── test_postgres_integration.py # PostgreSQL integration tests
```

## Project Structure

```
ai-software-factory/
├── main.py                 # FastAPI application
├── config.py               # Configuration settings
├── requirements.txt        # Python dependencies
├── Containerfile           # Docker build file
├── README.md               # This file
├── Makefile                # Development utilities
├── .env.example            # Environment template
├── .gitignore              # Git ignore rules
├── HISTORY.md              # Changelog
├── pytest.ini              # Pytest configuration
├── docker-compose.yml      # Multi-service orchestration
├── .env                    # Environment variables (not in git)
├── tests/                  # Test suite
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_*.py          # Test files
│   └── pytest.ini
├── agents/
│   ├── __init__.py
│   ├── orchestrator.py     # Main agent orchestrator
│   ├── git_manager.py      # Git operations
│   ├── ui_manager.py       # Web UI management
│   ├── telegram.py         # Telegram integration
│   └── gitea.py            # Gitea API client
└── n8n/                    # n8n webhook configurations
```

## Security Notes

- Never commit `.env` files to git
- Use environment variables for sensitive data
- Rotate Gitea API tokens regularly
- Restrict Telegram bot permissions
- Use HTTPS for Gitea and n8n endpoints

## License

MIT License - See LICENSE file for details

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.