Metadata-Version: 2.4
Name: untell-ai
Version: 0.1.0
Summary: untell.ai — reads your unspoken thoughts from digital footprints
Author-email: Junhyuk <xodn348@gmail.com>
License: Business Source License 1.1
        
        Parameters
        
        Licensor:             Junhyuk (xodn348@gmail.com)
        Licensed Work:        untell.ai
                              The Licensed Work is (c) 2026 Junhyuk
        Change Date:          2030-03-16
        Change License:       Apache License, Version 2.0
        
        For information about alternative licensing arrangements for the Licensed Work,
        please contact: xodn348@gmail.com
        
        ---
        
        Business Source License 1.1
        
        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
        "Business Source License" is a trademark of MariaDB Corporation Ab.
        
        Terms
        
        The Licensor hereby grants you the right to copy, modify, create derivative
        works, redistribute, and make non-production use of the Licensed Work. The
        Licensor may make an Additional Use Grant, above, permitting limited production use.
        
        Effective on the Change Date, or the fourth anniversary of the first publicly
        available distribution of a specific version of the Licensed Work under this
        License, whichever comes first, the Licensor hereby grants you rights under
        the terms of the Change License, and the rights granted in the paragraph
        above terminate.
        
        If your use of the Licensed Work does not comply with the requirements
        currently in effect as described in this License, you must purchase a
        commercial license from the Licensor, its affiliated entities, or authorized
        resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works
        of the Licensed Work, are subject to this License. This License applies
        separately for each version of the Licensed Work and the Change Date may vary
        for each version of the Licensed Work released by Licensor.
        
        You must conspicuously display this License on each original or modified copy
        of the Licensed Work. If you receive a copy of the Licensed Work in a different
        license, as may be permitted under the paragraph above, you are still required
        to ensure that you are in compliance with this License.
        
        You may not move the Change Date of the Licensed Work to a later date; no
        amendment to or modification of this License will be valid or have any effect
        if it attempts to do so.
        
        For each covered work, indicate where the source code for the work can be
        found using one of the following places: a downloadable location, a version
        control system, or a combination of the foregoing, listed on a web page that
        is accessible to the public without any need to register for access.
        
        Any attempt otherwise to propagate or modify it is void, and will automatically
        terminate your rights under this License (including any patent licenses granted
        under the third paragraph of section 11 of the GNU General Public License
        version 3 or later).
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click
Requires-Dist: litellm
Requires-Dist: matplotlib
Requires-Dist: orjson
Requires-Dist: plotly
Requires-Dist: pydantic>=2.0
Requires-Dist: requests
Requires-Dist: spotipy
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# untell.ai

> Understands you better than Google does.

untell.ai analyzes your digital footprints to reveal patterns you didn't know you had. Not just what you search — why you search it, what you avoid, and what your behavior says when you're not paying attention.

---

## What You Need

untell.ai uses **two data sources** to build your profile:

### 1. Chrome History (automatic)
Your Chrome browser stores every page visit, search term, and download in a local SQLite database. untell.ai reads it directly — no export needed.

**What it captures:**
- Every URL you visited + how long you stayed
- Every search term you typed in the address bar
- Pages you keep revisiting (obsession signals)
- Downloads (what you wanted to keep)

**Note:** Incognito/private browsing is not recorded by Chrome and cannot be analyzed.

### 2. YouTube Takeout (manual download, 5 min)
Google Takeout lets you export your full YouTube watch history as a JSON file.

**How to get it:**
1. Go to [takeout.google.com](https://takeout.google.com)
2. Click "Deselect all"
3. Scroll down and select only **"YouTube and YouTube Music"**
4. Click the YouTube section → change format from **HTML to JSON**
5. Click "Next step" → "Create export"
6. Wait for email → download the zip → unzip

Your Takeout folder will look like:
```
Takeout/
└── YouTube and YouTube Music/
    └── history/
        ├── watch-history.json    ← this is the key file
        └── search-history.json
```

**What it captures:**
- Every video you've ever watched (title, channel, timestamp)
- Your YouTube search history
- Subscriptions and playlists

---

## How It Works

untell.ai **does not call any LLM API**. It collects and structures your data. The analysis is done by whatever AI agent you're already using (Claude Code, Cursor, ChatGPT, etc.).

```
Step 1: untell collects Chrome + YouTube data
Step 2: Your AI agent reads the structured data
Step 3: AI generates a behavioral profile (facts, patterns, unconscious insights)
Step 4: untell serves the results as a web dashboard on localhost
```

---

## Quick Start

### Install
```bash
pip install untell-ai
```

### Collect Chrome History
```bash
untell collect --source chrome --output events.json
```
This reads all Chrome profiles on your machine. No setup needed.

### Add YouTube Takeout
```bash
untell collect --source youtube \
  --input ~/Downloads/Takeout/YouTube\ and\ YouTube\ Music/history/ \
  --merge events.json
```
Point `--input` to the `history/` folder inside your Takeout download.

### View Results
```bash
untell serve profile.json
```
Opens an interactive 4-tab dashboard on `http://localhost:8765`.

---

## The Dashboard

| Tab | What's Inside |
|-----|---------------|
| **Summary** | Identity layers, interest network graph, timeline, unconscious patterns |
| **Facts** | Who you are, active vs passive gap, hidden contradictions, predictions |
| **Mood** | Portrait, taste, passion, mission, drive |
| **Google vs Me** | How Google/YouTube see you vs who you actually are |

### Analysis Techniques

| Technique | What It Reveals |
|-----------|----------------|
| **Sequence Analysis** | What you do after watching certain content — unconscious emotional patterns |
| **Absence Analysis** | What's missing from your data — things you avoid without realizing |
| **Temporal Patterns** | Time-of-day behavior shifts — different versions of yourself at different hours |
| **Dwell Time** | How long you spend on each page — true interest vs casual browsing |
| **Cross-Source Gaps** | What you search vs what you watch — conscious intent vs unconscious consumption |

---

## Data Sources

| Source | How to Get It | What It Adds |
|--------|--------------|--------------|
| **Chrome History** | Automatic (local SQLite) | Browsing, searches, downloads, dwell time, revisit patterns |
| **YouTube Takeout** | [takeout.google.com](https://takeout.google.com) → JSON format | Full watch history, channels, timestamps |
| **Google Search Takeout** | Same Takeout export | Raw search queries with timestamps |

---

## Privacy

- **100% local.** All data stays on your machine. Nothing is sent anywhere.
- **No LLM API calls.** untell.ai does not call OpenAI, Anthropic, or any external AI service. Your AI agent (Claude Code, Cursor, etc.) does the analysis locally in your session.
- **No external data transmission.** Chrome History is read locally. YouTube Takeout is parsed locally. The dashboard runs on `localhost` — your browser talks to your own machine.
- Chrome History is read with `immutable=1` flag — doesn't lock the database.
- No telemetry, no analytics, no tracking, no cloud uploads. Zero network calls.

---

## License

[Business Source License 1.1](LICENSE) — Free for personal use.  
Commercial use requires a license. Contact: xodn348@gmail.com
