{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "da1ba4ff",
   "metadata": {},
   "source": [
    "# 🚀 filoma demo\n",
    "\n",
    "Fast, multi-backend file analysis with a tiny API surface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c9cfc6f",
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "import filoma\n",
    "\n",
    "print(f\"filoma version: {filoma.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "415fb942",
   "metadata": {},
   "source": [
    "Let's start with something simple, like getting a handy dataclass for a single file:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7bd80bf4",
   "metadata": {},
   "source": [
    "# 🔍📄 File analysis "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d28adfe2",
   "metadata": {},
   "source": [
    "### 📄 Single file (any kind)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71a9cf1f",
   "metadata": {},
   "outputs": [],
   "source": [
    "from filoma import probe_file\n",
    "\n",
    "file_info = probe_file(\"../README.md\")\n",
    "print(f\"Path: {file_info.path}\")\n",
    "print(f\"Size: {file_info.size}\")\n",
    "print(f\"Modified: {file_info.modified}\")\n",
    "print(f\"file_info: {[i for i in dir(file_info) if not i.startswith('_')]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a6b1fb2",
   "metadata": {},
   "source": [
    "or specifically for image files:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10c8f485",
   "metadata": {},
   "source": [
    "### 🖼️ Image file analysis"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c573a319",
   "metadata": {},
   "outputs": [],
   "source": [
    "from filoma import probe_image\n",
    "\n",
    "img = probe_image(\"../images/logo.png\")\n",
    "print(f\"Type of file: {img.file_type}, Type of img object: {type(img)}\")\n",
    "print(f\"Shape: {img.shape}\")\n",
    "print(f\"Data range: {img.min} - {img.max}\")\n",
    "print(f\"img info: {img.as_dict()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc9779c9",
   "metadata": {},
   "source": [
    "# 🔍📁 Directory Analysis"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac938f14",
   "metadata": {},
   "source": [
    "Do you want to analyze a directory of files and extract metadata, text content, and other useful information?   \n",
    "`filoma` makes it super easy to do so with just a few lines of code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0b115872",
   "metadata": {},
   "outputs": [],
   "source": [
    "from filoma.directories import DirectoryProfiler, DirectoryProfilerConfig\n",
    "\n",
    "# Create a profiler using the typed config dataclass\n",
    "config = DirectoryProfilerConfig(use_rust=True)\n",
    "dir_prof = DirectoryProfiler(config)\n",
    "\n",
    "analysis = dir_prof.probe(\"../\")\n",
    "dir_prof.print_summary(analysis)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e86a6d47",
   "metadata": {},
   "source": [
    "Want to quickly see a report of your findings? filoma has you covered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb2f3a50",
   "metadata": {},
   "outputs": [],
   "source": [
    "dir_prof.print_report(analysis)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "448bc8d6",
   "metadata": {},
   "source": [
    "# 📁 Directory of files --> DataFrame --> Data Exploration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "570832a2",
   "metadata": {},
   "source": [
    "Now that you saw what's up with your files, you might want to explore the data in a familiar format.   \n",
    "`filoma` can convert the analysis results into a Polars (or Pandas) DataFrame real quick.  \n",
    "**NOTE**: Pandas support requires the `pd` extra which you can install by running `uv sync --extra pd` in your terminal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9006315c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from filoma import probe_to_df\n",
    "\n",
    "df = probe_to_df(\"../\", max_depth=2, enrich=True)\n",
    "print(f\"Found {len(df)} files\")\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "633af2ef",
   "metadata": {},
   "outputs": [],
   "source": [
    "!uv pip install pandas pyarrow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34b6a71e",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"Type of df:\\t{type(df.to_pandas())}, \\nShape of df:\\t{df.to_pandas().shape}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e28af33",
   "metadata": {},
   "source": [
    "# ⚡ DataFrame enrichment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e12bb3a5",
   "metadata": {},
   "source": [
    "You're probably wondering \"what is `enrich=True`?\"  \n",
    "Well, since `filoma` gathers the paths of your files in a DataFrame, why not enrich this DataFrame with additional metadata. Its own `DataFrame` class has convenience functions like: `add_path_components()`, `add_file_stats_cols()`, `add_depth_col()`  \n",
    "  \n",
    "Let's see it in action:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a611ca15",
   "metadata": {},
   "outputs": [],
   "source": [
    "from rich.console import Console\n",
    "from rich.panel import Panel\n",
    "\n",
    "console = Console()\n",
    "\n",
    "cfg = DirectoryProfilerConfig(build_dataframe=True, use_rust=True, return_absolute_paths=True)\n",
    "dprof = DirectoryProfiler(cfg)\n",
    "res = dprof.probe(\"../\")\n",
    "\n",
    "orig_cols = list(res.dataframe.columns)\n",
    "console.print(Panel(f\"Columns before enrich: [bold]{', '.join(orig_cols)}[/]\"))\n",
    "console.print(Panel(res.dataframe.head(3).to_pandas().to_string(index=False), title=\"DataFrame head (before enrich)\"))\n",
    "\n",
    "df = res.dataframe.enrich()\n",
    "new_cols = sorted(set(df.columns) - set(orig_cols))\n",
    "console.print(Panel(f\"New columns after enrich: [bold]{', '.join(new_cols)}[/]\"))\n",
    "console.print(Panel(df.head(3).to_pandas().to_string(index=False), title=\"DataFrame head (after enrich)\"))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96178b12",
   "metadata": {
    "vscode": {
     "languageId": "markdown"
    }
   },
   "source": [
    "## ✅ Conclusion\n",
    "\n",
    "So this is how you can use `filoma` to go from a messy directory tree to a clean DataFrame with enriched metadata, ready for analysis and downstream workflows."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "filoma (3.11.11)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
