feat: initial thesis-agent scaffold

Local, sandboxed thesis-writing agent built on deepagents + Karpathy
LLM Wiki pattern.

Architecture
  - `thesis` CLI (Typer): setup, init, status, ingest, curate, chat,
    write, lint, style
  - Per-source wiki pages as the retrieval layer (no RAG, no embeddings)
  - Two-tier memory: SqliteSaver (threads) + SqliteStore (cross-thread),
    both on plain SQLite files under data/
  - Per-subagent write sandbox (researcher / wiki-curator / drafter),
    no shell/network/code-exec tools exposed to the agent
  - Providers: Anthropic + OpenRouter, switchable via THESIS_PROVIDER

First-run UX
  - `thesis setup` wizard handles retries, empty input, Ctrl-C, bad key
    prefix, validation failure. Non-interactive mode for CI via
    --non-interactive --provider --api-key

Tests
  - 31/31 passing: ingest idempotency, sandbox scope enforcement,
    11 wizard branches via mocked questionary, CLI smoke

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NikitasT2003

.env.example

@@ -0,0 +1,25 @@
+# Copy this file to .env and fill in your keys.
+# `thesis setup` will do this for you interactively.
+
+# Which LLM provider to use: "anthropic" (default) or "openrouter".
+THESIS_PROVIDER=anthropic
+
+# --- Anthropic (THESIS_PROVIDER=anthropic) -----------------------------------
+# Get a key at https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+# --- OpenRouter (THESIS_PROVIDER=openrouter) ---------------------------------
+# Get a key at https://openrouter.ai/keys
+# Browse models at https://openrouter.ai/models
+# OPENROUTER_API_KEY=sk-or-v1-your-key-here
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# OPENROUTER_SITE_URL=https://github.com/your-org/thesis-agent   # optional, for attribution
+# OPENROUTER_SITE_NAME=thesis-agent                              # optional
+
+# --- Model overrides (both providers) ----------------------------------------
+# Anthropic-format IDs (e.g. "anthropic:claude-sonnet-4-6") when provider is anthropic.
+# OpenRouter-format IDs (e.g. "anthropic/claude-sonnet-4-5" or "openai/gpt-4o")
+# when provider is openrouter.
+# THESIS_MODEL_DRAFTER=
+# THESIS_MODEL_CURATOR=
+# THESIS_MODEL_RESEARCHER=

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python }}
+
+      - name: Install deps
+        run: uv sync --extra dev
+
+      - name: Ruff
+        run: uv run ruff check src tests
+
+      - name: Pytest
+        run: uv run pytest -q
+
+      - name: CLI smoke
+        run: |
+          uv run thesis --help
+          uv run thesis --version

.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+
+# uv
+uv.lock
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Agent runtime data (per-user, never commit)
+data/
+*.sqlite
+*.db
+*.db-journal
+.thread
+
+# User workspace (when repo is cloned and used as the workspace)
+/research/raw/*
+!/research/raw/.gitkeep
+!/research/raw/urls.txt
+/research/wiki/*
+!/research/wiki/.gitkeep
+/style/samples/*
+!/style/samples/.gitkeep
+/style/STYLE.md
+/thesis/chapters/*
+!/thesis/chapters/.gitkeep
+/thesis/outline.md
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# mypy / ruff cache
+.mypy_cache/
+.ruff_cache/

AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md — Thesis Agent Schema
+
+This file is loaded into the main agent's system prompt on every run. It defines how to organise knowledge, write the thesis, and stay grounded. Follow it exactly.
+
+---
+
+## Three layers
+
+1. **`research/raw/`** — immutable source material (PDFs, DOCX, EPUB, MD, URLs). Never edit these. The `thesis ingest` CLI command normalises each file to `research/raw/<filename>.md` (same stem as the original) and records it in `research/raw/_index.json` with `status: pending`.
+2. **`research/wiki/`** — LLM-compiled knowledge. **One wiki page per source file**, named `research/wiki/<filename>.md` (matching the raw file's stem). Plus `research/wiki/index.md` which groups pages by topic/tag.
+3. **This file (`AGENTS.md`)** — the schema that turns the raw layer into the wiki layer, and the wiki layer into grounded thesis prose.
+
+The wiki is the index. **There is no vector search, no embeddings, no RAG.** To find information you navigate `research/wiki/index.md` → entity pages → drill into the raw file only if the wiki page is insufficient. Use `read_file`, `glob`, and `grep` — nothing else.
+
+---
+
+## Wiki page template
+
+Every file under `research/wiki/<name>.md` (except `index.md`) must follow this template exactly. Use the raw source's stem as the filename.
+
+```markdown
+---
+source: <raw_filename_with_ext>
+title: <best-effort title from the source; filename if unknown>
+authors: [<author1>, <author2>]   # empty list if unknown
+date: <YYYY or YYYY-MM-DD if known; "unknown" otherwise>
+tags: [<topic1>, <topic2>, ...]   # 3-8 short lowercase tags
+---
+
+# <title>
+
+## Summary
+3–5 sentences capturing the source's thesis / core contribution / relevance. Every sentence must be supported by the source. Inline-cite with `[src:<raw_filename>]`.
+
+## Key claims
+- Claim 1. [src:<raw_filename>]
+- Claim 2. [src:<raw_filename>]
+- ...
+(5–15 bullet points. Each bullet is a discrete factual claim quotable in the thesis.)
+
+## Methods / datasets
+- <method or dataset name>: <one-line description>. [src:<raw_filename>]
+(Omit this section if the source is not empirical.)
+
+## Key terms
+- <term>: <one-line definition as used in this source>. [src:<raw_filename>]
+
+## See also
+- [[<other_source_stem>]] — <one-line reason for the link>
+(Cross-references to other wiki pages. Add reciprocally on the other page.)
+
+## Conflicts
+- ⚠ conflicts with [[<other_source_stem>]] on <claim topic>
+(Flag only — do NOT quote both sides, do NOT merge. User resolves manually.)
+```
+
+---
+
+## Citation format
+
+Any factual claim — in a wiki page, in a thesis chapter, in chat — must carry `[src:<raw_filename>]` where `<raw_filename>` is the name (with extension) of the file in `research/raw/`. Example: `[src:attention-is-all-you-need.pdf]`.
+
+Never invent a citation. If no source supports a claim, reply: **"no grounding in indexed sources — add material or remove claim."** Do not use pretraining knowledge. Do not use web search (you have no web tools anyway).
+
+---
+
+## Workflows
+
+### Ingest (user-initiated via `thesis ingest`)
+1. The CLI runs `thesis_agent.ingest` — pure Python, no agent involvement. You do not run this.
+2. After it finishes, new entries appear in `research/raw/_index.json` with `status: pending`.
+
+### Curate (agent — triggered by `thesis curate` or user request)
+1. Read `research/raw/_index.json`. Collect entries where `status == "pending"`.
+2. For each pending entry, delegate to the `wiki-curator` subagent with the raw filename. The subagent:
+   - Reads `research/raw/<name>.md`.
+   - Produces `research/wiki/<name>.md` following the template above.
+   - Updates `research/wiki/index.md` to list the new page under the right topic cluster.
+   - Flips `status` to `curated` in `_index.json`.
+3. When all pending entries are processed, report a one-line summary: `curated N sources; M conflicts flagged`.
+
+### Write (user-initiated via `thesis write <section>` or chat)
+1. Read `style/STYLE.md`. If missing, stop and tell the user to run `thesis style` first.
+2. Read `research/wiki/index.md`. Identify wiki pages relevant to the requested section.
+3. Read those wiki pages.
+4. For any claim you plan to make, verify it appears in a wiki page's "Key claims" or can be read out of the raw file. Drill into `research/raw/<file>.md` only when the wiki page is insufficient.
+5. Delegate drafting to the `drafter` subagent. The drafter writes to `thesis/chapters/<NN>.md` (matching the outline numbering in `thesis/outline.md`).
+6. Every paragraph must contain at least one `[src:...]` citation. Paragraphs with no citable claim (transitions, meta-prose) are allowed but must not make factual statements.
+
+### Lint (agent — triggered by `thesis lint` or user request)
+1. Read the target chapter file.
+2. For every `[src:<name>]` citation, verify `research/raw/<name>` exists and `research/wiki/<name>.md` exists with `status: curated`.
+3. Flag paragraphs that make factual claims without any citation.
+4. Output a short report: file, line, issue, suggested fix. Do not auto-edit unless asked.
+
+### Style learning (agent — triggered by `thesis style`)
+1. Read every file in `style/samples/`.
+2. Produce/update `style/STYLE.md` with sections: Voice, Sentence rhythm, Lexicon (jargon density, hedging words, favoured transitions), POV and tense, Citation placement habits, Structural patterns (how the user opens/closes sections).
+3. Be specific and prescriptive (e.g., "average sentence length 22–28 words; avoid sentences under 10 words except in conclusions"). The drafter will follow this verbatim.
+
+---
+
+## Write scopes (enforced by the sandbox middleware — do not attempt violations)
+
+- `researcher` subagent: **read-only**. Cannot write anywhere.
+- `wiki-curator` subagent: may write only to `research/wiki/**` and update `research/raw/_index.json`.
+- `drafter` subagent: may write only to `thesis/**`.
+- The main agent: may write to `research/wiki/index.md`, `style/STYLE.md`, and the user's explicit targets. Never write to `research/raw/` (sources are immutable). Never write to `data/` (reserved for memory databases).
+- No tool can reach outside the project workspace.
+
+---
+
+## Hard rules (non-negotiable)
+
+1. **Every factual claim** in `research/wiki/**` and `thesis/**` has a `[src:...]` citation.
+2. **Never fabricate** sources, quotes, author names, dates, or statistics.
+3. **Never write** to `research/raw/` or `data/`.
+4. **Always read** `style/STYLE.md` before any `thesis/**` write.
+5. **Contradictions are flagged, not resolved.** Add `⚠ conflicts with [[other]]` on both pages; move on.
+6. When the wiki has no answer, say so. Do not fill the gap from memory.

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+## Dev setup
+
+```bash
+git clone https://github.com/your-org/thesis-agent.git
+cd thesis-agent
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check src tests
+```
+
+## Project layout
+
+```
+src/thesis_agent/
+  cli.py          Typer CLI (thesis setup, init, ingest, ...)
+  agent.py        build_agent(): wires deepagents with our config
+  subagents.py    researcher / wiki-curator / drafter definitions
+  memory.py       SqliteSaver + SqliteStore context managers
+  sandbox.py      path-scope enforcement for agent writes
+  config.py       workspace paths + env + model defaults
+  ingest/         deterministic source extraction (no LLM)
+skills/           5 SKILL.md files (YAML frontmatter + markdown)
+AGENTS.md         operating schema loaded into every agent run
+examples/         sample workspace committed for first-run demo
+tests/            ingest + sandbox + CLI smoke tests
+```
+
+## Adding a skill
+
+1. `mkdir skills/your-skill`
+2. Create `skills/your-skill/SKILL.md`:
+
+```markdown
+---
+name: your-skill
+description: >
+  When to use this skill. Put ALL trigger conditions here — the body is
+  only loaded after the skill has been triggered. Be explicit about the
+  phrases that should activate it.
+---
+
+# your-skill
+
+Step-by-step guidance here. What to read, what to write, what to avoid.
+```
+
+3. The skill is picked up automatically on the next agent run.
+
+## Swapping the model
+
+Set env vars in `.env`:
+
+```
+THESIS_MODEL_DRAFTER=anthropic:claude-sonnet-4-6
+THESIS_MODEL_CURATOR=anthropic:claude-sonnet-4-6
+THESIS_MODEL_RESEARCHER=anthropic:claude-haiku-4-5-20251001
+```
+
+## Adjusting the sandbox
+
+`src/thesis_agent/sandbox.py` defines per-scope allow/deny globs. Tests in
+`tests/test_sandbox.py` exercise the policy — run them if you change anything
+there.
+
+Two hard invariants that should not be relaxed:
+
+1. `tools=[]` in `build_agent(...)` — no shell, no network, no code exec.
+2. `research/raw/**` and `data/**` are always on the global deny list.
+
+If you need the agent to do something it's currently blocked from, consider
+whether a deterministic Python helper (like `ingest/`) would be safer than
+giving the agent a new tool.
+
+## Tests
+
+- `tests/test_ingest.py` — extractor + manifest idempotency.
+- `tests/test_sandbox.py` — path traversal, per-scope writes.
+- `tests/test_cli_smoke.py` — `thesis --help`, `thesis init`, `thesis status`.
+
+Add tests for any new code path before sending a PR. LLM-calling tests
+should be avoided in CI (no Anthropic key available); exercise those
+locally.
+
+## Filing issues
+
+- Include the full command you ran and the error.
+- Include your Python and `uv` versions (`uv run python --version`, `uv --version`).
+- Do **not** paste your API key or source material — reproduce with the
+  committed examples where possible.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thesis-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.