INSTALLATION_GUIDE.md

# luwa-01 Installation & Deployment Guide

## Get luwa-01 Running in 5 Minutes

This guide shows you how to set up luwa-01 on your machine, server, or cloud — no GPU required.

---

## Requirements

| Requirement | Minimum |
|-------------|---------|
| **RAM** | 4 GB |
| **Disk space** | 1 GB (model is 942 MB) |
| **Python** | 3.8 or higher |
| **GPU** | Not required (works on CPU) |
| **Internet** | Required for initial download only |

---

## Method 1: Quick Start (Python)

The fastest way to get luwa-01 running:

```bash
pip install transformers torch
```

Then create a file called `chat.py`:

```python
from transformers import AutoTokenizer, AutoModelForCausalLM

# Load the model (downloads automatically on first run)
model = AutoModelForCausalLM.from_pretrained(
    "chatpbc1/luwa-01",
    trust_remote_code=True,
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("chatpbc1/luwa-01")

# Your question
question = "What is the market size for AI in healthcare in 2026?"

# Format the message
messages = [{"role": "user", "content": question}]
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)

# Generate response
inputs = tokenizer(text, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=512)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)

print(response)
```

Run it:
```bash
python chat.py
```

---

## Method 2: Interactive Chat

Create a simple chat loop so you can have a conversation with luwa-01:

```python
from transformers import AutoTokenizer, AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("chatpbc1/luwa-01", trust_remote_code=True, device_map="auto")
tokenizer = AutoTokenizer.from_pretrained("chatpbc1/luwa-01")

print("luwa-01 Business Intelligence Agent")
print("Type your question (or 'quit' to exit)\n")

messages = []
while True:
    user_input = input("You: ")
    if user_input.lower() == "quit":
        break
    messages.append({"role": "user", "content": user_input})
    
    text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(text, return_tensors="pt").to(model.device)
    outputs = model.generate(**inputs, max_new_tokens=512)
    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
    
    print(f"\nluwa-01: {response}\n")
    messages.append({"role": "assistant", "content": response})
```

---

## Method 3: Deploy as a Web API

Turn luwa-01 into a REST API server that your apps can call:

```bash
pip install transformers torch fastapi uvicorn
```

Create `server.py`:

```python
from fastapi import FastAPI
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

app = FastAPI()

# Load model once at startup
model = AutoModelForCausalLM.from_pretrained("chatpbc1/luwa-01", trust_remote_code=True, device_map="auto")
tokenizer = AutoTokenizer.from_pretrained("chatpbc1/luwa-01")

@app.post("/chat")
async def chat(request: dict):
    prompt = request.get("prompt", "")
    max_tokens = request.get("max_tokens", 512)
    
    messages = [{"role": "user", "content": prompt}]
    text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(text, return_tensors="pt").to(model.device)
    
    with torch.no_grad():
        outputs = model.generate(**inputs, max_new_tokens=max_tokens)
    
    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
    return {"response": response}
```

Start the server:
```bash
uvicorn server:app --host 0.0.0.0 --port 8000
```

Then call it:
```bash
curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d '{"prompt": "Analyze the AI market", "max_tokens": 256}'
```

---

## Method 4: Deploy on Modal (Cloud GPU)

For production with automatic scaling:

**Step 1:** Sign up at [modal.com](https://modal.com)

**Step 2:** Install Modal:
```bash
pip install modal
modal token new
```

**Step 3:** Create your HF secret:
```bash
modal secret create hf-token HF_TOKEN=YOUR_HF_TOKEN
```

**Step 4:** Deploy:
```bash
modal deploy deploy_luwa.py
```

You'll get a URL like:
```
https://your-username--luwa-01-service.modal.run
```

**Step 5:** Use it from anywhere:
```bash
curl -X POST https://your-username--luwa-01-service.modal.run -H "Content-Type: application/json" -d '{"prompt": "Market analysis request", "max_tokens": 512}'
```

---

## Method 5: Deploy with Docker

For containerized production:

```dockerfile
FROM python:3.11-slim

RUN pip install transformers torch fastapi uvicorn

WORKDIR /app
COPY server.py .

EXPOSE 8000
CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"]
```

```bash
docker build -t luwa-01 .
docker run -p 8000:8000 luwa-01
```

---

## Performance Tips

| Scenario | Recommendation |
|----------|---------------|
| **Development/Testing** | Run directly on CPU (4GB RAM) |
| **Production API** | Use Modal or any cloud GPU (T4) |
| **High traffic** | Deploy with Docker + load balancer |
| **Edge deployment** | Use ONNX export for even faster inference |

---

## Troubleshooting

**"CUDA out of memory"**
- Switch to CPU: `device_map="cpu"`
- Reduce `max_new_tokens` to 256

**"Model not found"**
- Check your internet connection
- Ensure you have `transformers >= 4.30.0`

**"Slow responses"**
- Use a GPU if available
- Reduce `max_new_tokens`
- Set `temperature=0.5` for faster deterministic output

---

## What's Included in the Repository

| File | Purpose |
|------|---------|
| `model.safetensors` | Model weights (942 MB) |
| `config.json` | Architecture settings |
| `generation_config.json` | Optimized generation parameters |
| `tokenizer.json` | Text tokenizer (152K vocabulary) |
| `tokenizer_config.json` | Tokenizer settings |
| `chat_template.jinja` | Chat formatting template |
| `system_prompt.txt` | Business intelligence persona |
| `agent_config.json` | Agent tool definitions |

---

## Next Steps

- Read the [Agent Guide](AGENT_GUIDE.md) for how to use luwa-01 effectively
- Visit the [repository](https://huggingface.co/chatpbc1/luwa-01) for the latest updates
- Join the [ChatPBC community](https://huggingface.co/chatpbc1) for support

---

Built by **ChatPBC**