braindump-ai 0.1.0__tar.gz

braindump_ai-0.1.0/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run ruff:*)",
+      "Bash(uv run ty:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run bandit:*)",
+      "Bash(uv run tools/check.py:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run build:*)"
+    ]
+  }
+}

braindump_ai-0.1.0/.claude/skills/code-quality/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: code-quality
+description: >
+    Activate this skill for any task updating the source code.
+    
+    This includes:
+      - creating a new source file
+      - updating an existing source file
+      - writing new tests
+      - update existing tests
+---
+
+# Code Quality Guardian
+
+This sections summarizes the checks that must pass before finalizing a code change.
+
+## Software Quality Gate
+
+There is a single entry point to run all SW quality gates for this project:
+
+- [ ] **Software Quality Gate**: ``uv run tools/check.py``
+
+The individual commands for finer-grain control are listed in the subsequent subsections.
+
+## Python Checklist
+
+- [ ] **Python Formatting**: ``uv run ruff format``
+- [ ] **Python Linting**: ``uv run ruff check``
+- [ ] **Python Type Checking**: ``uv run ty check``
+- [ ] **Python Tests**: ``uv run pytest tests``
+- [ ] **Python Security**: ``uv run bandit``
+
+## React and Typescript
+
+- [ ] **TS Type Checking**: `cd frontend && npx tsc --noEmit`
+- [ ] **Linting**: `cd frontend && npm run lint`
+- [ ] **Build**: `cd frontend && npm run build`

braindump_ai-0.1.0/.claude/skills/package-structure/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: package-structure
+description: >
+    Activate this skill for any task adding new files to the repository.
+---
+
+# Package Structure
+
+## Project structure
+
+```
+braindump/
+├── src/braindump/       # Python backend package (FastAPI, RAG pipeline, LLM backends)
+├── frontend/
+│   └── src/
+│       └── components/  # React components (one .tsx + .css pair per component)
+├── tests/               # Pytest integration tests
+├── tools/               # Build hooks and dev helper scripts
+└── pyproject.toml       # Package config, hatch build, ruff, ty, bandit
+```
+
+## Key conventions
+
+- New backend modules go in `src/braindump/`; register new API routes in `app.py`.
+- New React components go in `frontend/src/components/` with a matching `.css` file.

braindump_ai-0.1.0/.claude/skills/python-dev/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: python-dev
+description: >
+    Activate this skill for any task involving writing Python source code (extension: .py)
+    
+    This includes:
+      - writing new module
+      - fixing bugs
+      - adding type hints
+      - writing docstrings
+      - creating unit tests
+      - structuring packages
+      - reviewing Python code.
+---
+
+# Python Development Skill
+
+## Core Principles
+
+1. **Always write idiomatic Python** — follow PEP 8 and PEP 20.
+2. **Prefer clarity over cleverness** — readable code is maintainable code.
+3. **Type hints by default** — add type hints for all functions.
+4. **Fail loudly** — raise specific exceptions with helpful messages rather than silently swallowing errors.
+5. **Test-first mindset** — suggest or produce `pytest` tests alongside non-trivial implementations.
+6. **Assert code** — use `assert` statements only for internal assertions and type deductions.
+
+---
+
+## General Python Coding Guidelines
+
+Before finalising any Python output, verify:
+
+- [ ] **File Structure** — use the Python structure from [python_template.md](python_template.md)
+- [ ] **Identifier** — use snake_case names, use a leading underscore for private constants and functions
+- [ ] **PEP 8 compliant** — 4-space indent
+- [ ] **Type-annotated** — all function signatures have parameter and return types
+- [ ] **Docstrings** — public functions/classes have Google-style
+- [ ] **Error handling** — no bare `except:`, raise specific exception types
+- [ ] **No mutable defaults** — never `def f(x=[]):`, use `None` sentinel instead
+- [ ] **f-strings over %/format** — prefer f-strings
+- [ ] **Context managers** — use `with` for files, DB connections, locks
+- [ ] **Init Files** — use ``__init__.py`` files only for exposing constants and functions, do not add code
+
+
+## Test Guidelines
+
+- [ ] **Test Functions** — use free-floating test functions instead of nested functions in test classes
+- [ ] **Public Functions** — write tests for new public functions
+- [ ] **Private Functions** — write tests for private functions if suitable to reduce test variation on the public function level
+- [ ] **Test Updates** — modify existing tests as least as possible to assure software stability  
+
+
+### Project-Specific Guidelines
+
+Use these guidelines in addition to the general coding guidelines:
+
+- [ ] **Pydantic** — use `pydantic` types for file I/O and for `fastapi` routes.
+
+---
+
+## Patterns & Best Practices
+
+### Idiomatic Constructs
+
+```python
+# Prefer enumerate over manual indexing
+for i, item in enumerate(items):
+    ...
+
+# Prefer unpacking over indexing
+first, *rest = collection
+
+# Use walrus operator for assignment in conditions (Python 3.8+)
+if m := pattern.match(line):
+    process(m.group(0))
+
+# Prefer dataclasses for plain data containers
+from dataclasses import dataclass, field
+
+@dataclass
+class Config:
+    host: str = "localhost"
+    port: int = 8080
+    tags: list[str] = field(default_factory=list)
+```
+
+### Error Handling
+
+```python
+# Always be specific
+try:
+    result = risky_call()
+except (ValueError, KeyError) as exc:
+    raise RuntimeError(f"Failed to process item: {exc}") from exc
+```
+
+### Typing Patterns
+
+```python
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+def process(items: Sequence[str]) -> dict[str, int]:
+    return {item: len(item) for item in items}
+```
+
+### File I/O
+
+```python
+# Always specify encoding
+file_path.read_text(encoding="utf-8")
+
+# Use pathlib over os.path
+from pathlib import Path
+
+config_path = Path(__file__).parent / "config.yaml"
+```
+
+---
+
+## Testing
+
+Default test framework: **pytest**. Place tests in `tests/` mirroring the source layout.
+Test files start with `test_<module>.py`.
+
+```python
+# tests/test_example.py
+import pytest
+from mymodule import my_function
+
+def test_happy_path():
+    assert my_function("input") == "expected"
+
+def test_raises_on_bad_input():
+    with pytest.raises(ValueError, match="must be positive"):
+        my_function(-1)
+
+@pytest.mark.parametrize("val,expected", [
+    ("a", 1),
+    ("ab", 2),
+    ("", 0),
+])
+def test_parametrized(val, expected):
+    assert len(val) == expected
+```
+
+Run tests:
+```bash
+uv run python -m pytest -v
+# With coverage:
+uv run python -m pytest --cov=src --cov-report=term-missing
+```
+
+---
+
+## Debugging Tips
+
+```bash
+# Run with verbose traceback
+python -m traceback script.py
+
+# Quick REPL inspection
+python -c "import module; print(dir(module))"
+
+# Profile a script
+python -m cProfile -s cumulative script.py | head -20
+```

braindump_ai-0.1.0/.claude/skills/python-dev/python_template.md

@@ -0,0 +1,24 @@
+# Python Template File
+
+The line width is 120 characters.
+The file layout shall correspond to:
+
+```python
+<License Header>
+<Includes>
+
+#######################################################################################################################
+# Public Interface                                                                                                    #
+#######################################################################################################################
+
+<Public Interface>
+  <Public Constants>
+  <Public Functions>
+
+#######################################################################################################################
+# Implementation                                                                                                      #
+#######################################################################################################################
+
+<Implementation>
+  <Private Constants>
+  <Private Functions>

braindump_ai-0.1.0/.claude/skills/react-dev/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: react-dev
+description: >
+    Activate this skill for any task involving writing React/TypeScript source code
+    in the frontend/ directory.
+
+    This includes:
+      - adding new components
+      - fixing bugs
+      - adding types
+      - updating styles
+      - writing or updating tests
+      - reviewing frontend code
+---
+
+# React Development Skill
+
+## Core Principles
+
+1. **TypeScript only** — no `.js` or `.jsx` files; every file is `.ts` or `.tsx`.
+2. **Strict mode** — `tsconfig.json` enables `"strict": true`; never use `any` unless absolutely unavoidable and always add a comment explaining why.
+3. **Functional components only** — no class components; use hooks for all state and side-effects.
+4. **Co-locate styles** — every component has a matching `.css` file; no inline `style={{}}` except for dynamic values that cannot be expressed in CSS.
+5. **Fail visibly** — surface errors through `useErrorToast()` so users always see what went wrong.
+
+---
+
+## General Coding Guidelines
+
+Before finalising any frontend output, verify:
+
+- [ ] **File extension** — `.ts` for pure logic, `.tsx` for JSX-containing files
+- [ ] **No JS files** — `eslint.config.js` is the only `.js` file and is tooling config, not app code
+- [ ] **Named exports** — prefer named exports for components; default export only for the component itself (required by react-refresh)
+- [ ] **Typed props** — every component has an explicit `interface Props { … }` or inline type
+- [ ] **No `any`** — use `unknown` + narrowing, generics, or precise union types instead
+- [ ] **Hook rules** — hooks called unconditionally at the top of the component; never inside loops, conditions, or nested functions
+- [ ] **Exhaustive deps** — `useEffect` / `useCallback` / `useMemo` dependency arrays are complete; add a comment if a dep is intentionally omitted
+- [ ] **Event handlers** — typed with `React.MouseEvent`, `React.ChangeEvent<HTMLInputElement>`, etc.
+- [ ] **Keys** — list renders use stable, unique keys (IDs, not array indices)
+- [ ] **Accessibility** — interactive elements have `aria-label` or visible label; icon-only buttons have `title` and `aria-label`
+- [ ] **CSS class naming** — kebab-case; scoped with a component prefix (e.g. `.query-bar`, `.query-input`)
+
+---
+
+## Project-Specific Guidelines
+
+- [ ] **API calls** — always go through `api.ts`; never call `fetch` directly in a component
+- [ ] **Error handling** — wrap async calls in `try/catch` and call `pushError()` from `useErrorToast()`
+- [ ] **Types** — shared domain types live in `types.ts`; API-response shapes live in `api.ts` alongside the call that returns them
+- [ ] **State lifting** — local state stays local; lift only when two or more siblings need it
+- [ ] **No prop drilling past two levels** — use React context (following the `ErrorToast` provider pattern) for cross-cutting concerns
+
+---
+
+## Patterns & Best Practices
+
+### Component structure
+
+```tsx
+// components/MyWidget.tsx
+import { useState, useCallback } from 'react'
+import { useErrorToast } from './ErrorToast'
+import './MyWidget.css'
+
+interface Props {
+  label: string
+  onConfirm: (value: string) => void
+}
+
+export default function MyWidget({ label, onConfirm }: Props) {
+  const { pushError } = useErrorToast()
+  const [value, setValue] = useState('')
+
+  const handleSubmit = useCallback(async () => {
+    try {
+      await someApiCall(value)
+      onConfirm(value)
+    } catch (err: unknown) {
+      pushError('Failed to submit', String(err))
+    }
+  }, [value, onConfirm])
+
+  return (
+    <div className="my-widget">
+      <label className="my-widget-label">{label}</label>
+      <input
+        className="my-widget-input"
+        value={value}
+        onChange={e => setValue(e.target.value)}
+        onKeyDown={e => e.key === 'Enter' && handleSubmit()}
+      />
+      <button className="my-widget-btn" onClick={handleSubmit}>
+        Confirm
+      </button>
+    </div>
+  )
+}
+```
+
+### Typing async state
+
+```tsx
+// Explicit loading / error / data pattern
+const [data, setData] = useState<Spike[] | null>(null)
+const [loading, setLoading] = useState(false)
+
+useEffect(() => {
+  let cancelled = false
+  setLoading(true)
+  fetchSpikes()
+    .then(spikes => { if (!cancelled) setData(spikes) })
+    .catch(err => pushError('Load failed', String(err)))
+    .finally(() => { if (!cancelled) setLoading(false) })
+  return () => { cancelled = true }
+}, [])
+```
+
+### Context provider pattern
+
+```tsx
+// Follow the ErrorToast pattern for cross-cutting concerns:
+// 1. Define the context value interface
+// 2. Create the context with a safe no-op default
+// 3. Export a custom hook `useFoo()`
+// 4. Export a `FooProvider` that wraps children
+
+interface FooContextValue { doSomething: () => void }
+const FooContext = createContext<FooContextValue>({ doSomething: () => {} })
+export function useFoo() { return useContext(FooContext) }
+export function FooProvider({ children }: { children: React.ReactNode }) { … }
+```
+
+### Adding an API call
+
+```ts
+// api.ts — add alongside the function that uses the new shape
+export interface MyNewResponse {
+  id: string
+  value: number
+}
+
+export async function fetchMyThing(id: string): Promise<MyNewResponse> {
+  return request<MyNewResponse>(`/my-thing/${id}`)
+}
+```
+
+---
+
+## Tooling
+
+| Tool | Purpose | Run |
+|------|---------|-----|
+| **Vite** | Dev server (port 5173) + production build | `npm run dev` / `npm run build` |
+| **TypeScript** | Type checking | `npx tsc --noEmit` |
+| **ESLint** | Linting (typescript-eslint + react-hooks + react-refresh) | `npm run lint` |
+
+The Vite dev server proxies `/api` → `http://localhost:8000` and `/api` websockets, so the backend must be running on port 8000 during development.
+
+Production assets are compiled into `frontend/dist/` and bundled into the wheel by `tools/hatch_build.py`.
+
+---
+
+## Debugging Tips
+
+```bash
+# Type-check without building
+npx tsc --noEmit
+
+# Lint the source
+npm run lint
+
+# Inspect the production bundle contents
+npx vite-bundle-visualizer   # or: unzip -l ../dist/*.whl | grep frontend
+```

braindump_ai-0.1.0/.github/workflows/pr.yml

@@ -0,0 +1,66 @@
+name: Pull Request
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  backend:
+    name: Backend
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check (ty)
+        run: uv run ty check src/
+
+      - name: Security scan (bandit)
+        run: uv run bandit -r src/ -c pyproject.toml
+
+      - name: Tests (pytest)
+        run: uv run pytest tests/
+
+  frontend:
+    name: Frontend
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Lint (eslint)
+        working-directory: frontend
+        run: npm run lint
+
+      - name: Type check & build (tsc + vite)
+        working-directory: frontend
+        run: npm run build

braindump_ai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write   # required for PyPI trusted publishing (OIDC)
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/braindump
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1