add llm classification

Author: soodoku

.github/workflows/python-publish.yml

@@ -1,4 +1,5 @@
 # Publish to PyPI when a new release is created or manually triggered
+# Uses OpenID Connect trusted publishing for enhanced security
 # For more information see: https://docs.github.com/en/actions/guides/publishing-python-packages
 name: python-publish
 on:
@@ -7,10 +8,11 @@ on:
   workflow_dispatch:  # Enables manual triggering
 permissions:
   contents: read
-  id-token: write
+  id-token: write  # Required for trusted publishing with OIDC
 jobs:
   publish:
     runs-on: ubuntu-latest
+    environment: pypi  # Use PyPI environment for trusted publishing
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
@@ -25,7 +27,8 @@ jobs:
 
       - name: Build package
         run: uv build
+      
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
+        # Trusted publishing with OpenID Connect - no API token needed
+        # Configured via PyPI project settings: https://pypi.org/manage/account/publishing/

README.md

@@ -4,7 +4,7 @@
 [![PyPI Version](https://img.shields.io/pypi/v/piedomains.svg)](https://pypi.python.org/pypi/piedomains)
 [![Documentation](https://github.com/themains/piedomains/actions/workflows/docs.yml/badge.svg)](https://github.com/themains/piedomains/actions/workflows/docs.yml)
 
-**piedomains** predicts website content categories using AI analysis of domain names, text content, and homepage screenshots. Classify domains as news, shopping, adult content, education, etc. with high accuracy.
+**piedomains** predicts website content categories using traditional ML models or modern LLMs (GPT-4, Claude, Gemini). Analyze domain names, text content, and homepage screenshots to classify websites as news, shopping, adult content, education, etc. with high accuracy and flexible custom categories.
 
 ## 🚀 Quickstart
 
@@ -30,10 +30,11 @@ print(result[['domain', 'pred_label', 'pred_prob']])
 ## 📊 Key Features
 
 - **High Accuracy**: Combines text analysis + visual screenshots for 90%+ accuracy
+- **LLM-Powered**: Use GPT-4o, Claude 3.5, Gemini with custom categories and instructions
 - **Historical Analysis**: Classify websites from any point in time using archive.org
 - **Fast & Scalable**: Batch processing with caching for 1000s of domains
 - **Easy Integration**: Modern Python API with pandas output
-- **41 Categories**: From news/finance to adult/gambling content
+- **Flexible Categories**: 41 default categories or define your own with AI models
 
 ## ⚡ Usage Examples
 
@@ -78,6 +79,60 @@ results = classifier.classify_batch(
 )
 ```
 
+### 🤖 LLM-Powered Classification
+
+Use modern AI models (GPT-4, Claude, Gemini) for flexible, accurate classification:
+
+```python
+from piedomains import DomainClassifier
+
+classifier = DomainClassifier()
+
+# Configure your preferred AI provider
+classifier.configure_llm(
+    provider="openai",           # openai, anthropic, google
+    model="gpt-4o",              # multimodal model
+    api_key="sk-...",            # or set via environment variable
+    categories=["news", "shopping", "social", "tech", "education"]
+)
+
+# Text-only LLM classification
+result = classifier.classify_by_llm(["cnn.com", "github.com"])
+
+# Multimodal classification (text + screenshots)
+result = classifier.classify_by_llm_multimodal(["instagram.com"])
+
+# Custom classification instructions
+result = classifier.classify_by_llm(
+    ["khanacademy.org", "reddit.com"],
+    custom_instructions="Classify by educational value: educational, entertainment, mixed"
+)
+
+# Track usage and costs
+stats = classifier.get_llm_usage_stats()
+print(f"API calls: {stats['total_requests']}, Cost: ${stats['estimated_cost_usd']:.4f}")
+```
+
+**LLM Benefits:**
+- **Custom Categories**: Define your own classification schemes
+- **Multimodal Analysis**: Combines text + visual understanding
+- **Latest AI**: GPT-4o, Claude 3.5 Sonnet, Gemini 1.5 Pro
+- **Cost Tracking**: Built-in usage monitoring and limits
+- **Flexible Prompts**: Customize instructions for specific use cases
+
+**Supported Providers:**
+- **OpenAI**: GPT-4o, GPT-4-turbo, GPT-3.5-turbo
+- **Anthropic**: Claude 3.5 Sonnet, Claude 3 Opus/Haiku
+- **Google**: Gemini 1.5 Pro, Gemini Pro Vision
+- **Others**: Any litellm-supported model
+
+```bash
+# Set API keys via environment variables
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GOOGLE_API_KEY="..."
+```
+
 ## 🏷️ Supported Categories
 
 News, Finance, Shopping, Education, Government, Adult Content, Gambling, Social Networks, Search Engines, and 32 more categories based on the Shallalist taxonomy.

TRUSTED_PUBLISHING_FIX.md

@@ -0,0 +1,111 @@
+# Trusted Publishing Configuration Fix
+
+## Problem Analysis
+
+The error shows:
+- Repository: `themains/know-your-ip`
+- Environment: `MISSING` ← **This is the key issue**
+- Branch: `master`
+- Workflow: `python-publish.yml`
+
+## Required Actions
+
+### 1. Update Workflow File in `themains/know-your-ip`
+
+Replace the `python-publish.yml` file in `themains/know-your-ip` with this exact content:
+
+```yaml
+# Publish to PyPI when a new release is created or manually triggered
+# Uses OpenID Connect trusted publishing for enhanced security
+name: python-publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # Enables manual triggering
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing with OIDC
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi  # ← THIS IS CRITICAL - currently missing!
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      
+      - name: Build package
+        run: uv build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Trusted publishing - no API token needed
+```
+
+### 2. Configure Trusted Publisher on PyPI
+
+Go to your PyPI project (know-your-ip) settings:
+
+1. **Visit**: https://pypi.org/manage/project/know-your-ip/settings/publishing/
+2. **Add trusted publisher** with these **EXACT** values:
+
+   - **Repository owner**: `themains`
+   - **Repository name**: `know-your-ip`
+   - **Workflow filename**: `python-publish.yml`
+   - **Environment name**: `pypi`
+
+### 3. Create PyPI Environment in GitHub
+
+In the `themains/know-your-ip` repository:
+
+1. Go to **Settings** → **Environments**
+2. Click **New environment**
+3. Name it: `pypi`
+4. (Optional) Add protection rules like requiring reviews
+
+### 4. Test the Configuration
+
+1. Create a test release in `themains/know-your-ip`
+2. Check the workflow logs for:
+   ```
+   * `environment`: `pypi`  # Should no longer be MISSING
+   ```
+3. Verify successful publication
+
+## Verification Checklist
+
+- [ ] Workflow file updated with `environment: pypi`
+- [ ] PyPI trusted publisher configured for `themains/know-your-ip`
+- [ ] GitHub environment `pypi` created
+- [ ] Test release triggers workflow successfully
+- [ ] Environment claim appears in logs (not MISSING)
+
+## Security Benefits
+
+✅ **No API tokens to manage**  
+✅ **Automatic token rotation**  
+✅ **Audit trail through OIDC**  
+✅ **Reduced credential exposure**
+
+## Troubleshooting
+
+If you still get errors:
+
+1. **Double-check repository names** (themains/know-your-ip)
+2. **Verify branch name** (master vs main)
+3. **Confirm PyPI project name** matches exactly
+4. **Check environment name** is exactly `pypi`
+
+The key fix is adding `environment: pypi` to the workflow, which will make the environment claim appear in the OIDC token instead of being `MISSING`.

docs/source/conf.py

@@ -58,7 +58,8 @@
     'nltk',
     'scikit-learn',
     'sklearn',
-    'joblib'
+    'joblib',
+    'litellm'
 ]
 
 # Source file configuration

docs/source/piedomains.classifiers.rst

@@ -20,6 +20,14 @@ piedomains.classifiers.image\_classifier module
    :show-inheritance:
    :undoc-members:
 
+piedomains.classifiers.llm\_classifier module
+---------------------------------------------
+
+.. automodule:: piedomains.classifiers.llm_classifier
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 piedomains.classifiers.text\_classifier module
 ----------------------------------------------
 

docs/source/piedomains.llm.rst

@@ -0,0 +1,37 @@
+piedomains.llm package
+======================
+
+Submodules
+----------
+
+piedomains.llm.config module
+----------------------------
+
+.. automodule:: piedomains.llm.config
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+piedomains.llm.prompts module
+-----------------------------
+
+.. automodule:: piedomains.llm.prompts
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+piedomains.llm.response\_parser module
+--------------------------------------
+
+.. automodule:: piedomains.llm.response_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: piedomains.llm
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/source/piedomains.rst

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    piedomains.classifiers
+   piedomains.llm
    piedomains.processors
 
 Submodules

examples/README.md

@@ -2,18 +2,35 @@
 
 This directory contains example scripts demonstrating piedomains functionality:
 
+## Traditional ML Classification
+- `new_api_demo.py`: Modern DomainClassifier API demonstration
 - `archive_demo.py`: Basic archive.org classification demo
 - `archive_functionality_demo.py`: Archive functionality testing
 - `final_archive_demo.py`: Final archive integration test
 - `jupyter_demo.py`: Jupyter notebook demonstration
 
+## LLM-Powered Classification
+- `llm_demo.py`: LLM-based classification with OpenAI, Anthropic, Google models
+
 ## Running Examples
 
 ```bash
 cd examples
-python archive_demo.py
+python new_api_demo.py
+python llm_demo.py  # Requires API key
+```
+
+### LLM Demo Setup
+
+For LLM examples, set your API key:
+```bash
+export OPENAI_API_KEY="sk-..."       # OpenAI
+export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic
+export GOOGLE_API_KEY="..."          # Google
 ```
 
+## Installation
+
 Note: These scripts require the piedomains package to be installed:
 ```bash
 pip install -e ..