# Familiar Integration Guide

This document explains how to integrate your actual Familiar v2.5.1 codebase 
with the Familiar Launcher for a complete distribution.

## Quick Integration

1. **Extract your Familiar zip:**
   ```bash
   unzip familiar-v1_0_3.zip -d temp/
   ```

2. **Replace the stub familiar/ folder:**
   ```bash
   rm -rf familiar_unified/familiar
   cp -r temp/familiar familiar_unified/familiar
   ```

3. **Verify structure:**
   ```
   familiar_unified/
   ├── FamiliarLauncher.py
   ├── launcher/
   └── familiar/           ← Your actual code now here
       ├── __init__.py
       ├── core/
       │   ├── agent.py
       │   ├── config.py
       │   ├── providers.py
       │   ├── local_llm.py
       │   └── ...
       ├── skills/
       ├── channels/
       └── ...
   ```

4. **Test:**
   ```bash
   python FamiliarLauncher.py --cli
   ```

## Required Interfaces

The launcher expects these interfaces from your Familiar code:

### familiar/core/agent.py

```python
class Agent:
    def __init__(self, config=None):
        """Initialize with optional config."""
        pass
    
    def chat(self, message: str, user_id: str = "default") -> str:
        """Send message, get response."""
        pass
    
    def status(self) -> dict:
        """Return status dict."""
        pass
```

### familiar/core/config.py

```python
class Config:
    @classmethod
    def load(cls, path=None) -> "Config":
        """Load from YAML file."""
        pass
```

## Launcher Integration Points

The launcher interacts with Familiar in these ways:

1. **Agent Subprocess** (launcher/agent.py)
   - Starts: `python -m familiar --provider local --web-ui`
   - Stops: SIGTERM then SIGKILL
   - Monitors: stdout/stderr for logs

2. **Config Loading** (FamiliarLauncher.py)
   - Reads: `~/.familiar/config.yaml`
   - Expects: YAML with llm, agent, server sections

3. **Model Path**
   - Models stored: `~/.familiar/models/*.gguf`
   - Passed to agent via `--local-model-path`

## Building Standalone Executable

After integrating your code:

```bash
# Install PyInstaller
pip install pyinstaller

# Build
pyinstaller FamiliarLauncher.spec

# Output
dist/Familiar          # Linux/Mac executable
dist/Familiar.exe      # Windows executable
dist/Familiar.app      # macOS app bundle
```

## File Sizes

| Component | Size |
|-----------|------|
| Launcher only | ~15-20 MB |
| + Familiar stubs | ~20-25 MB |
| + Full Familiar | ~30-40 MB |
| + Bundled model | +400 MB to +5 GB |

## Distribution Options

### Option A: Launcher + Download
- Distribute just the launcher (~20 MB)
- Users download models on first run
- Smallest initial download

### Option B: Full Bundle
- Include a default model
- Larger download (~1.5 GB with Qwen 1.5B)
- Works immediately out of box

### Option C: Separate Downloads
- Launcher download
- Model packs download
- Skills packs download
- Most flexible

## Testing Checklist

Before release:

- [ ] GUI launches on Windows
- [ ] GUI launches on macOS
- [ ] GUI launches on Linux
- [ ] GUI launches on Pi
- [ ] Quick Setup downloads model
- [ ] Agent starts successfully
- [ ] Web UI opens
- [ ] Chat works
- [ ] CLI mode works
- [ ] Headless mode works

## Troubleshooting

### "Module not found: familiar"
Your familiar/ folder structure doesn't match expected.
Check that `familiar/__init__.py` exists.

### "Agent won't start"
Check logs in `~/.familiar/logs/familiar.log`

### "Model not loading"
Verify model path: `ls ~/.familiar/models/*.gguf`

### "GUI is slow"
The Tkinter GUI is lightweight but not optimized for heavy use.
For better performance, use the web UI via `--web-only`.
