Metadata-Version: 2.4
Name: viir-cli
Version: 1.0.0
Summary: Official CLI tool for viir.tech — Viir Phuria Portfolio, Research & AI Agent Gateway
Home-page: https://viir.tech
Author: Viir Phuria
Author-email: Viir Phuria <virvphuria@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://viir.tech
Project-URL: Documentation, https://viir.tech/cli/
Project-URL: API Docs, https://viir.tech/docs/
Project-URL: MCP Server, https://viir.tech/mcp/
Project-URL: Repository, https://github.com/Viir-Phuria/viir_portfolio
Project-URL: Changelog, https://viir.tech/deprecation
Keywords: viir,viir.tech,viir-cli,cybersecurity,mcp,deep-learning,agentic
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Viir Phuria — Elite Engineering Portfolio & AI Agent Gateway

[![CI Pipeline](https://github.com/Viir-Phuria/viir_portfolio/actions/workflows/ci.yml/badge.svg)](https://github.com/Viir-Phuria/viir_portfolio/actions)
[![Django CI/CD](https://github.com/Viir-Phuria/viir_portfolio/actions/workflows/django.yml/badge.svg)](https://github.com/Viir-Phuria/viir_portfolio/actions)
[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![Django Version](https://img.shields.io/badge/django-4.2%20LTS-green.svg)](https://www.djangoproject.com/)
[![Is Agentic Score](https://img.shields.io/badge/Is--Agentic-100%2F100-brightgreen.svg)](https://viir.tech/llms.txt)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Security: Hardened](https://img.shields.io/badge/security-hardened-blueviolet.svg)](https://viir.tech/SECURITY.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Production codebase powering [viir.tech](https://viir.tech) — a high-performance, defense-in-depth engineering portfolio, research portal, and AI agent interface built by **Viir Phuria** (Cybersecurity Engineer, Security Consultant, Full-Stack Developer, and IEEE Researcher).

---

## Architecture Overview

```
                      +-----------------------------+
                      |   Cloudflare Managed DNS    |
                      |   (DNS-Only Apex + CNAME)   |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |      Vercel Edge Proxy      |
                      | (SSL, www->apex, CDN Cache) |
                      +--------------+--------------+
                                     |
                                     v
                      +-----------------------------+
                      |   PythonAnywhere Host       |
                      |   (Gunicorn WSGI App)       |
                      +--------------+--------------+
                                     |
             +-----------------------+-----------------------+
             |                                               |
             v                                               v
+--------------------------+                   +--------------------------+
|      Django 4.2 LTS      |                   |    Static & Media Assets |
|  - Content Security Policy|                   |  - WhiteNoise Storage    |
|  - Argon2 Password Hasher|                   |  - Offline CSS Compressor|
|  - nh3 Rust XSS Filter   |                   +--------------------------+
|  - Model Context Protocol|
|  - RFC 9457 & RateLimits |
+------------+-------------+
             |
             v
+--------------------------+
|  Storage & Encryption    |
|  - Encrypted PII Fields  |
|  - Dynamic Cache Backend |
|  - SQLite / PostgreSQL   |
+--------------------------+
```

---

## Core Capabilities

### 1. Defense-in-Depth Security
- **Argon2 Password Hashing**: Utilizes `ParanoidArgon2Hasher` configured with elevated memory and time costs.
- **Content Security Policy (CSP)**: Per-request cryptographically secure random nonces injected via middleware (`nonce-{secret}`). Disables `unsafe-inline` scripts.
- **Data-at-Rest Encryption**: Visitor contact details, emails, and phone numbers are encrypted at the database level using `django-cryptography`.
- **Rust-based HTML Sanitization**: Powered by `nh3` (Ammonia binding in Rust) for blog posts and rich content rendering.
- **Brute-Force Lockout**: Integrated with `django-axes` (5 failure limit, 1-hour cool-off, IP-based tracking).
- **HSTS Preload**: Strict Transport Security with subdomains and preload flags (`max-age=31536000`).

### 2. Autonomous Agent & AI Discoverability (100/100 Score)
- **`llms.txt` & `llms-full.txt`**: Standardized machine-readable agent documentation conforming to [llmstxt.org](https://llmstxt.org).
- **Model Context Protocol (MCP)**: Streamable JSON-RPC endpoint and manifest at `/.well-known/mcp.json` providing portfolio context tools to LLM agents.
- **Content Negotiation (acceptmarkdown.com)**: Requests with `Accept: text/markdown` receive clean Markdown context rather than HTML.
- **Agent-Friendly 404s**: Probes requesting markdown on missing routes receive markdown problem summaries with links to sitemaps and documentation.
- **RFC 9457 Problem Details**: Standardized API error format returning `application/problem+json`.
- **RFC 8594 & IETF RateLimit Headers**: Comprehensive sunset notices, deprecation dates, and proactive rate-limit indicators on all API routes.

### 3. Developer Portal & REST API v1
- **OpenAPI 3.1 Specification**: Hosted at `/api/openapi.json` and `/api/v1/openapi.json`.
- **Developer Portal**: Live interactive documentation at [`https://viir.tech/developer/`](https://viir.tech/developer/).
- **Official CLI SDK**: `viir-cli` Python package specification for rapid terminal querying of portfolio data.

---

## Public REST Endpoints

All REST API endpoints support both JSON and Markdown content negotiation:

| Endpoint | Method | Description |
|---|---|---|
| `/api/v1/health` | `GET` | System health check and uptime status |
| `/api/v1/dossier` | `GET` | Complete machine-readable candidate dossier |
| `/api/v1/projects` | `GET` | Verified engineering projects, tags, and repos |
| `/api/v1/publications` | `GET` | Academic publications and IEEE conference papers |
| `/api/v1/contact` | `POST` | Encrypted recruiter and consulting contact form |
| `/api/v1/mcp` | `POST` | Model Context Protocol JSON-RPC stream |
| `/api/openapi.json` | `GET` | OpenAPI 3.1 specification schema |
| `/llms.txt` | `GET` | Concise LLM overview & agent guidance |
| `/llms-full.txt` | `GET` | Expanded complete system context dossier |

---

## Local Development & Quickstart

### 1. Prerequisites
- Python 3.11+
- Virtual environment (`venv`)
- Git

### 2. Setup Instructions

```bash
# Clone repository
git clone https://github.com/Viir-Phuria/viir_portfolio.git
cd viir_portfolio

# Create and activate virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your specific local settings

# Run database migrations
python manage.py migrate

# Create administrative user
python manage.py createsuperuser

# Start development server
python manage.py runserver
```

Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser. The administrative portal is accessible at `http://127.0.0.1:8000/dashboard/`.

---

## Testing & Quality Assurance

We maintain a rigorous test suite of 47 automated tests verifying agentic readiness, rate-limiting, CSP nonce generation, content negotiation, and API schemas:

```bash
# Run unit test suite
python manage.py test viir_folio

# Run tests with pytest
pytest

# Code style formatting check
black --check .

# Linting and syntax check
flake8 viir_folio viir_portfolio --statistics --max-line-length=127

# Check for uncommitted database migrations
python manage.py makemigrations --check --dry-run

# Production security deployment checklist verification
python manage.py check --deploy
```

---

## Environment Variables Reference

| Variable | Type | Default | Description |
|---|---|---|---|
| `SECRET_KEY` | `string` | *Required* | Django cryptographic signing secret |
| `DEBUG` | `bool` | `False` | Enables debugging toolbar/detailed traces |
| `ALLOWED_HOSTS` | `string` | `viir.tech,...` | Comma-delimited list of host headers |
| `SITE_DOMAIN` | `string` | `viir.tech` | Primary apex domain |
| `SECURE_SSL_REDIRECT` | `bool` | `True` | Forces HTTPS redirect on requests |
| `SECURE_HSTS_SECONDS` | `int` | `31536000` | HTTP Strict Transport Security duration (1 year) |
| `COMPRESS_ENABLED` | `bool` | `False` | Enables django-compressor asset minification |
| `COMPRESS_OFFLINE` | `bool` | `False` | Pre-compresses static assets offline |
| `SENTRY_DSN` | `string` | `""` | Sentry Application Performance Monitoring DSN |
| `EMAIL_HOST_USER` | `string` | `""` | SMTP sender email username |
| `EMAIL_HOST_PASSWORD` | `string` | `""` | SMTP application-specific password |
| `EMAIL_RECIPIENT_EMAIL` | `string`| `""` | Inbox destination for contact form submissions |

---

## Production Deployment Checklist

When deploying changes to PythonAnywhere / Vercel:

1. **Pull Latest Changes**:
   ```bash
   git pull origin main
   ```
2. **Collect Static Files**:
   ```bash
   python manage.py collectstatic --noinput
   ```
3. **Compile Offline Compressed Bundles** (if `COMPRESS_OFFLINE=True`):
   ```bash
   python manage.py compress --force
   ```
4. **Apply Migrations**:
   ```bash
   python manage.py migrate
   ```
5. **Reload WSGI Process**:
   ```bash
   touch /var/www/viir_pythonanywhere_com_wsgi.py
   ```

---

## Contributing & Security

- **Security Advisories**: Please review [SECURITY.md](SECURITY.md) for vulnerability reporting and coordinated disclosure guidelines.
- **Contributing**: Please review [CONTRIBUTING.md](CONTRIBUTING.md) for coding conventions, commit standards, and pull request procedures.
- **Changelog**: Release history and updates are documented in [CHANGELOG.md](CHANGELOG.md).

---

## License

This project is open-source software licensed under the [MIT License](LICENSE).
