project-brain 0.1.0__tar.gz

project_brain-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+*.egg
+
+# Node
+node_modules/
+dist/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Alembic
+alembic/versions/__pycache__/
+.vercel
+.env*.local
+
+changes_summary.txt
+
+.claude

project_brain-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: project-brain
+Version: 0.1.0
+Summary: CLI for ProjectBrain — AI-native project management
+Author-email: Li-Hsuan Lung <li-hsuan.lung@9trinkets.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: publish
+Requires-Dist: twine>=5.0; extra == 'publish'

project_brain-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "project-brain"
+version = "0.1.0"
+description = "CLI for ProjectBrain — AI-native project management"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Li-Hsuan Lung", email = "li-hsuan.lung@9trinkets.com" },
+]
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "rich>=13.0",
+    "typer[all]>=0.12",
+]
+
+[project.optional-dependencies]
+publish = ["twine>=5.0"]
+
+[project.scripts]
+pb = "pb.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pb"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]

project_brain-0.1.0/src/pb/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

project_brain-0.1.0/src/pb/client.py

@@ -0,0 +1,122 @@
+"""Sync httpx client for the ProjectBrain API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import click  # Keep for other potential uses, though we're replacing ClickException
+
+from pb import config
+
+
+class APIError(Exception):
+    """Custom exception for API errors."""
+    def __init__(self, detail: str, code: int | None = None):
+        self.detail = detail
+        self.code = code
+        super().__init__(self.detail)
+
+    def __str__(self):
+        if self.code:
+            return f"API error ({self.code}): {self.detail}"
+        return self.detail
+
+
+def _make_client(server: str | None = None, token: str | None = None) -> httpx.Client:
+    base = server or config.get_server()
+    tok = token or config.get_token()
+    if not tok:
+        raise APIError(
+            "Not authenticated. Run `pb login` first or set PB_TOKEN."
+        )
+    return httpx.Client(
+        base_url=base,
+        headers={"Authorization": f"Bearer {tok}"},
+        timeout=30.0,
+    )
+
+
+def _handle_error(resp: httpx.Response) -> None:
+    if resp.status_code < 400:
+        return
+    try:
+        body = resp.json()
+        detail = body.get("detail", body)
+    except Exception:
+        detail = resp.text or f"HTTP {resp.status_code}"
+    if isinstance(detail, list):
+        detail = "; ".join(
+            d.get("msg", str(d)) if isinstance(d, dict) else str(d)
+            for d in detail
+        )
+    raise APIError(detail=str(detail), code=resp.status_code)
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json_body: dict[str, Any] | None = None,
+    server: str | None = None,
+    token: str | None = None,
+) -> Any:
+    """Make an authenticated API request and return parsed JSON."""
+    with _make_client(server, token) as client:
+        resp = client.request(method, path, params=params, json=json_body)
+    _handle_error(resp)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()
+
+
+def resolve_project(value: str, *, server: str | None = None) -> str:
+    """Resolve a project identifier to a UUID.
+
+    Accepts a full UUID, a short UUID prefix (e.g. first 8 chars),
+    or a project name (case-insensitive substring match).
+    Raises APIError if no match or ambiguous.
+    """
+    import re
+    # Full UUID — return as-is
+    if re.match(r"^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$", value, re.I):
+        return value
+
+    projects = request("GET", "/api/projects/", server=server)
+
+    # Short hex prefix (e.g. "a84c4871") — match against ID start
+    if re.match(r"^[0-9a-f]+$", value, re.I) and len(value) >= 4:
+        prefix = value.lower()
+        matches = [p for p in projects if p["id"].lower().startswith(prefix)]
+        if len(matches) == 1:
+            return matches[0]["id"]
+        if len(matches) > 1:
+            names = ", ".join(f"{m['name']} ({m['id'][:8]})" for m in matches)
+            raise APIError(f"Ambiguous ID prefix '{value}' — matches: {names}.")
+        # Fall through to name search
+
+    # Name search (case-insensitive substring)
+    needle = value.lower()
+    matches = [p for p in projects if needle in p["name"].lower()]
+    if len(matches) == 1:
+        return matches[0]["id"]
+    if len(matches) == 0:
+        raise APIError(f"No project matching '{value}'. Run `pb projects list` to see available projects.")
+    names = ", ".join(m["name"] for m in matches)
+    raise APIError(f"Ambiguous project name '{value}' — matches: {names}. Use the full UUID.")
+
+
+def request_unauth(
+    method: str,
+    path: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    server: str | None = None,
+) -> Any:
+    """Make an unauthenticated API request (for login)."""
+    base = server or config.get_server()
+    with httpx.Client(base_url=base, timeout=30.0) as client:
+        resp = client.request(method, path, json=json_body)
+    _handle_error(resp)
+    return resp.json()

project_brain-0.1.0/src/pb/commands/auth.py

@@ -0,0 +1,290 @@
+"""pb login / logout / whoami commands."""
+
+from __future__ import annotations
+import typer
+from typing import Optional
+from typing_extensions import Annotated
+
+
+import socket
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from pb import config
+from pb.client import request, request_unauth, APIError
+from pb.reporters import render, panic
+
+
+# Fixed port so the redirect URI can be pre-registered in OAuth provider settings.
+# Override with PB_OAUTH_PORT if 8085 conflicts.
+_DEFAULT_OAUTH_PORT = 8085
+
+
+def _get_oauth_port() -> int:
+    import os
+    return int(os.environ.get("PB_OAUTH_PORT", str(_DEFAULT_OAUTH_PORT)))
+
+
+# ---------------------------------------------------------------------------
+# OAuth callback page — styled to match the ProjectBrain dark UI.
+# Tokens: brand warm gold #A88450, warm neutral slate, Lora + Plus Jakarta Sans.
+# ---------------------------------------------------------------------------
+_CALLBACK_HTML = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>ProjectBrain — Logged In</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Lora:wght@400&family=Plus+Jakarta+Sans:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  * { margin:0; padding:0; box-sizing:border-box; }
+  body {
+    min-height:100vh;
+    display:flex;
+    align-items:center;
+    justify-content:center;
+    background:#0A0A0B;
+    color:#E8E3DA;
+    font-family:'Plus Jakarta Sans',system-ui,sans-serif;
+    line-height:1.65;
+    letter-spacing:.01em;
+  }
+  .card {
+    text-align:center;
+    padding:48px 40px;
+    background:#1A1714;
+    border:1px solid #272420;
+    border-radius:16px;
+    max-width:420px;
+    width:90%;
+  }
+  .icon {
+    width:56px; height:56px;
+    margin:0 auto 20px;
+    background:#A88450;
+    border-radius:50%;
+    display:flex;
+    align-items:center;
+    justify-content:center;
+  }
+  .icon svg { width:28px; height:28px; fill:none; stroke:#fff; stroke-width:2.5; stroke-linecap:round; stroke-linejoin:round; }
+  h1 {
+    font-family:'Lora',serif;
+    font-weight:400;
+    font-size:26px;
+    line-height:1.25;
+    margin-bottom:8px;
+  }
+  p {
+    color:#8A8580;
+    font-size:15px;
+  }
+  .tag {
+    display:inline-block;
+    margin-top:24px;
+    padding:6px 14px;
+    font-size:12px;
+    font-weight:500;
+    letter-spacing:.04em;
+    text-transform:uppercase;
+    color:#C8A570;
+    background:#261E15;
+    border-radius:6px;
+  }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">
+      <svg viewBox="0 0 24 24"><polyline points="20 6 9 17 4 12"/></svg>
+    </div>
+    <h1>Logged in</h1>
+    <p>You can close this tab and return to the terminal.</p>
+    <span class="tag">ProjectBrain CLI</span>
+  </div>
+</body>
+</html>
+"""
+
+
+def _run_oauth_callback_server(port: int) -> str | None:
+    """Start a one-shot HTTP server to capture the OAuth code."""
+    captured: dict[str, str | None] = {"code": None}
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            qs = parse_qs(urlparse(self.path).query)
+            captured["code"] = qs.get("code", [None])[0]
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            body = _CALLBACK_HTML
+            self.wfile.write(body.encode("utf-8"))
+
+        def log_message(self, *_args: object) -> None:
+            pass  # silence request logs
+
+    server = HTTPServer(("127.0.0.1", port), Handler)
+    server.timeout = 120  # 2 minutes
+    server.handle_request()
+    server.server_close()
+    return captured["code"]
+
+
+def login(
+    ctx: typer.Context,
+    token_value: Annotated[Optional[str], typer.Option("--token", help="API token (pb_xxx or JWT).")] = None,
+    use_google: Annotated[bool, typer.Option("--google", help="Login with Google (opens browser).")] = False,
+    use_github: Annotated[bool, typer.Option("--github", help="Login with GitHub (opens browser).")] = False,
+) -> None:
+    """Authenticate with ProjectBrain."""
+    server = ctx.obj.get("server")
+
+    try:
+        if token_value:
+            # Token-based login — validate by calling /api/auth/me
+            # Warn if overwriting a human JWT with an agent key
+            existing = config.get_file_token()
+            if (
+                token_value.startswith("pb_")
+                and existing
+                and not existing.startswith("pb_")
+            ):
+                typer.echo(
+                    "Warning: overwriting human login session with an agent API key. "
+                    "Features like `pb run --agent` require human auth."
+                )
+            config.save(token_value, server)
+            try:
+                user = request("GET", "/api/auth/me", server=server, token=token_value)
+            except APIError:
+                config.clear()
+                panic(code="invalid_token", message="Invalid token — could not authenticate.")
+            render(user)
+            return
+
+        if use_google:
+            _login_oauth(server, provider="google")
+            return
+
+        if use_github:
+            _login_oauth(server, provider="github")
+            return
+
+        # Interactive email/password login
+        email = typer.prompt("Email")
+        password = typer.prompt("Password", hide_input=True)
+        data = request_unauth(
+            "POST",
+            "/api/auth/login",
+            json_body={"email": email, "password": password},
+            server=server,
+        )
+        token = data["access_token"]
+        config.save(token, server)
+
+        # Fetch identity to confirm
+        user = request("GET", "/api/auth/me", server=server, token=token)
+        render(user)
+    except APIError as e:
+        panic(code=e.code, message=str(e))
+
+
+_OAUTH_CONFIG = {
+    "google": {
+        "env_var": "PB_GOOGLE_CLIENT_ID",
+        "auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
+        "scope": "openid%20email%20profile",
+        "extra_params": "&access_type=offline&prompt=select_account",
+        "api_path": "/api/auth/google",
+    },
+    "github": {
+        "env_var": "PB_GITHUB_CLIENT_ID",
+        "auth_url": "https://github.com/login/oauth/authorize",
+        "scope": "read:user%20user:email",
+        "extra_params": "",
+        "api_path": "/api/auth/github",
+    },
+}
+
+
+def _login_oauth(server: str | None, provider: str) -> None:
+    """Browser-based OAuth flow (Google or GitHub)."""
+    import os
+    cfg = _OAUTH_CONFIG[provider]
+
+    try:
+        client_id = os.environ.get(cfg["env_var"])
+        if not client_id:
+            try:
+                providers = request_unauth("GET", "/api/auth/providers", server=server)
+                client_id = (providers.get(provider) or {}).get("client_id")
+            except APIError:
+                pass # Fail over to the panic below
+        if not client_id:
+            panic(
+                code="oauth_config_missing",
+                message=f"{provider.title()} client ID not found. Set {cfg['env_var']} or deploy the /providers endpoint."
+            )
+
+        port = _get_oauth_port()
+        redirect_uri = f"http://localhost:{port}/callback"
+
+        params = (
+            f"client_id={client_id}"
+            f"&redirect_uri={redirect_uri}"
+            f"&response_type=code"
+            f"&scope={cfg['scope']}"
+            f"{cfg['extra_params']}"
+        )
+        url = f"{cfg['auth_url']}?{params}"
+
+        typer.echo(f"Opening browser for {provider.title()} login...")
+        webbrowser.open(url)
+        typer.echo("Waiting for callback (press Ctrl+C to cancel)...")
+
+        code = _run_oauth_callback_server(port)
+        if not code:
+            panic(code="oauth_cancelled", message="No authorization code received. Login cancelled.")
+
+        data = request_unauth(
+            "POST",
+            cfg['api_path'],
+            json_body={"code": code, "redirect_uri": redirect_uri},
+            server=server,
+        )
+        token = data["access_token"]
+        config.save(token, server)
+
+        user = request("GET", "/api/auth/me", server=server, token=token)
+        render(user)
+    except APIError as e:
+        panic(code=e.code, message=str(e))
+
+
+def whoami(ctx: typer.Context) -> None:
+    """Show current authenticated identity."""
+    server = ctx.obj.get("server")
+    try:
+        user = request("GET", "/api/auth/me", server=server)
+        if ctx.obj.get("json"):
+            render(user)
+        else:
+            typer.echo(f"{user['name']} <{user['email']}>")
+            typer.echo(f"  ID:   {user['id']}")
+            typer.echo(f"  Type: {user['user_type']}")
+            src = config.token_source()
+            source = "PB_TOKEN" if src == "env" else "~/.pb/config.json"
+            typer.echo(f"  Auth: {source}")
+    except APIError as e:
+        panic(code=e.code, message=str(e))
+
+
+def logout() -> None:
+    """Clear stored credentials."""
+    config.clear()
+    typer.echo("Logged out.")

project_brain-0.1.0/src/pb/commands/backfill_embeddings.py

@@ -0,0 +1,53 @@
+import asyncio
+import typer
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+# This is a hack to get the app config.
+# In a real application, the CLI and API would share a common package.
+import sys
+sys.path.append("api")  # models use `from app.* import …` (relative to api/)
+
+from app.config import settings
+from app.models.fact import Fact
+from app.models.decision import Decision
+from app.models.skill import Skill
+from app.services.embeddings import upsert_embedding
+
+app = typer.Typer()
+
+async def backfill():
+    engine = create_async_engine(settings.database_url, echo=False)
+    AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+    async with AsyncSessionLocal() as db:
+        entity_types = {
+            "fact": Fact,
+            "decision": Decision,
+            "skill": Skill,
+        }
+        for entity_type, model in entity_types.items():
+            print(f"Querying all entities of type: {entity_type}...")
+            result = await db.execute(select(model))
+            entities = result.scalars().all()
+            print(f"Found {len(entities)} entities. Processing...")
+            for i, entity in enumerate(entities):
+                try:
+                    print(f"  - ({i+1}/{len(entities)}) Upserting embedding for {entity_type} {entity.id}...")
+                    await upsert_embedding(db, entity, entity_type)
+                except Exception as e:
+                    print(f"    - ERROR: Failed to upsert embedding for {entity_type} {entity.id}: {e}")
+        
+        print("Backfill complete. Committing changes.")
+        await db.commit()
+
+@app.command()
+def main():
+    """Backfill embeddings for existing facts, decisions, and skills."""
+    print("Starting embedding backfill process...")
+    asyncio.run(backfill())
+    print("Backfill process finished successfully.")
+
+if __name__ == "__main__":
+    app()

project_brain-0.1.0/src/pb/commands/completion.py

@@ -0,0 +1,40 @@
+"""Show shell completion scripts."""
+import typer
+import os
+from typer import completion
+
+app = typer.Typer(
+    help="Show shell completion scripts. To install, add the output to your shell's startup file.",
+)
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    shell: str = typer.Option(
+        os.environ.get("SHELL", "").split("/")[-1],
+        "--shell",
+        "-s",
+        help="The shell to generate completions for.",
+        autocompletion=lambda: ["bash", "zsh", "fish", "powershell", "pwsh"],
+    ),
+    install: bool = typer.Option(
+        False,
+        "--install",
+        help="Install completions for the current shell.",
+    ),
+):
+    """
+    Manage shell completions.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    prog_name = os.environ.get("PB_PROG_NAME", "pb")
+    if install:
+        typer.echo(f"Installing completions for {shell}...")
+        completion.install(shell=shell, prog_name=prog_name)
+        raise typer.Exit()
+    else:
+        script = completion.get_completion_script(prog_name=prog_name, complete_var=f"_{prog_name.upper()}_COMPLETE", shell=shell)
+        typer.echo(script)
+        raise typer.Exit()

project_brain-0.1.0/src/pb/commands/curate.py

@@ -0,0 +1,66 @@
+"""pb curate — project-level memory curator settings."""
+
+from __future__ import annotations
+from typing_extensions import Annotated
+
+import typer
+
+from pb.client import request, resolve_project, APIError
+from pb.reporters import render, panic
+
+app = typer.Typer()
+
+
+@app.command("enable")
+def enable_curate(
+    ctx: typer.Context,
+    project_id: Annotated[str, typer.Option("--project", "-p", help="Project ID.")],
+) -> None:
+    """Enable curation for a project."""
+    server = ctx.obj.get("server")
+    try:
+        project_id = resolve_project(project_id, server=server)
+        data = request(
+            "PATCH",
+            f"/api/projects/{project_id}",
+            json_body={"curation_enabled": True},
+            server=server,
+        )
+        render(data)
+    except APIError as e:
+        panic(code=e.code, message=str(e))
+
+
+@app.command("disable")
+def disable_curate(
+    ctx: typer.Context,
+    project_id: Annotated[str, typer.Option("--project", "-p", help="Project ID.")],
+) -> None:
+    """Disable curation for a project."""
+    server = ctx.obj.get("server")
+    try:
+        project_id = resolve_project(project_id, server=server)
+        data = request(
+            "PATCH",
+            f"/api/projects/{project_id}",
+            json_body={"curation_enabled": False},
+            server=server,
+        )
+        render(data)
+    except APIError as e:
+        panic(code=e.code, message=str(e))
+
+
+@app.command("status")
+def curate_status(
+    ctx: typer.Context,
+    project_id: Annotated[str, typer.Option("--project", "-p", help="Project ID.")],
+) -> None:
+    """Show curation status for a project."""
+    server = ctx.obj.get("server")
+    try:
+        project_id = resolve_project(project_id, server=server)
+        data = request("GET", f"/api/projects/{project_id}", server=server)
+        render(data)
+    except APIError as e:
+        panic(code=e.code, message=str(e))