sortai 0.1.0__tar.gz

sortai-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: sortai
+Version: 0.1.0
+Summary: LLM-powered directory organizer using Google Gemini
+Author: sortai
+License: MIT
+Keywords: cli,organize,files,gemini,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: google-generativeai>=0.3.0
+Requires-Dist: pdfplumber>=0.10.0
+Requires-Dist: python-docx>=1.0
+
+# sortai
+
+LLM-powered directory organizer. Uses **Google Gemini** to suggest a folder structure from filenames and (for text-based files) the first ~500 characters of content, then moves files into the suggested subfolders.
+
+- **Dry-run by default** – see exactly what would move where before touching anything.
+- **Confirm before apply** – with `--apply`, you are prompted to confirm before any files are moved.
+
+## Install
+
+```bash
+pip install sortai
+```
+
+Development install from source:
+
+```bash
+git clone <repo>
+cd sortai
+pip install -e .
+```
+
+## Setup
+
+Set your Google Gemini API key (required):
+
+```bash
+export GEMINI_API_KEY=your_key_here
+```
+
+Get a key at: **https://aistudio.google.com/app/apikey**
+
+You can copy `.env.example` to `.env` and set `GEMINI_API_KEY` there; load it with your shell or a tool like `python-dotenv` if you use one (sortai does not load `.env` automatically).
+
+## Demo
+
+<!-- TODO: add demo GIF -->
+![Demo](docs/demo.gif)
+
+*(Placeholder: add a short GIF showing `sortai ./folder`, dry-run output, then `--apply` and confirmation.)*
+
+## Usage
+
+| Command | Description |
+|--------|-------------|
+| `sortai <path>` | Dry-run: show what would be moved where (default). |
+| `sortai <path> --apply` | After dry-run, prompt and then actually move files. |
+| `sortai <path> --depth 2` | Organize up to 2 levels of subfolders (e.g. `documents/work`). |
+| `sortai <path> --model gemini-1.5-flash` | Override Gemini model (default: gemini-1.5-flash). |
+| `sortai --version` | Print version. |
+| `sortai --help` | Show help. |
+
+### Example output
+
+**Before (flat directory):**
+
+```
+my-folder/
+├── report.pdf
+├── notes.txt
+├── budget.csv
+├── vacation.jpg
+└── readme.md
+```
+
+**Dry-run:**
+
+```
+$ sortai ./my-folder
+Dry run – would move:
+  report.pdf  ->  documents/
+  notes.txt   ->  documents/
+  budget.csv  ->  finance/
+  vacation.jpg ->  images/
+  readme.md   ->  (keep at root)
+Run with --apply to perform moves.
+```
+
+**After applying:**
+
+```
+my-folder/
+├── readme.md
+├── documents/
+│   ├── report.pdf
+│   └── notes.txt
+├── finance/
+│   └── budget.csv
+└── images/
+    └── vacation.jpg
+```
+
+## Supported file types for content reading
+
+sortai reads the **first ~500 characters** of content for:
+
+- `.pdf` (first page via pdfplumber)
+- `.txt`, `.md`, `.csv` (plain text)
+- `.docx` (paragraph text via python-docx)
+
+All other files are categorized by **filename and extension only**.
+
+## Publishing to PyPI
+
+1. **Create a PyPI account** (and optionally [Test PyPI](https://test.pypi.org/) for testing):
+   - https://pypi.org/account/register/
+
+2. **Install build tools** (one-time):
+   ```bash
+   pip install build twine
+   ```
+
+3. **Bump version** in `pyproject.toml` and `sortai/__init__.py` when releasing a new version.
+
+4. **Build the package** (from the project root):
+   ```bash
+   python -m build
+   ```
+   This creates `dist/sortai-0.1.0.tar.gz` and a wheel.
+
+5. **Upload to PyPI**:
+   ```bash
+   twine upload dist/*
+   ```
+   Twine will prompt for your PyPI username and password. Prefer an [API token](https://pypi.org/manage/account/token/) (username: `__token__`, password: your token) over your account password.
+
+   To try Test PyPI first:
+   ```bash
+   twine upload --repository testpypi dist/*
+   ```
+   Then install with: `pip install -i https://test.pypi.org/simple/ sortai`
+
+**Note:** If the name `sortai` is already taken on PyPI, change the `name` in `pyproject.toml` to something unique (e.g. `sortai-cli`) and publish under that name.
+
+## License
+
+MIT

sortai-0.1.0/README.md

@@ -0,0 +1,136 @@
+# sortai
+
+LLM-powered directory organizer. Uses **Google Gemini** to suggest a folder structure from filenames and (for text-based files) the first ~500 characters of content, then moves files into the suggested subfolders.
+
+- **Dry-run by default** – see exactly what would move where before touching anything.
+- **Confirm before apply** – with `--apply`, you are prompted to confirm before any files are moved.
+
+## Install
+
+```bash
+pip install sortai
+```
+
+Development install from source:
+
+```bash
+git clone <repo>
+cd sortai
+pip install -e .
+```
+
+## Setup
+
+Set your Google Gemini API key (required):
+
+```bash
+export GEMINI_API_KEY=your_key_here
+```
+
+Get a key at: **https://aistudio.google.com/app/apikey**
+
+You can copy `.env.example` to `.env` and set `GEMINI_API_KEY` there; load it with your shell or a tool like `python-dotenv` if you use one (sortai does not load `.env` automatically).
+
+## Demo
+
+<!-- TODO: add demo GIF -->
+![Demo](docs/demo.gif)
+
+*(Placeholder: add a short GIF showing `sortai ./folder`, dry-run output, then `--apply` and confirmation.)*
+
+## Usage
+
+| Command | Description |
+|--------|-------------|
+| `sortai <path>` | Dry-run: show what would be moved where (default). |
+| `sortai <path> --apply` | After dry-run, prompt and then actually move files. |
+| `sortai <path> --depth 2` | Organize up to 2 levels of subfolders (e.g. `documents/work`). |
+| `sortai <path> --model gemini-1.5-flash` | Override Gemini model (default: gemini-1.5-flash). |
+| `sortai --version` | Print version. |
+| `sortai --help` | Show help. |
+
+### Example output
+
+**Before (flat directory):**
+
+```
+my-folder/
+├── report.pdf
+├── notes.txt
+├── budget.csv
+├── vacation.jpg
+└── readme.md
+```
+
+**Dry-run:**
+
+```
+$ sortai ./my-folder
+Dry run – would move:
+  report.pdf  ->  documents/
+  notes.txt   ->  documents/
+  budget.csv  ->  finance/
+  vacation.jpg ->  images/
+  readme.md   ->  (keep at root)
+Run with --apply to perform moves.
+```
+
+**After applying:**
+
+```
+my-folder/
+├── readme.md
+├── documents/
+│   ├── report.pdf
+│   └── notes.txt
+├── finance/
+│   └── budget.csv
+└── images/
+    └── vacation.jpg
+```
+
+## Supported file types for content reading
+
+sortai reads the **first ~500 characters** of content for:
+
+- `.pdf` (first page via pdfplumber)
+- `.txt`, `.md`, `.csv` (plain text)
+- `.docx` (paragraph text via python-docx)
+
+All other files are categorized by **filename and extension only**.
+
+## Publishing to PyPI
+
+1. **Create a PyPI account** (and optionally [Test PyPI](https://test.pypi.org/) for testing):
+   - https://pypi.org/account/register/
+
+2. **Install build tools** (one-time):
+   ```bash
+   pip install build twine
+   ```
+
+3. **Bump version** in `pyproject.toml` and `sortai/__init__.py` when releasing a new version.
+
+4. **Build the package** (from the project root):
+   ```bash
+   python -m build
+   ```
+   This creates `dist/sortai-0.1.0.tar.gz` and a wheel.
+
+5. **Upload to PyPI**:
+   ```bash
+   twine upload dist/*
+   ```
+   Twine will prompt for your PyPI username and password. Prefer an [API token](https://pypi.org/manage/account/token/) (username: `__token__`, password: your token) over your account password.
+
+   To try Test PyPI first:
+   ```bash
+   twine upload --repository testpypi dist/*
+   ```
+   Then install with: `pip install -i https://test.pypi.org/simple/ sortai`
+
+**Note:** If the name `sortai` is already taken on PyPI, change the `name` in `pyproject.toml` to something unique (e.g. `sortai-cli`) and publish under that name.
+
+## License
+
+MIT

sortai-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sortai"
+version = "0.1.0"
+description = "LLM-powered directory organizer using Google Gemini"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "sortai" }]
+keywords = ["cli", "organize", "files", "gemini", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.0",
+    "google-generativeai>=0.3.0",
+    "pdfplumber>=0.10.0",
+    "python-docx>=1.0",
+]
+
+[project.scripts]
+sortai = "sortai.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sortai*"]

sortai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sortai-0.1.0/sortai/__init__.py

@@ -0,0 +1,3 @@
+"""sortai – LLM-powered directory organizer using Google Gemini."""
+
+__version__ = "0.1.0"

sortai-0.1.0/sortai/ai.py

@@ -0,0 +1,105 @@
+"""Gemini API client: build prompt from file list, call model, parse JSON moves."""
+
+import json
+import os
+import re
+from typing import Any
+
+GEMINI_API_KEY_URL = "https://aistudio.google.com/app/apikey"
+
+
+class MissingApiKeyError(Exception):
+    """Raised when GEMINI_API_KEY is not set."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "GEMINI_API_KEY is not set. Get an API key at " + GEMINI_API_KEY_URL
+        )
+
+
+def get_moves(
+    file_list: list[dict],
+    depth: int,
+    model_name: str = "gemini-1.5-flash",
+) -> list[tuple[str, str]]:
+    """
+    Call Gemini to suggest folder structure. Returns list of (relative_path, target_folder).
+    target_folder may be "." for root or e.g. "documents" or "documents/work" when depth > 1.
+    Raises MissingApiKeyError if GEMINI_API_KEY is not set.
+    """
+    api_key = os.environ.get("GEMINI_API_KEY")
+    if not api_key or not api_key.strip():
+        raise MissingApiKeyError()
+
+    import google.generativeai as genai
+    genai.configure(api_key=api_key.strip())
+    model = genai.GenerativeModel(model_name)
+
+    prompt = _build_prompt(file_list, depth)
+    response = model.generate_content(prompt)
+    text = (response.text or "").strip()
+    return _parse_moves(text, file_list)
+
+
+def _build_prompt(file_list: list[dict], depth: int) -> str:
+    """Build the prompt for Gemini with file list and depth rules."""
+    lines = [
+        "You are organizing files in a directory. Given the list of files below (with optional content previews), suggest a folder structure.",
+        "",
+        "Rules:",
+        "- Use only the relative paths exactly as given in the file list.",
+        f"- Maximum folder depth is {depth}. So target_folder must be at most {depth} path segments (e.g. for depth 1 use a single folder name like 'documents'; for depth 2 you can use 'documents/work').",
+        "- Use forward slashes in target_folder (e.g. 'documents/work').",
+        "- To leave a file at the root, use target_folder: '.'.",
+        "- Do not suggest moving outside the given directory or using absolute paths.",
+        "- Output ONLY a single JSON object, no other text. Format:",
+        '{"moves": [{"path": "filename.txt", "target_folder": "documents"}, ...]}',
+        "",
+        "File list:",
+    ]
+    for item in file_list:
+        path = item.get("path", "")
+        preview = item.get("content_preview")
+        if preview:
+            lines.append(f"- {path}")
+            lines.append(f"  content_preview: {preview!r}")
+        else:
+            lines.append(f"- {path} (filename/extension only)")
+    return "\n".join(lines)
+
+
+def _parse_moves(response_text: str, file_list: list[dict]) -> list[tuple[str, str]]:
+    """Extract JSON from response, validate paths against file_list, return list of (path, target_folder)."""
+    valid_paths = {item["path"] for item in file_list}
+
+    # Strip markdown code fences if present
+    text = response_text.strip()
+    match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", text)
+    if match:
+        text = match.group(1).strip()
+    # Try raw parse in case there's no fence
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return []
+
+    moves_raw = data.get("moves")
+    if not isinstance(moves_raw, list):
+        return []
+
+    result = []
+    for entry in moves_raw:
+        if not isinstance(entry, dict):
+            continue
+        path = entry.get("path")
+        target = entry.get("target_folder")
+        if path is None or target is None:
+            continue
+        path = str(path).strip()
+        target = str(target).strip().replace("\\", "/")
+        if path not in valid_paths:
+            continue
+        if not target:
+            target = "."
+        result.append((path, target))
+    return result

sortai-0.1.0/sortai/cli.py

@@ -0,0 +1,105 @@
+"""Click CLI entrypoint for sortai."""
+
+import os
+from pathlib import Path
+
+import click
+
+from sortai import __version__
+from sortai.ai import GEMINI_API_KEY_URL, MissingApiKeyError, get_moves
+from sortai.organizer import apply_moves, confirm, dry_run
+from sortai.reader import list_files
+
+
+@click.command()
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    required=False,
+    default=None,
+)
+@click.option(
+    "--apply",
+    is_flag=True,
+    default=False,
+    help="Actually move files after confirmation (default: dry-run only).",
+)
+@click.option(
+    "--depth",
+    type=int,
+    default=1,
+    help="Organize recursively up to N levels of subfolders (default: 1).",
+)
+@click.option(
+    "--model",
+    type=str,
+    default="gemini-1.5-flash",
+    help="Gemini model name (default: gemini-1.5-flash).",
+)
+@click.option(
+    "--version",
+    "show_version",
+    is_flag=True,
+    default=False,
+    help="Show version and exit.",
+)
+def main(
+    path: Path | None,
+    apply: bool,
+    depth: int,
+    model: str,
+    show_version: bool,
+) -> None:
+    """Organize files in a directory using Google Gemini."""
+    if show_version:
+        click.echo(f"sortai {__version__}")
+        raise SystemExit(0)
+
+    if path is None:
+        click.echo("Error: PATH is required. Use --help for usage.", err=True)
+        raise SystemExit(1)
+
+    root = path.resolve()
+    if not root.is_dir():
+        click.echo(f"Error: not a directory: {path}", err=True)
+        raise SystemExit(1)
+
+    if not (os.environ.get("GEMINI_API_KEY") or "").strip():
+        click.echo("Error: GEMINI_API_KEY is not set.", err=True)
+        click.echo(f"Get an API key at: {GEMINI_API_KEY_URL}", err=True)
+        raise SystemExit(1)
+
+    file_list = list_files(root, max_depth=depth)
+    if not file_list:
+        click.echo("No files found to organize.")
+        raise SystemExit(0)
+
+    try:
+        moves = get_moves(file_list, depth=depth, model_name=model)
+    except MissingApiKeyError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo(f"Get an API key at: {GEMINI_API_KEY_URL}", err=True)
+        raise SystemExit(1)
+    except Exception as e:
+        click.echo(f"Error calling Gemini: {e}", err=True)
+        raise SystemExit(1)
+
+    if not moves:
+        click.echo("No moves suggested.")
+        raise SystemExit(0)
+
+    dry_run(root, moves, echo=click.echo)
+    if not apply:
+        click.echo("Run with --apply to perform moves.")
+        raise SystemExit(0)
+
+    if not confirm(echo=click.echo):
+        click.echo("Aborted.")
+        raise SystemExit(0)
+
+    apply_moves(root, moves, echo=click.echo)
+    click.echo("Done.")
+
+
+if __name__ == "__main__":
+    main()

sortai-0.1.0/sortai/organizer.py

@@ -0,0 +1,53 @@
+"""Dry-run display, confirmation prompt, and file move execution."""
+
+import os
+import shutil
+from pathlib import Path
+from typing import Callable
+
+
+def dry_run(root: Path, moves: list[tuple[str, str]], echo: Callable[[str], None]) -> None:
+    """Print what would be moved where. No filesystem changes."""
+    root = root.resolve()
+    echo("Dry run – would move:")
+    for rel_path, target_folder in moves:
+        if target_folder == ".":
+            dest_desc = "(keep at root)"
+        else:
+            dest_desc = f"{target_folder}/"
+        echo(f"  {rel_path}  ->  {dest_desc}")
+
+
+def confirm(echo: Callable[[str], None]) -> bool:
+    """Prompt 'Apply these moves? [y/N]'. Returns True for y/yes, False otherwise."""
+    try:
+        answer = input("Apply these moves? [y/N] ").strip().lower()
+    except EOFError:
+        return False
+    return answer in ("y", "yes")
+
+
+def apply_moves(root: Path, moves: list[tuple[str, str]], echo: Callable[[str], None]) -> None:
+    """
+    Create target dirs and move files. Skips and warns if destination file already exists
+    (no overwrite without user consent).
+    """
+    root = root.resolve()
+    for rel_path, target_folder in moves:
+        src = root / rel_path.replace("/", os.sep)
+        if not src.is_file():
+            echo(f"  Skip (not a file): {rel_path}")
+            continue
+        if target_folder == ".":
+            continue
+        target_dir = root / target_folder.replace("/", os.sep)
+        target_dir.mkdir(parents=True, exist_ok=True)
+        dest = target_dir / src.name
+        if dest.exists() and dest.resolve() != src.resolve():
+            echo(f"  Skip (destination exists): {rel_path} -> {dest.relative_to(root)}")
+            continue
+        try:
+            shutil.move(str(src), str(dest))
+            echo(f"  Moved: {rel_path} -> {target_folder}/")
+        except OSError as e:
+            echo(f"  Error moving {rel_path}: {e}")

sortai-0.1.0/sortai/reader.py

@@ -0,0 +1,101 @@
+"""File listing and content extraction (first ~500 chars) for text-based types."""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+CONTENT_PREVIEW_LENGTH = 500
+
+# Extensions for which we read file content; everything else is categorized by filename/extension only.
+CONTENT_EXTENSIONS = {".pdf", ".txt", ".md", ".docx", ".csv"}
+
+
+def _read_text_preview(path: Path, limit: int = CONTENT_PREVIEW_LENGTH) -> Optional[str]:
+    """Read first `limit` characters from a text file. Returns None on error."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return (f.read(limit + 1))[:limit] or None
+    except OSError:
+        return None
+
+
+def _read_pdf_preview(path: Path, limit: int = CONTENT_PREVIEW_LENGTH) -> Optional[str]:
+    """Extract text from first page of PDF and truncate. Returns None on error."""
+    try:
+        import pdfplumber
+        with pdfplumber.open(path) as pdf:
+            if not pdf.pages:
+                return None
+            text = pdf.pages[0].extract_text()
+            if not text:
+                return None
+            return (text[: limit + 1])[:limit]
+    except Exception:
+        return None
+
+
+def _read_docx_preview(path: Path, limit: int = CONTENT_PREVIEW_LENGTH) -> Optional[str]:
+    """Extract paragraph text from docx and truncate. Returns None on error."""
+    try:
+        from docx import Document
+        doc = Document(path)
+        parts = []
+        n = 0
+        for para in doc.paragraphs:
+            if para.text:
+                parts.append(para.text)
+                n += len(para.text)
+                if n >= limit:
+                    break
+        text = " ".join(parts)
+        return (text[: limit + 1])[:limit] if text else None
+    except Exception:
+        return None
+
+
+def get_content_preview(path: Path, limit: int = CONTENT_PREVIEW_LENGTH) -> Optional[str]:
+    """Return first ~limit characters of file content for supported types, else None."""
+    ext = path.suffix.lower()
+    if ext in (".txt", ".md", ".csv"):
+        return _read_text_preview(path, limit)
+    if ext == ".pdf":
+        return _read_pdf_preview(path, limit)
+    if ext == ".docx":
+        return _read_docx_preview(path, limit)
+    return None
+
+
+def list_files(
+    root: Path,
+    max_depth: Optional[int] = None,
+) -> list[dict]:
+    """
+    Walk directory up to max_depth levels; return list of dicts with path (relative),
+    name (filename), and content_preview (first ~500 chars for supported types, else None).
+    """
+    root = root.resolve()
+    if not root.is_dir():
+        return []
+
+    result = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirpath = Path(dirpath)
+        depth = len(dirpath.relative_to(root).parts) if dirpath != root else 0
+        if max_depth is not None and depth > max_depth:
+            continue
+        if max_depth is not None and depth >= max_depth:
+            dirnames[:] = []  # do not descend further
+        for name in filenames:
+            full_path = dirpath / name
+            try:
+                rel = full_path.relative_to(root)
+            except ValueError:
+                continue
+            rel_str = str(rel).replace("\\", "/")
+            content = get_content_preview(full_path) if full_path.suffix.lower() in CONTENT_EXTENSIONS else None
+            result.append({
+                "path": rel_str,
+                "name": name,
+                "content_preview": content,
+            })
+    return result

sortai-0.1.0/sortai.egg-info/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: sortai
+Version: 0.1.0
+Summary: LLM-powered directory organizer using Google Gemini
+Author: sortai
+License: MIT
+Keywords: cli,organize,files,gemini,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: google-generativeai>=0.3.0
+Requires-Dist: pdfplumber>=0.10.0
+Requires-Dist: python-docx>=1.0
+
+# sortai
+
+LLM-powered directory organizer. Uses **Google Gemini** to suggest a folder structure from filenames and (for text-based files) the first ~500 characters of content, then moves files into the suggested subfolders.
+
+- **Dry-run by default** – see exactly what would move where before touching anything.
+- **Confirm before apply** – with `--apply`, you are prompted to confirm before any files are moved.
+
+## Install
+
+```bash
+pip install sortai
+```
+
+Development install from source:
+
+```bash
+git clone <repo>
+cd sortai
+pip install -e .
+```
+
+## Setup
+
+Set your Google Gemini API key (required):
+
+```bash
+export GEMINI_API_KEY=your_key_here
+```
+
+Get a key at: **https://aistudio.google.com/app/apikey**
+
+You can copy `.env.example` to `.env` and set `GEMINI_API_KEY` there; load it with your shell or a tool like `python-dotenv` if you use one (sortai does not load `.env` automatically).
+
+## Demo
+
+<!-- TODO: add demo GIF -->
+![Demo](docs/demo.gif)
+
+*(Placeholder: add a short GIF showing `sortai ./folder`, dry-run output, then `--apply` and confirmation.)*
+
+## Usage
+
+| Command | Description |
+|--------|-------------|
+| `sortai <path>` | Dry-run: show what would be moved where (default). |
+| `sortai <path> --apply` | After dry-run, prompt and then actually move files. |
+| `sortai <path> --depth 2` | Organize up to 2 levels of subfolders (e.g. `documents/work`). |
+| `sortai <path> --model gemini-1.5-flash` | Override Gemini model (default: gemini-1.5-flash). |
+| `sortai --version` | Print version. |
+| `sortai --help` | Show help. |
+
+### Example output
+
+**Before (flat directory):**
+
+```
+my-folder/
+├── report.pdf
+├── notes.txt
+├── budget.csv
+├── vacation.jpg
+└── readme.md
+```
+
+**Dry-run:**
+
+```
+$ sortai ./my-folder
+Dry run – would move:
+  report.pdf  ->  documents/
+  notes.txt   ->  documents/
+  budget.csv  ->  finance/
+  vacation.jpg ->  images/
+  readme.md   ->  (keep at root)
+Run with --apply to perform moves.
+```
+
+**After applying:**
+
+```
+my-folder/
+├── readme.md
+├── documents/
+│   ├── report.pdf
+│   └── notes.txt
+├── finance/
+│   └── budget.csv
+└── images/
+    └── vacation.jpg
+```
+
+## Supported file types for content reading
+
+sortai reads the **first ~500 characters** of content for:
+
+- `.pdf` (first page via pdfplumber)
+- `.txt`, `.md`, `.csv` (plain text)
+- `.docx` (paragraph text via python-docx)
+
+All other files are categorized by **filename and extension only**.
+
+## Publishing to PyPI
+
+1. **Create a PyPI account** (and optionally [Test PyPI](https://test.pypi.org/) for testing):
+   - https://pypi.org/account/register/
+
+2. **Install build tools** (one-time):
+   ```bash
+   pip install build twine
+   ```
+
+3. **Bump version** in `pyproject.toml` and `sortai/__init__.py` when releasing a new version.
+
+4. **Build the package** (from the project root):
+   ```bash
+   python -m build
+   ```
+   This creates `dist/sortai-0.1.0.tar.gz` and a wheel.
+
+5. **Upload to PyPI**:
+   ```bash
+   twine upload dist/*
+   ```
+   Twine will prompt for your PyPI username and password. Prefer an [API token](https://pypi.org/manage/account/token/) (username: `__token__`, password: your token) over your account password.
+
+   To try Test PyPI first:
+   ```bash
+   twine upload --repository testpypi dist/*
+   ```
+   Then install with: `pip install -i https://test.pypi.org/simple/ sortai`
+
+**Note:** If the name `sortai` is already taken on PyPI, change the `name` in `pyproject.toml` to something unique (e.g. `sortai-cli`) and publish under that name.
+
+## License
+
+MIT

sortai-0.1.0/sortai.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+sortai/__init__.py
+sortai/ai.py
+sortai/cli.py
+sortai/organizer.py
+sortai/reader.py
+sortai.egg-info/PKG-INFO
+sortai.egg-info/SOURCES.txt
+sortai.egg-info/dependency_links.txt
+sortai.egg-info/entry_points.txt
+sortai.egg-info/requires.txt
+sortai.egg-info/top_level.txt

sortai-0.1.0/sortai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sortai-0.1.0/sortai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sortai = sortai.cli:main

sortai-0.1.0/sortai.egg-info/requires.txt

@@ -0,0 +1,4 @@
+click>=8.0
+google-generativeai>=0.3.0
+pdfplumber>=0.10.0
+python-docx>=1.0

sortai-0.1.0/sortai.egg-info/top_level.txt

@@ -0,0 +1 @@
+sortai