Metadata-Version: 2.4
Name: yous
Version: 0.1.0
Summary: You(s) – a personal wiki-first AI agent
Project-URL: Homepage, https://github.com/yous-ai/yous
Project-URL: Repository, https://github.com/yous-ai/yous
Project-URL: Bug Tracker, https://github.com/yous-ai/yous/issues
License: MIT
Keywords: agent,ai,assistant,personal,wiki
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: google-api-python-client>=2.179.0
Requires-Dist: google-auth>=2.40.0
Requires-Dist: openai>=1.0.0
Requires-Dist: prompt-toolkit>=3.0.47
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-docx>=1.1.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Provides-Extra: chroma
Requires-Dist: chromadb>=0.5.0; extra == 'chroma'
Requires-Dist: sentence-transformers>=3.0.0; extra == 'chroma'
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Provides-Extra: devops
Requires-Dist: docker>=7.1.0; extra == 'devops'
Requires-Dist: paramiko>=3.4.0; extra == 'devops'
Requires-Dist: pygithub>=2.3.0; extra == 'devops'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == 'excel'
Requires-Dist: xlrd>=2.0.1; extra == 'excel'
Provides-Extra: google
Requires-Dist: google-api-python-client>=2.179.0; extra == 'google'
Requires-Dist: google-auth-oauthlib>=1.2.0; extra == 'google'
Requires-Dist: google-auth>=2.40.0; extra == 'google'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: research
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'research'
Requires-Dist: httpx>=0.27.0; extra == 'research'
Requires-Dist: praw>=7.7.0; extra == 'research'
Requires-Dist: pygithub>=2.3.0; extra == 'research'
Requires-Dist: readability-lxml>=0.8.1; extra == 'research'
Requires-Dist: tavily-python>=0.5.0; extra == 'research'
Requires-Dist: tweepy>=4.14.0; extra == 'research'
Provides-Extra: server-client
Requires-Dist: cryptography>=41; extra == 'server-client'
Requires-Dist: httpx>=0.27.0; extra == 'server-client'
Provides-Extra: sheets
Requires-Dist: google-api-python-client>=2.179.0; extra == 'sheets'
Requires-Dist: google-auth-oauthlib>=1.2.0; extra == 'sheets'
Requires-Dist: openpyxl>=3.1.0; extra == 'sheets'
Provides-Extra: trading
Requires-Dist: futu-api>=9.0.0; extra == 'trading'
Provides-Extra: travel
Requires-Dist: amadeus>=9.0.0; extra == 'travel'
Requires-Dist: httpx>=0.27.0; extra == 'travel'
Description-Content-Type: text/markdown

# You(s)

> A personal CLI agent that learns who you are — and gets smarter every day.

You(s) is a wiki-first AI agent that lives in your terminal. It reads your Obsidian vault before it does anything else, learns your writing style, your code preferences, your active projects, and your thinking patterns — and uses that context to produce work that actually sounds like you.

Unlike a generic chatbot, You(s) knows your vault. It never re-derives what it already knows, never silently overwrites your files, and never makes a move without your approval.

---

## What You(s) Can Do

You talk to it in plain English. It figures out what to do.

```
"search my wiki for LoRA"
"write a 3-page project proposal for my agent"
"debug this error in main.py"
"break down my goal of building the ingest pipeline into tasks"
"what do people on Reddit say about ChromaDB vs Pinecone?"
"deploy my project to the VPS"
"buy 100 TSLA paper"
"find flights from KL to London in mid-June, 2 pax"
"what's the regime on BTC right now?"
"put this data in a Google Sheet"
```

No commands to memorise for getting work done. If the intent is ambiguous, You(s) asks exactly one clarifying question — with multiple-choice options — before doing anything.

---

## Feature Overview

### Wiki — The Core
You(s) treats your Obsidian vault as its primary brain. Every response draws from your wiki before falling back to model reasoning or the internet.

- Semantic search via ChromaDB
- Read, create, and update wiki pages with diff preview and approval gate
- 4-stage ingest pipeline for PDFs and raw sources
- Skill page auto-creation after hard problems (so solutions are never re-derived)
- Persistent vault map — You(s) never loses track of file locations between sessions

### Coding
- Generate, refactor, and debug code in your preferred language and style
- Style and library preferences extracted from your wiki automatically
- Critique gate reviews output before delivery

### Writing
- Produce Word documents (`.docx`) or Google Docs from natural language
- Tone and structure pulled from your wiki preferences
- Draft → outline approval → full document → critique → export

### Planning
- Break any high-level goal into concrete, prioritised tasks
- Context-aware: reads your `hot.md` and active projects first
- Plans saved to `/wiki/plans/` and updatable with natural language mid-session

### Research
- Web search, official docs, GitHub issues, Reddit discussions
- Results synthesised into a coherent answer
- Prompted to save findings back into your wiki

### Trading Mode *(paper only in v1.1)*
Auto-detected from intent — no command needed.

- Regime detection, watchlist scans, trade-check against risk rules
- Journal: log entries, close trades, view P&L, run backtests
- Paper execution via MooMoo (Futu OpenD required)
- Risk rules enforced: 2% max risk, 2:1 min R:R, 2 max open positions
- Live trading locked behind a config flag; every live order requires Telegram confirmation before it executes

### Google Drive, Sheets, and Excel
- Create, read, and edit Google Sheets or local `.xlsx` files
- Read and write files inside your Google Drive workspace
- Single OAuth grant covers Drive, Sheets, and Docs
- Default scope: `/My Drive/You(s) Workspace/` — full Drive access is opt-in

### Trip Planning
Auto-detected from intent — no command needed.

- Flight search via Amadeus; results link to Trip.com, Google Flights, and Skyscanner
- Hotel comparison across Booking.com, Agoda, and Trip.com
- Day-by-day itinerary generation with POIs and weather context
- Booking tracking saved to your vault
- Google Sheets or Google Docs export on request
- VPS trip reminders: 48h, 24h, and day-of alerts via Telegram (if VPS is configured)

### DevOps
- VPS deployment via SSH, Dockerfile generation, Docker build and run
- GitHub Actions and GitLab CI config generation
- CI/CD pipeline status via GitHub API

### Frontend
- React, Vue, or framework of your preference (read from wiki)
- Figma MCP integration for visual output alongside code (optional, connect via `/mcps`)

### Observability
- Full activity log at `~/.yous/logs/YYYY-MM-DD.log`
- Token usage and API cost breakdown per session
- Alerts for errors and high token usage

---

## Vault Safety

You(s) never silently writes to your vault. Every file write goes through a guarded pipeline:

1. **Vault map lookup** — path is always resolved from the persistent `~/.yous/vault_map.json`, never re-derived
2. **Name collision check** — if a file with that name exists elsewhere, You(s) stops and asks
3. **Content similarity check** — if similar content already exists (Chroma similarity > 0.85), You(s) asks before creating a duplicate
4. **Folder confirmation** — if the target folder is new, You(s) confirms before creating it
5. **Diff preview** — every write shows a unified diff in the terminal before anything is applied
6. **Approval gate** — `[y/n/e]` — apply, cancel, or open in your editor
7. **`.bak` file** — created before every overwrite, no exceptions

In `/mode auto`, the diff is still shown but the write proceeds automatically after a 2-second pause so you can `Ctrl+C`.

---

## Memory and Personalisation

### Style Learning
At session start, You(s) scans your wiki and builds a style profile:

- Preferred coding language and libraries
- Explanation depth and tone derived from how you write
- Active projects and current priorities from `hot.md`
- Opinions and decisions from `origin: self-written` pages — never contradicted

### Life Profile Onboarding *(requires VPS)*
You(s) asks you one question per day via Telegram, drawn from a 1,500-question life profile spanning your history, values, cognitive style, and personality. Answers are written to your vault locally and build into:

- `/wiki/identity/life-profile.md` — a continuously updated personal knowledge base
- Your style profile JSON — tone, depth, active topics
- The "About Me" block in `hot.md` — loaded every session

No duplicate questions, ever. Skipped questions are archived and replaced. The daily question fires from the VPS at your configured time — your local machine does not need to be on.

---

## VPS Backend — 24/7 Autonomous Core *(optional)*

You(s) works fully offline. The VPS backend adds the ability to run scheduled work — market scans, daily questions, Telegram alerts — without your local machine being on.

### Architecture

```
┌─────────────────────────────────────────┐
│         VPS — You(s) Cloud Core         │
│  (runs 24/7)                            │
│                                         │
│  • Job Scheduler (APScheduler)          │
│  • Telegram Bot (send & receive)        │
│  • OpenTrader market scans              │
│  • MCP-Trading signal engine            │
│  • Job Queue (Redis or SQLite)          │
│  • Auth / API gateway                   │
└────────────────┬────────────────────────┘
                 │  HTTPS + mutual TLS
                 │  Jobs ↓     Results ↑
┌────────────────┴────────────────────────┐
│       Local Device — You(s) Client      │
│  (runs when machine is on)              │
│                                         │
│  • Full vault access (local only)       │
│  • Executes jobs received from VPS      │
│  • Sends back result summaries only     │
│  • Raw vault content never leaves       │
└─────────────────────────────────────────┘
```

The VPS dispatches instructions. Your local client executes them against your vault. Only summaries and confirmations are returned — raw file content never leaves your device.

### Security
- **mTLS** — both sides authenticate; connections cannot be impersonated
- **API key** — hashed with bcrypt server-side; rotates with immediate invalidation via `/config server rotate-key`
- **Ed25519 device keypair** — mandatory for all VPS connections; private key never leaves your device; every job result is signed and verified before the VPS accepts it
- **No vault exposure** — the VPS never sees raw file content, wiki page text, or local filesystem paths

### Connect to a VPS

```bash
yous config server connect --host https://your-vps-ip --key YOUR_API_KEY
```

### VPS Setup

```bash
git clone https://github.com/yous-ai/yous-server
cd yous-server
uv sync
cp config.example.yaml config.yaml
# Edit config.yaml: Telegram token, user API keys, scheduler settings
uv run yous-server start
```

Recommended spec: **8 GB RAM / 4 vCPU / 75 GB NVMe**. A Caddy reverse proxy handles TLS. The server runs as a systemd service or Docker container.

---

## Install

Python 3.11+ is required. Choose whichever install method suits you.

```bash
# Recommended for developers
pipx install yous

# macOS
brew install yous-ai/tap/yous

# Windows
scoop install yous

# uv users
uv tool install yous
```

After any method, open any terminal and type:

```bash
yous
```

### First-Run Setup

On first launch, a setup wizard walks you through configuration in about 2 minutes:

```
Welcome to You(s) v1.1

? Where is your Obsidian vault?  ~/vault
? Which LLM provider?            DeepSeek
? Enter your DeepSeek API key:   ••••••••
? Connect Google Drive?          Yes  ← opens browser for OAuth
? Enable Telegram alerts?        Yes
? Telegram Bot Token:            ••••••••
? Telegram Chat ID:              ••••••••

Setup complete. Type 'yous' anytime to start.
```

### Shell Completion

```bash
yous --install-completion
```

---

## Slash Commands

Slash commands are for controlling You(s) itself. Everything else is natural language.

| Command | Description |
|---|---|
| `/help` | Show all slash commands and agent capabilities |
| `/new` | Start a new session (clears session memory, wiki is preserved) |
| `/sessions` | List all past sessions with timestamps and summaries |
| `/session <id>` | Resume or inspect a past session |
| `/agents` | List available agent personas / switch between them |
| `/skills` | List all skill pages in `/wiki/skills/` |
| `/mcps` | List currently connected MCP servers |
| `/mode ask` | Ask before every action (default) |
| `/mode auto` | Act and log — still shows diffs before writes |
| `/logs` | Show recent activity log |
| `/logs sync` | Force all pending log writes immediately |
| `/cost` | Show API cost breakdown for this session |
| `/audit` | Run vault linting — orphan pages, broken links, path reconciliation |
| `/style` | Show your current style profile derived from the wiki |
| `/config` | Open config file for editing |
| `/config env` | Show the environment/app cache as a table |
| `/config env clear` | Wipe the env cache and re-discover on next use |
| `/config drive full-access` | Enable full Google Drive access beyond the default workspace folder |
| `/config server connect` | Connect local client to a VPS backend |
| `/config server rotate-key` | Rotate VPS API key (old key invalidated immediately) |

---

## Configuration

Key config paths:

| Path | Purpose |
|---|---|
| `~/.yous/config.yaml` | Main configuration |
| `~/.yous/.env` | API keys and secrets |
| `~/.yous/vault_map.json` | Persistent vault file index |
| `~/.yous/env_cache.json` | Cached environment paths (OpenD, etc.) |
| `~/.yous/credentials/google_token.json` | Google OAuth token |
| `~/.yous/credentials/device_key.pem` | Ed25519 private key (chmod 600) |
| `~/.yous/onboarding/` | Life profile question state |
| `~/.yous/logs/` | Activity logs |

Key config options:

```yaml
logs:
  auto_update: true           # set false to disable automatic log writes
  write_on_significant: true
  write_on_session_end: true

writes:
  diff_preview: true          # set false to skip diff display (power users only)
  auto_apply_delay_seconds: 2 # pause in auto mode before applying

trading:
  allow_real_execution: false # must be true to place live orders
  default_trd_env: SIMULATE
  confirmation_timeout_seconds: 60

env_cache:
  stale_after_days: 7
```

---

## Tech Stack

| Layer | Tool |
|---|---|
| Language | Python 3.11+ |
| LLM — fast tasks | DeepSeek V4 Flash |
| LLM — reasoning | DeepSeek V4 Pro |
| LLM — high-stakes decisions | DeepSeek V4 Pro + thinking mode |
| Semantic search | ChromaDB |
| CLI | `rich` + `prompt_toolkit` |
| Word docs | `python-docx` |
| Spreadsheets | Google Sheets API + `openpyxl` |
| Google integration | `google-api-python-client` |
| Session storage | SQLite |
| Trading | OpenTrader + MCP-Trading + MooMoo (Futu OpenD) |
| Flights | Amadeus API |
| Places / geocoding | Google Places API |
| Weather | OpenMeteo |
| SSH / DevOps | `paramiko` + Docker SDK |
| Logging | Python `logging` + structured JSON |

---

## Provenance and Quality Control

- All agent-generated content is tagged `origin: agent-compiled`
- All user-written content is tagged `origin: self-written`
- You(s) cannot overwrite `origin: self-written` pages without explicit confirmation
- Every wiki write creates a `.bak` before overwriting
- The critique gate (DeepSeek Pro self-review) runs on all outputs before delivery
- Conflicts are flagged in the change plan — never silently resolved
- Schema linting available via `/audit`

---

## Version

**v1.1** — Current  
**v1.0** — Foundation release

You(s) is a personal project, actively developed.