tawn 0.1.0__tar.gz

tawn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Testimony Adekoya
+
+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.

tawn-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: tawn
+Version: 0.1.0
+Summary: Tawn — the personal digital twin. Local-first memory and context core for your work, wealth, research, and academic life.
+Author-email: Testimony Adekoya <testimonyadekoya.02@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tawn-hq/tawn
+Project-URL: Repository, https://github.com/tawn-hq/tawn
+Project-URL: Bug Tracker, https://github.com/tawn-hq/tawn/issues
+Keywords: ai,personal-ai,digital-twin,memory,mcp,rag,local-first,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: keyring>=25.0
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: watchfiles>=0.21
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.100; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=2.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == "gemini"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4; extra == "ollama"
+Provides-Extra: vectors
+Requires-Dist: pgvector>=0.3; extra == "vectors"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == "mcp"
+Provides-Extra: providers
+Requires-Dist: anthropic>=0.100; extra == "providers"
+Requires-Dist: openai>=2.0; extra == "providers"
+Requires-Dist: google-genai>=1.0; extra == "providers"
+Requires-Dist: ollama>=0.4; extra == "providers"
+Provides-Extra: full
+Requires-Dist: anthropic>=0.100; extra == "full"
+Requires-Dist: openai>=2.0; extra == "full"
+Requires-Dist: google-genai>=1.0; extra == "full"
+Requires-Dist: ollama>=0.4; extra == "full"
+Requires-Dist: pgvector>=0.3; extra == "full"
+Requires-Dist: fastmcp>=2.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# Tawn — the twin you own
+
+> **taw (ת) + own** — Local-first personal digital twin. Your data, your machine, your intelligence.
+
+Tawn is a self-hosted memory and context core that unifies your work, wealth, research, and academic life into one searchable brain — shared across every AI agent you use (Claude Code, Cursor, Gemini CLI, and others).
+
+```
+pip install tawn
+tawn init
+tawn web start    # opens the web dashboard at http://tawn:8787
+```
+
+## What it does
+
+- **Memory federation** — indexes conversations from Claude, ChatGPT, Gemini, Obsidian, and local files into one semantic store
+- **Domain modules** — Work, Wealth (read-only), Research, and Academic — each with its own compiled wiki and entity graph
+- **Multi-provider model routing** — Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, Ollama; local by default, cloud when needed
+- **MCP server** — any MCP-compatible agent gets `recall`, `note`, and `brief` verbs against your twin's memory
+- **Web dashboard** — streaming chat, memory browser, audit log, settings — at `tawn:8787`
+- **Capability grants** — deny-all filesystem access by default; every read and write is audited
+
+## Quick start
+
+### Requirements
+
+- Python 3.12+
+- PostgreSQL (for memory and federation tables)
+- Node.js 18+ (only needed if installing from source)
+
+### Install
+
+```bash
+# fast core install (add providers when needed)
+pipx install tawn
+
+# or install everything at once
+pipx install "tawn[full]"
+
+# individual provider extras
+pip install "tawn[anthropic]"   # Claude
+pip install "tawn[openai]"      # OpenAI / OpenRouter
+pip install "tawn[gemini]"      # Google Gemini
+pip install "tawn[ollama]"      # local models
+pip install "tawn[vectors]"     # pgvector for semantic search
+pip install "tawn[mcp]"         # MCP server
+```
+
+### Setup
+
+```bash
+tawn init                  # creates ~/.tawn/
+tawn db setup              # initialises PostgreSQL
+tawn web start             # starts the web server at tawn:8787
+```
+
+Configure model providers:
+
+```bash
+tawn setup                 # interactive wizard — sets API keys, DB, local model
+```
+
+Or set keys directly:
+
+```bash
+# keys are stored in the OS keyring, never in files
+tawn setup                 # interactive
+```
+
+### MCP integration (Claude Code)
+
+Add to your `~/.claude/claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "tawn": {
+      "command": "tawn",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then from any Claude session: `tawn.recall("…")`, `tawn.note("…")`, `tawn.brief("work")`.
+
+## Domain modules
+
+| Domain | What it tracks |
+|--------|---------------|
+| **work** | Tasks, projects, decisions — per employer |
+| **wealth** | Portfolio, net worth, holdings — **read-only, never trades** |
+| **research** | Papers, experiments, entity graph, morning brief |
+| **academic** | Applications, deadlines, proposal drafts |
+
+Extend with your own domain:
+
+```bash
+tawn domain add health     # scaffolds a new domain plugin
+```
+
+## CLI reference
+
+```
+tawn                       # chat with your twin
+tawn note "…"              # append a note to today's raw file
+tawn recall "query"        # semantic search over compiled memory
+tawn brief work            # daily summary for a domain
+tawn compile               # compile raw/ into wiki + vectors
+tawn federation sources    # list federated AI tool sources
+tawn federation merge      # ingest pending federation records
+tawn web start/stop/status # web server control
+tawn update                # check and install latest release
+tawn config list           # view all settings
+```
+
+## Architecture
+
+```
+~/.tawn/
+├── raw/          # immutable ingested sources
+├── wiki/         # compiled markdown knowledge
+├── federation/   # AI tool exports + adapters
+├── grants.yaml   # capability grants (deny-all default)
+└── audit.log     # every write, every cross-domain action
+```
+
+API server binds to `127.0.0.1` only. Wealth core is read-only. No withdrawal credentials ever stored.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tawn-0.1.0/README.md

@@ -0,0 +1,131 @@
+# Tawn — the twin you own
+
+> **taw (ת) + own** — Local-first personal digital twin. Your data, your machine, your intelligence.
+
+Tawn is a self-hosted memory and context core that unifies your work, wealth, research, and academic life into one searchable brain — shared across every AI agent you use (Claude Code, Cursor, Gemini CLI, and others).
+
+```
+pip install tawn
+tawn init
+tawn web start    # opens the web dashboard at http://tawn:8787
+```
+
+## What it does
+
+- **Memory federation** — indexes conversations from Claude, ChatGPT, Gemini, Obsidian, and local files into one semantic store
+- **Domain modules** — Work, Wealth (read-only), Research, and Academic — each with its own compiled wiki and entity graph
+- **Multi-provider model routing** — Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, Ollama; local by default, cloud when needed
+- **MCP server** — any MCP-compatible agent gets `recall`, `note`, and `brief` verbs against your twin's memory
+- **Web dashboard** — streaming chat, memory browser, audit log, settings — at `tawn:8787`
+- **Capability grants** — deny-all filesystem access by default; every read and write is audited
+
+## Quick start
+
+### Requirements
+
+- Python 3.12+
+- PostgreSQL (for memory and federation tables)
+- Node.js 18+ (only needed if installing from source)
+
+### Install
+
+```bash
+# fast core install (add providers when needed)
+pipx install tawn
+
+# or install everything at once
+pipx install "tawn[full]"
+
+# individual provider extras
+pip install "tawn[anthropic]"   # Claude
+pip install "tawn[openai]"      # OpenAI / OpenRouter
+pip install "tawn[gemini]"      # Google Gemini
+pip install "tawn[ollama]"      # local models
+pip install "tawn[vectors]"     # pgvector for semantic search
+pip install "tawn[mcp]"         # MCP server
+```
+
+### Setup
+
+```bash
+tawn init                  # creates ~/.tawn/
+tawn db setup              # initialises PostgreSQL
+tawn web start             # starts the web server at tawn:8787
+```
+
+Configure model providers:
+
+```bash
+tawn setup                 # interactive wizard — sets API keys, DB, local model
+```
+
+Or set keys directly:
+
+```bash
+# keys are stored in the OS keyring, never in files
+tawn setup                 # interactive
+```
+
+### MCP integration (Claude Code)
+
+Add to your `~/.claude/claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "tawn": {
+      "command": "tawn",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then from any Claude session: `tawn.recall("…")`, `tawn.note("…")`, `tawn.brief("work")`.
+
+## Domain modules
+
+| Domain | What it tracks |
+|--------|---------------|
+| **work** | Tasks, projects, decisions — per employer |
+| **wealth** | Portfolio, net worth, holdings — **read-only, never trades** |
+| **research** | Papers, experiments, entity graph, morning brief |
+| **academic** | Applications, deadlines, proposal drafts |
+
+Extend with your own domain:
+
+```bash
+tawn domain add health     # scaffolds a new domain plugin
+```
+
+## CLI reference
+
+```
+tawn                       # chat with your twin
+tawn note "…"              # append a note to today's raw file
+tawn recall "query"        # semantic search over compiled memory
+tawn brief work            # daily summary for a domain
+tawn compile               # compile raw/ into wiki + vectors
+tawn federation sources    # list federated AI tool sources
+tawn federation merge      # ingest pending federation records
+tawn web start/stop/status # web server control
+tawn update                # check and install latest release
+tawn config list           # view all settings
+```
+
+## Architecture
+
+```
+~/.tawn/
+├── raw/          # immutable ingested sources
+├── wiki/         # compiled markdown knowledge
+├── federation/   # AI tool exports + adapters
+├── grants.yaml   # capability grants (deny-all default)
+└── audit.log     # every write, every cross-domain action
+```
+
+API server binds to `127.0.0.1` only. Wealth core is read-only. No withdrawal credentials ever stored.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tawn-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tawn"
+version = "0.1.0"
+description = "Tawn — the personal digital twin. Local-first memory and context core for your work, wealth, research, and academic life."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Testimony Adekoya", email = "testimonyadekoya.02@gmail.com" },
+]
+keywords = ["ai", "personal-ai", "digital-twin", "memory", "mcp", "rag", "local-first", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.12"
+dependencies = [
+    # core — always installed
+    "pydantic>=2.7",
+    "pydantic-settings>=2.2",
+    "PyYAML>=6.0",
+    "typer>=0.12",
+    "SQLAlchemy>=2.0",
+    "psycopg[binary]>=3.1",
+    "httpx>=0.27",
+    "rich>=13.7",
+    "fastapi>=0.111",
+    "uvicorn>=0.30",
+    "keyring>=25.0",
+    "python-frontmatter>=1.1",
+    "rapidfuzz>=3.0",
+    "watchfiles>=0.21",
+]
+
+[project.optional-dependencies]
+# individual provider extras
+anthropic  = ["anthropic>=0.100"]
+openai     = ["openai>=2.0"]
+gemini     = ["google-genai>=1.0"]
+ollama     = ["ollama>=0.4"]
+vectors    = ["pgvector>=0.3"]
+mcp        = ["fastmcp>=2.0"]
+# convenience meta-extras
+providers  = ["anthropic>=0.100", "openai>=2.0", "google-genai>=1.0", "ollama>=0.4"]
+full       = [
+    "anthropic>=0.100", "openai>=2.0", "google-genai>=1.0",
+    "ollama>=0.4", "pgvector>=0.3", "fastmcp>=2.0",
+]
+dev = ["pytest>=8.0", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://github.com/tawn-hq/tawn"
+Repository = "https://github.com/tawn-hq/tawn"
+"Bug Tracker" = "https://github.com/tawn-hq/tawn/issues"
+
+[project.scripts]
+tawn = "tawn.cli:app"
+
+[project.entry-points."tawn.domains"]
+wealth = "tawn.domains.wealth:register"
+work = "tawn.domains.work:register"
+research = "tawn.domains.research:register"
+academic = "tawn.domains.academic:register"
+hobby = "tawn.domains.hobby:register"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tawn = [
+    "web/dist/**/*",
+    "web/dist/*",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.tawn.scripts]
+build-web = "cd frontend && npm install && npm run build"

tawn-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tawn-0.1.0/setup.py

@@ -0,0 +1,51 @@
+import shutil
+import subprocess
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+
+HERE = Path(__file__).parent
+FRONTEND = HERE / "frontend"
+DIST_SRC = FRONTEND / "dist"
+# frontend dist lands inside the package so it's included in the wheel
+DIST_DST = HERE / "src" / "tawn" / "web" / "dist"
+
+
+class BuildFrontend(build_py):
+    def run(self):
+        # `python -m build`'s default flow builds the wheel from an
+        # isolated copy of the *sdist*, not the working tree — and the
+        # sdist never contains the top-level frontend/ dir (it's not part
+        # of the Python package, so nothing declares it for inclusion).
+        # `src/tawn/web/dist` DOES ship in the sdist (it's inside the
+        # package, matched by package-data), so if the workflow already
+        # populated it — build the frontend, then `cp -r dist/. ../src/
+        # tawn/web/dist/`, exactly like publish.yml — there's nothing left
+        # to do here and no reason to expect frontend/ to exist at all.
+        already_bundled = DIST_DST.is_dir() and any(DIST_DST.iterdir())
+        if not already_bundled:
+            if FRONTEND.is_dir():
+                if not DIST_SRC.is_dir():
+                    if shutil.which("npm"):
+                        subprocess.run(["npm", "ci"], cwd=str(FRONTEND), check=True)
+                        subprocess.run(["npm", "run", "build"], cwd=str(FRONTEND), check=True)
+                    else:
+                        import warnings
+                        warnings.warn("npm not found — web dashboard will not be bundled", stacklevel=2)
+                if DIST_SRC.is_dir():
+                    if DIST_DST.exists():
+                        shutil.rmtree(DIST_DST)
+                    shutil.copytree(DIST_SRC, DIST_DST)
+            else:
+                import warnings
+                warnings.warn(
+                    "frontend/ not present (isolated sdist build?) and no "
+                    "pre-built web/dist — web dashboard will not be bundled",
+                    stacklevel=2,
+                )
+
+        super().run()
+
+
+setup(cmdclass={"build_py": BuildFrontend})

tawn-0.1.0/src/tawn/__init__.py

@@ -0,0 +1,3 @@
+"""Tawn — the personal digital twin. Capability-gated memory core."""
+
+__version__ = "0.1.0"

tawn-0.1.0/src/tawn/_webserver.py

@@ -0,0 +1,66 @@
+"""Internal entrypoint for the background web server process.
+
+Run as: python -m tawn._webserver <port>
+Not intended for direct user invocation — use `tawn web start/stop`.
+"""
+
+import sys
+
+
+def _start_auto_compiler(engine) -> None:
+    import threading
+    import time
+    from tawn.db import session as db_session
+    from tawn.compiler.compiler import run_compile as run_compiler
+    from tawn.federation.merge import scan_all_sources, merge_pending
+    from tawn.home import tawn_home
+
+    def _bootstrap_then_loop():
+        # Bootstrap: ingest + merge all existing federation files on startup.
+        # Runs in this background thread, not before uvicorn.run() — a
+        # source directory can hold thousands of files (a size cap on
+        # individual files exists, but the walk itself over many entries
+        # still takes real time), and the web server must bind its port
+        # immediately regardless of how long that one-time scan takes.
+        try:
+            with db_session(engine) as s:
+                n = scan_all_sources(tawn_home(), s)
+                if n > 0:
+                    merge_pending(tawn_home(), s)
+        except Exception:
+            pass
+
+        while True:
+            try:
+                with db_session(engine) as session:
+                    run_compiler(tawn_home(), session)
+            except Exception:
+                pass
+            time.sleep(30 * 60)  # 30-minute interval
+
+    t = threading.Thread(target=_bootstrap_then_loop, name="tawn-auto-compiler", daemon=True)
+    t.start()
+
+
+def main(port: int = 8787) -> None:
+    import uvicorn
+    from tawn.db import make_engine
+    from tawn.web import create_app
+
+    from tawn.db import init_db
+    from tawn.updater import start_daily_updater
+    engine = make_engine(pooled=True)
+    init_db(engine)
+    start_daily_updater()
+    _start_auto_compiler(engine)
+    uvicorn.run(
+        create_app(engine),
+        host="127.0.0.1",
+        port=port,
+        log_level="warning",
+    )
+
+
+if __name__ == "__main__":
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 8787
+    main(port)

tawn-0.1.0/src/tawn/branding.py

@@ -0,0 +1,82 @@
+"""Branded terminal identity (brand/README.md: Cairn × Sandstone & Lapis).
+
+The cairn: three stones, lapis capstone. The wordmark lettering follows
+the drawn monoline mark — rounded, lowercase, final n in lapis.
+Colors are the brand tokens; Rich truecolor degrades gracefully.
+"""
+
+from rich.columns import Columns
+from rich.console import Group
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+
+# brand tokens (brand/tokens.css) — dark-ground values; terminals are
+# usually dark, and both lapis values pass on light too.
+LAPIS = "#4A7BC8"
+BONE = "#EFE9DC"
+MUTED = "#ADA28C"
+
+_CAIRN = [
+    ("   ▄██▄   ", LAPIS),
+    ("   ▀██▀   ", LAPIS),
+    ("  ▄████▄  ", BONE),
+    ("  ▀████▀  ", BONE),
+    (" ▄██████▄ ", BONE),
+    (" ▀██████▀ ", BONE),
+]
+
+# monoline block lettering — t a w in bone, n in lapis (the letter that
+# makes it *own*), matching the wordmark rule in brand/README.md
+_LETTERS = [
+    ("▄█▄  ▄▀▀▄  █   █  ", "█▀▀▄"),
+    (" █   █▄▄█  █ ▄ █  ", "█  █"),
+    (" ▀▄  █  █  ▀▄▀▄▀  ", "█  █"),
+]
+
+
+def cairn() -> Text:
+    art = Text()
+    for i, (line, color) in enumerate(_CAIRN):
+        art.append(line, style=color)
+        if i < len(_CAIRN) - 1:
+            art.append("\n")
+    return art
+
+
+def wordmark() -> Text:
+    art = Text()
+    for i, (taw, n) in enumerate(_LETTERS):
+        art.append(taw, style=f"bold {BONE}")
+        art.append(n, style=f"bold {LAPIS}")
+        if i < len(_LETTERS) - 1:
+            art.append("\n")
+    return art
+
+
+def banner(version: str) -> Group:
+    lockup = Columns([cairn(), Padding(wordmark(), (1, 0, 0, 2))], padding=(0, 2))
+    tag = Text()
+    tag.append("the twin you own", style=f"italic {MUTED}")
+    tag.append(f"  ·  v{version}", style=MUTED)
+    return Group(lockup, Padding(tag, (0, 0, 0, 1)))
+
+
+def status_table(rows: list[tuple[str, bool, str]]) -> Table:
+    t = Table(show_header=False, box=None, padding=(0, 1))
+    t.add_column(style=MUTED)
+    t.add_column()
+    t.add_column(style=MUTED)
+    for name, ok, detail in rows:
+        mark = Text("●", style="green" if ok else "red")
+        t.add_row(name, mark, detail)
+    return t
+
+
+def commands_table(commands: list[tuple[str, str]]) -> Table:
+    t = Table(show_header=False, box=None, padding=(0, 1))
+    t.add_column(style=f"bold {LAPIS}")
+    t.add_column(style=MUTED)
+    for cmd, desc in commands:
+        t.add_row(cmd, desc)
+    return t

tawn-0.1.0/src/tawn/capability/__init__.py

@@ -0,0 +1 @@
+"""Capability layer: grants, integrity, audit, and the FS chokepoint."""