Metadata-Version: 2.4
Name: dbt-autodoc
Version: 1.0.10
Summary: Automated documentation generator for dbt projects using Google Gemini AI
Author-email: JustDataPlease <hey@justdataplease.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=0.9.0
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: ruamel.yaml>=0.17.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: dbt-osmosis
Requires-Dist: dbt-duckdb
Requires-Dist: psycopg2-binary
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# DBT Autodoc Documentation

`dbt-autodoc` is the ultimate tool for **Automated Documentation** and **Logging** for your dbt projects. It combines the power of Google Gemini AI with a robust **Database Logging** system to ensure your documentation is always up-to-date, accurate, and auditable.

## 🌟 Why dbt-autodoc?

-   **🤖 Automatic AI Documentation:** Generate comprehensive descriptions for your tables and columns automatically.
-   **💾 Database Logging & History:** Every description is stored in a database (`duckdb` or `postgres`). This acts as a "Source of Truth" and provides a full history of changes.
-   **🔄 Full Synchronization:** Seamlessly integrates with `dbt-osmosis` to keep your YAML files in sync with your SQL models.
-   **🔒 Protect Manual Work:** Respects human-written documentation. If you write it, we lock it.
-   **👥 Team Ready:** Use Postgres to share documentation cache across your entire team.

## 🛠️ Setup

1.  **Install:**
    ```bash
    pip install dbt-autodoc
    ```

2.  **Configuration:**
    Run `dbt-autodoc` to generate `dbt-autodoc.yml`.
    **Important:** Edit `company_context` in this file to give the AI knowledge about your business logic.

3.  **Environment Variables:**
    ```env
    GEMINI_API_KEY=your_api_key_here
    POSTGRES_URL=postgresql://user:pass@host:port/db (optional)
    ```

## 🚀 Quick Start

The easiest way to document your entire project in one go:

### 1. Automatic Mode (Recommended)
Generates table descriptions, syncs columns, and generates column descriptions using AI.
```bash
dbt-autodoc --generate-docs-ai
```

### 2. Manual Mode (No AI)
Syncs your project structure and restores descriptions from the database cache without calling AI.
```bash
dbt-autodoc --generate-docs
```

## 📋 Detailed Workflow

If you prefer granular control, you can run steps individually:

1.  **Generate Table Descriptions:**
    ```bash
    dbt-autodoc --generate-docs-config-ai
    ```

2.  **Generate Column Descriptions:**
    ```bash
    dbt-autodoc --generate-docs-yml-ai
    ```

3.  **Sync Structure Only (No AI):**
    ```bash
    dbt-autodoc --generate-docs-yml
    ```

## 📖 Arguments Reference

| Argument | Description |
| :--- | :--- |
| `--generate-docs-ai` | **🔥 Full Auto.** Runs the complete workflow: SQL generation, Osmosis sync, and YAML generation using AI. |
| `--generate-docs` | **🔄 Full Sync.** Runs the complete workflow using only the database cache (no AI). |
| `--model-path` | Restrict processing to a specific directory (e.g. `models/staging`). |
| `--generate-docs-config-ai` | Generate table descriptions in `.sql` files using AI. |
| `--generate-docs-yml-ai` | Generate column descriptions in `.yml` files using AI. |
| `--generate-docs-config` | Sync `.sql` files from cache (no AI). |
| `--generate-docs-yml` | Sync `.yml` files from cache (no AI). |
| `--cleanup-db` | **Reset Database.** Wipes the description cache and history. |
| `--concurrency` | Max threads for AI/DB requests (default: 10). |

## 🧠 Smart Caching System

`dbt-autodoc` isn't just a wrapper for GPT. It maintains a sophisticated state:

1.  **`doc_cache` Table:** Stores the current active description.
2.  **`doc_cache_log` Table:** logs every single change to a description, by whom, and when.

This means if you accidentally delete a description from your code, `dbt-autodoc --generate-docs` will restore it instantly from the database history!

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Attribution

Brought to you by [JustDataPlease](https://justdataplease.com/agency/).
