# Python Service Generator

Generates a new Python FastAPI service for the Oshun platform.

## Usage

### Using Nx

```bash
# Generate a new service
nx generate @oshun/tools:python-service \
  --name=my-service \
  --description="My awesome service" \
  --scope=psyche \
  --port=8020

# Or use the shorthand
nx g python-service my-service
```

### Options

| Option        | Description                                 | Default     | Required |
| ------------- | ------------------------------------------- | ----------- | -------- |
| `name`        | Service name (e.g., 'my-service')           | -           | Yes      |
| `description` | Service description                         | -           | Yes      |
| `scope`       | Domain scope (psyche, veritas, metis, etc.) | psyche      | No       |
| `directory`   | Directory for the service                   | services    | No       |
| `port`        | Port number                                 | 8000        | No       |
| `projectType` | Project type (application/library)          | application | No       |

## Generated Structure

```
services/{scope}/{name}/
├── pyproject.toml        # Poetry configuration
├── project.json          # Nx project configuration
├── Dockerfile            # Docker container definition
├── README.md             # Service documentation
├── src/
│   └── {package_name}/
│       ├── __init__.py   # Package initialization
│       └── main.py       # FastAPI application
└── tests/
    ├── conftest.py       # Pytest fixtures
    └── test_health.py    # Health endpoint tests
```

## Features

The generated service includes:

- **FastAPI Application** - Modern Python web framework
- **Health Endpoints** - `/health`, `/ready`, and `/` endpoints
- **CORS Middleware** - Configurable CORS support
- **Lifespan Management** - Async startup/shutdown hooks
- **Structured Logging** - Configured logging
- **Docker Support** - Multi-stage Dockerfile with non-root user
- **Testing** - Pytest with async support and fixtures
- **Linting** - Ruff and Black for code quality
- **Type Checking** - MyPy for static type analysis
- **Nx Integration** - Full Nx project with 13 targets

## Nx Targets

| Target         | Description                             |
| -------------- | --------------------------------------- |
| `serve`        | Development server with hot reload      |
| `serve-prod`   | Production server with multiple workers |
| `build`        | Build the package                       |
| `install`      | Install dependencies                    |
| `lint`         | Run Ruff linter                         |
| `lint-fix`     | Fix linting issues                      |
| `format`       | Format code with Black                  |
| `format-check` | Check code formatting                   |
| `typecheck`    | Run MyPy type checker                   |
| `test`         | Run pytest                              |
| `test-cov`     | Run tests with coverage                 |
| `docker-build` | Build Docker image                      |
| `docker-run`   | Run Docker container                    |

## Example

```bash
# Generate a new Psyche persona management service
nx generate @oshun/tools:python-service \
  --name=persona-manager \
  --description="Persona management service for Psyche AI assistants" \
  --scope=psyche \
  --port=8025

# Start development
nx serve psyche-persona-manager

# Run tests
nx test psyche-persona-manager

# Build Docker image
nx docker-build psyche-persona-manager
```
