opencrates 0.1.0

# OpenCrates

[![Build Status](https://github.com/nikjois/opencrates/workflows/CI/badge.svg)](https://github.com/nikjois/opencrates/actions)
[![Crates.io](https://img.shields.io/crates/v/opencrates.svg)](https://crates.io/crates/opencrates)
[![Documentation](https://docs.rs/opencrates/badge.svg)](https://docs.rs/opencrates)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](https://opensource.org/licenses/MIT)

**OpenCrates** is a powerful AI-driven Rust crate generator that leverages OpenAI's latest models to create production-ready Rust projects with comprehensive testing, documentation, and enterprise-grade observability features.

## Features

### Core Capabilities
- **AI-Powered Generation**: Uses GPT-4, GPT-4 Turbo, and other OpenAI models
- **Web Search Integration**: Enhanced context through real-time web search
- **Interactive Wizard**: Step-by-step crate creation process
- **Comprehensive Testing**: Automated unit, integration, and benchmark tests
- **Documentation**: Auto-generated docs with examples and API references
- **Containerization**: Docker and Docker Compose support
- **Template System**: Extensible template engine for different project types

### Enterprise Features
- **Observability**: Prometheus metrics, distributed tracing, health checks
- **Security**: Built-in security scanning and vulnerability detection
- **Performance**: Benchmarking and performance regression detection
- **Web API**: FastAPI integration for web-based interactions
- **Caching**: Multi-layer caching with Redis support
- **CI/CD**: GitHub Actions workflows and automated deployment

### Supported Project Types
- CLI Tools and Applications
- Libraries and APIs
- Web Services (Axum, Warp, Actix)
- Async Libraries
- Data Processing Pipelines
- Game Development
- Embedded Systems
- Custom Templates

## Quick Start

### Prerequisites

- **Rust** 1.70.0 or later
- **OpenAI API Key** (required for AI features)
- **Docker** (optional, for containerization)
- **Redis** (optional, for caching)

### Installation

#### From Crates.io
```bash
cargo install opencrates
```

#### From Source
```bash
git clone https://github.com/nikjois/opencrates.git
cd opencrates
cargo install --path .
```

#### Using Docker
```bash
docker pull nikjois/opencrates:latest
docker run -it --rm nikjois/opencrates:latest --help
```

### Configuration

1. **Set up your OpenAI API key**:
```bash
export OPENAI_API_KEY="your-api-key-here"
```

2. **Configure OpenCrates** (optional):
```bash
opencrates config
```

3. **Verify installation**:
```bash
opencrates --help
```

## Usage

### Interactive Mode
```bash
opencrates
```
This launches the interactive wizard that guides you through creating a new crate.

### Command Line Mode
```bash
# Create a CLI tool
opencrates create "A command-line tool for managing Docker containers"

# Create with specific options
opencrates create "Web API for user management" \
  --template web-api \
  --features "postgres,redis,metrics" \
  --model gpt-4 \
  --search-web

# Create interactively
opencrates create --interactive
```

### Web Search Integration
```bash
# Search for Rust patterns and examples
opencrates search "async Rust patterns with tokio"

# Search with custom limit
opencrates search "Rust web frameworks comparison" --limit 20
```

### Testing and Quality Assurance
```bash
# Run the built-in test suite
opencrates test

# Run specific test scenarios
opencrates test --scenario basic
opencrates test --all

# List available templates
opencrates templates
```

## Architecture

OpenCrates is built with a modular architecture:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Interface │    │   Web Interface │    │   API Interface │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      Core Engine          │
                    │  ┌─────────────────────┐  │
                    │  │  Stage Orchestrator │  │
                    │  └─────────────────────┘  │
                    └─────────────┬─────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        │                         │                         │
┌───────▼────────┐    ┌───────────▼──────────┐    ┌────────▼────────┐
│   Providers    │    │      Utilities       │    │    Templates    │
│                │    │                      │    │                 │
│ • OpenAI       │    │ • Config Management  │    │ • CLI Templates │
│ • Web Search   │    │ • Caching           │    │ • Web Templates │
│ • Templates    │    │ • Metrics           │    │ • Lib Templates │
│                │    │ • Health Checks     │    │ • Custom Types  │
└────────────────┘    │ • Error Handling    │    └─────────────────┘
                      │ • FastAPI Integration│
                      └─────────────────────┘
```

### Core Components

1. **Stage Orchestrator**: Manages the crate generation pipeline
2. **Providers**: External service integrations (OpenAI, web search)
3. **Templates**: Extensible template system for different project types
4. **Utilities**: Cross-cutting concerns (config, caching, metrics)

## Configuration

OpenCrates can be configured through:

1. **Environment Variables**:
```bash
export OPENAI_API_KEY="your-key"
export OPENCRATES_MODEL="gpt-4"
export OPENCRATES_CACHE_TTL="3600"
export REDIS_URL="redis://localhost:6379"
```

2. **Configuration File** (`~/.config/opencrates/config.toml`):
```toml
[openai]
api_key = "your-key"
default_model = "gpt-4"
max_tokens = 4000
temperature = 0.7

[cache]
enabled = true
ttl = 3600
redis_url = "redis://localhost:6379"

[web_search]
enabled = true
max_results = 10

[templates]
custom_path = "~/.config/opencrates/templates"

[metrics]
enabled = true
prometheus_port = 9090
```

3. **Interactive Configuration**:
```bash
opencrates config
```

## Docker Support

### Using Pre-built Images
```bash
# Run with environment variables
docker run -e OPENAI_API_KEY="your-key" nikjois/opencrates:latest create "my awesome crate"

# Run interactively
docker run -it -e OPENAI_API_KEY="your-key" nikjois/opencrates:latest
```

### Building from Source
```bash
# Build the image
docker build -t opencrates:local .

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

### Docker Compose Setup
```yaml
version: '3.8'
services:
  opencrates:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    ports:
      - "8000:8000"
      - "9090:9090"
  
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
  
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9091:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
```

## Testing

### Running Tests
```bash
# Run all tests
cargo test

# Run specific test suites
cargo test --lib                    # Unit tests
cargo test --test integration       # Integration tests
cargo test --doc                    # Documentation tests

# Run benchmarks
cargo bench

# Run the comprehensive test suite
./test_all.sh
```

### Test Coverage
```bash
# Install tarpaulin
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out Html
```

### Performance Testing
```bash
# Run benchmarks
cargo bench

# Profile with flamegraph
cargo install flamegraph
cargo flamegraph --bin opencrates -- create "test crate"
```

## Monitoring and Observability

### Metrics
OpenCrates exposes Prometheus metrics on port 9090:

- **Request metrics**: HTTP request duration, count, errors
- **Generation metrics**: Crate generation time, success rate
- **Cache metrics**: Hit rate, miss rate, eviction count
- **Health metrics**: Component health status

### Health Checks
Health check endpoint available at `/health`:

```bash
curl http://localhost:8000/health
```

### Distributed Tracing
OpenCrates supports distributed tracing with Jaeger:

```bash
# Start Jaeger
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 14268:14268 \
  jaegertracing/all-in-one:latest

# Configure OpenCrates
export JAEGER_ENDPOINT="http://localhost:14268/api/traces"
```

## API Integration

### FastAPI Web Interface
OpenCrates includes a FastAPI web interface:

```bash
# Start the web server
opencrates serve --port 8000

# API endpoints
curl -X POST http://localhost:8000/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"description": "CLI tool for file management", "template": "cli"}'
```

### OpenAI Agents SDK Integration
```rust
use opencrates::agents::CrateAssistant;

#[tokio::main]
async fn main() -> Result<()> {
    let assistant = CrateAssistant::new("your-api-key").await?;
    
    let result = assistant.generate_crate(
        "A web scraper for e-commerce sites",
        GenerationOptions::default()
    ).await?;
    
    println!("Generated crate: {}", result.name);
    Ok(())
}
```

## Development

### Building from Source
```bash
git clone https://github.com/nikjois/opencrates.git
cd opencrates

# Install dependencies
cargo build

# Run in development mode
cargo run -- --help

# Run with all features
cargo run --all-features -- create "test crate"
```

### Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run the test suite: `./test_all.sh`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Development Tools
```bash
# Install development tools
cargo install cargo-watch cargo-audit cargo-deny

# Watch for changes
cargo watch -x check -x test

# Security audit
cargo audit

# License and dependency checking
cargo deny check
```

## Examples

### CLI Tool Example
```bash
opencrates create "A CLI tool for managing Kubernetes deployments" \
  --template cli \
  --features "clap,serde,tokio" \
  --model gpt-4
```

### Web API Example
```bash
opencrates create "REST API for a blog platform" \
  --template web-api \
  --features "axum,sqlx,redis" \
  --search-web
```

### Library Example
```bash
opencrates create "A high-performance JSON parser" \
  --template library \
  --features "serde,benchmarks" \
  --no-docs false
```

## Troubleshooting

### Common Issues

1. **OpenAI API Key Issues**:
```bash
# Verify your API key
echo $OPENAI_API_KEY

# Test API connectivity
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models
```

2. **Build Issues**:
```bash
# Clean and rebuild
cargo clean
cargo build

# Update dependencies
cargo update
```

3. **Docker Issues**:
```bash
# Check Docker daemon
docker info

# Rebuild image
docker build --no-cache -t opencrates:local .
```

### Debug Mode
```bash
# Enable debug logging
RUST_LOG=debug opencrates create "test crate"

# Enable trace logging
RUST_LOG=trace opencrates create "test crate"
```

### Performance Issues
```bash
# Profile the application
cargo install flamegraph
cargo flamegraph --bin opencrates -- create "test crate"

# Check system resources
htop
```

## License

This project is licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Support

- **Documentation**: [https://docs.rs/opencrates](https://docs.rs/opencrates)
- **Issues**: [GitHub Issues](https://github.com/nikjois/opencrates/issues)
- **Repository**: [GitHub Repository](https://github.com/nikjois/opencrates)

## Author

**Nik Jois** - [nik@nikjois.com](mailto:nik@nikjois.com)

For questions, suggestions, or contributions, please open an issue on GitHub or contact the author directly.