AI Consultant Portfolio Site

A YAML-driven static site generator for AI consultants — edit your site with natural language via browser or CLI, preview locally, and deploy to GitHub Pages. Built with Clean Architecture and TDD.

Live Demo: (your GitHub Pages URL after deployment)

---

🚀 Getting Started (2 Minutes)

What You'll Need

• Python 3.11+ — Download here
• Git — Download here
• A GitHub account — Sign up free

Step 1 — Fork & Clone

1. Click the Fork button at the top of this GitHub page
2. Open your terminal and run:

git clone https://github.com/YOUR_USERNAME/ai-portfolio.git
cd ai-portfolio

Step 2 — Install & Setup

# Create a virtual environment
python -m venv .venv && source .venv/bin/activate

# Install everything
pip install -e ".[dev]"

# Run the setup wizard
site setup

The setup wizard walks you through configuring your .env file and checks that everything is ready.

Step 3 — Open the Admin Dashboard

site admin

Open http://localhost:8888/admin in your browser. You'll see:

• 🩺 System Health — real-time status of all services
• 💬 Chat Console — edit your site with plain English
• ⚡ Quick Actions — build, publish, and rollback in one click

First time? Visit http://localhost:8888/admin/setup for guided configuration.

Step 4 — Deploy to GitHub Pages

1. On GitHub: Settings → Pages → Source: GitHub Actions
2. Push your changes:

git add . && git commit -m "Personalize my site" && git push

3. Visit https://YOUR_USERNAME.github.io/ai-portfolio/ in ~60 seconds

🎉 Your site is live!

---

✏️ Editing Your Site

Option A — Browser Dashboard (Recommended)

site admin

Open http://localhost:8888/admin and use the Chat Console:

1. Type: "Change my tagline to 'AI-Powered Growth for Your Business'"
2. Click Preview Changes — see a diff of what will change
3. Click Apply & Rebuild — changes are saved and site is rebuilt
4. Click Publish — push to GitHub Pages

Option B — CLI (Power Users)

# Natural language editing
site chat "Add a service called 'AI Audit'"

# Direct YAML editing
site update --confirm '{"site_info": {"tagline": "New Tagline"}}'
site build

# Preview locally
site preview

Option C — Edit content/content.yaml Directly

Open the file, make changes, then run site build.

---

📋 Command Reference

Command	What It Does
site setup	Interactive setup wizard for first-time configuration
site admin	Start the browser admin dashboard on port 8888
site doctor	Check if everything is set up correctly
site build	Generate the HTML site from your content
site preview	Start local server to preview your site
site chat "..."	Edit your site with natural language
site validate	Check your content.yaml for errors
site diff '<json>'	Preview changes without applying them
site update '<json>'	Apply JSON changes (add --confirm)
site publish	Build + git push to GitHub Pages
site rollback	Undo the last change

Tip: Add --json to any command for machine-readable output.

---

🏗️ Architecture

                    ┌─────────────────────────┐
                    │   Browser Dashboard     │
                    │   localhost:8888/admin   │
                    └──────────┬──────────────┘
                               │ HTTP (JSON)
                    ┌──────────▼──────────────┐
                    │   FastAPI REST API       │
                    │   /api/doctor, /api/chat │
                    │   /api/build, /api/publish│
                    └──────────┬──────────────┘
                               │ Use Cases
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
       ┌──────────┐    ┌──────────┐    ┌──────────┐
       │  Doctor   │    │ ChatEdit │    │  Build   │
       │ UseCase   │    │ UseCase  │    │ UseCase  │
       └─────┬────┘    └────┬─────┘    └────┬─────┘
             │              │               │
       ┌─────▼──────────────▼───────────────▼────┐
       │         Domain (Entities, Services)      │
       └─────────────────┬───────────────────────┘
                         │
       ┌─────────────────▼───────────────────────┐
       │    Infrastructure (YAML, Jinja2, LLM)   │
       └─────────────────────────────────────────┘

Clean Architecture Layers

Layer	Path	What It Does
Domain	domain/	Data models, business rules, abstractions
Application	application/	Use cases: build, chat, doctor, publish, rollback
Infrastructure	infrastructure/	YAML, Jinja2, LLM adapters, Git
Interfaces	interfaces/cli/	CLI commands (Typer)
Interfaces	interfaces/web/	REST API + admin dashboard (FastAPI)

---

🧪 Development

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
python -m pytest tests/ -v

# Lint + format
ruff check src/ tests/ && black --check src/ tests/

Project Structure

ai-portfolio/
├── content/
│   └── content.yaml          ← Your site data (single source of truth)
├── templates/
│   ├── base.html             ← Page template
│   ├── admin.html            ← Admin dashboard
│   └── setup.html            ← Setup wizard
├── static/css/               ← Custom CSS
├── src/consultant_site/
│   ├── domain/               ← Entities, ports, services
│   ├── application/          ← Use cases
│   ├── infrastructure/       ← Adapters (YAML, Jinja2, LLM, Git)
│   └── interfaces/
│       ├── cli/              ← CLI commands
│       └── web/              ← REST API + admin dashboard
├── tests/
│   ├── unit/                 ← Domain + service tests
│   ├── integration/          ← Adapter integration tests
│   ├── cli/                  ← CLI command tests
│   └── e2e/                  ← End-to-end acceptance tests
├── .github/workflows/        ← CI/CD pipelines
├── pyproject.toml
└── .env.example

---

💰 Cost

Component	Cost
Hosting (GitHub Pages)	Free
Contact form (Formspree)	Free (50/month)
Booking (Calendly)	Free
CSS framework (Pico.css)	Free
AI editing (Ollama)	Free (local)
AI editing (OpenAI/Gemini)	Pay-as-you-go (optional)

No monthly subscriptions required.

---

License

MIT