@monoes/monomindcli 2.15.3 → 2.15.5

package/org-skills/experimental-design/references/randomization_and_blocking.md

@@ -0,0 +1,116 @@
+# Randomization, Blocking, Stratification, and Controls
+
+These are the tools of *local control*: removing or balancing nuisance variation so
+the comparison you care about is clean. Randomization handles the unknown
+confounders; blocking and stratification handle the known ones; controls and
+blinding handle the systematic biases.
+
+## Randomization — why and how
+
+Randomization assigns treatments to units by chance, so that in expectation every
+confounder (measured or not, known or unknown) is balanced across arms. This is the
+foundation of causal inference: without it, an observed difference could always be
+due to some variable that happened to track the grouping.
+
+Use a **seeded, reproducible** schedule (see `scripts/randomization.py`) and follow
+it exactly. Record the seed. "I randomized somehow" is neither auditable nor
+reproducible.
+
+### Methods (and when each is right)
+
+| Method | What it does | Use when |
+|--------|--------------|----------|
+| **Simple** | Independent random assignment per unit | n is large (≳100); simplicity matters; imbalance is tolerable |
+| **Permuted block** | Within each block, arms appear in fixed ratio; order shuffled | You need balance throughout enrollment, or n is small/moderate, or intake is sequential |
+| **Stratified block** | Separate blocks within each level of a prognostic factor | A known covariate (site, sex, stage) must be balanced across arms |
+| **Cluster** | Whole groups (clinics, classes) assigned to arms | The intervention is delivered at a group level |
+| **Minimization** | Adaptively assign to minimize imbalance across several covariates | Many prognostic factors and small n (specialized; not in the script) |
+
+**Simple randomization caveat:** with small n it behaves like flipping a few coins —
+you can easily get 12 vs. 8 instead of 10 vs. 10, and worse for subgroups. Blocking
+fixes this.
+
+**Block size:** must be a multiple of the ratio unit (e.g. for 1:1, sizes 2, 4, 6).
+Smaller blocks balance more tightly but are more predictable in unblinded trials
+(a clinician who knows the block size can guess the last allocation). Vary block
+size or keep it concealed when predictability is a concern.
+
+## Blocking — removing known nuisance variation
+
+A **block** is a group of units expected to be similar (same day, batch, litter,
+plate, instrument run). You randomize treatments *within* each block. The nuisance
+variation between blocks is then removed from the error term, so the treatment
+comparison is more precise — often dramatically so.
+
+Block on anything that (a) you can identify before the experiment and (b) you
+expect to affect the response but isn't of interest itself:
+- **Time:** day, week, session, processing batch.
+- **Space:** plate, plate position/edge, shelf, cage rack, field plot.
+- **Material:** reagent lot, animal litter, cell passage, donor.
+- **People/instruments:** technician, machine, sequencing run.
+
+Rule of thumb: *"Block what you can, randomize what you cannot."* If you suspect a
+factor matters but can't block it, at least randomize across it and record it as a
+covariate.
+
+**Randomized complete block design (RCBD):** every treatment appears once in every
+block. This is the workhorse design — analyze with treatment + block in the model.
+
+## Stratification vs. blocking vs. covariate adjustment
+
+These overlap; the distinction is about *when* you control the variable:
+- **Stratify / block at design time** when the factor is known before assignment and
+  you want guaranteed balance (the safest, since it doesn't rely on a model).
+- **Adjust as a covariate at analysis time** (ANCOVA, regression) when the factor is
+  continuous or measured after assignment. Often you do both: stratify on the big
+  ones, adjust for the rest.
+
+A few strata are better than many: stratifying on too many factors at once leaves
+strata with too few units to block effectively. For many covariates and small n,
+minimization is the alternative.
+
+## Controls
+
+A comparison needs a concurrent baseline. Match the control to the threat you're
+ruling out:
+- **Untreated / standard-of-care control** — isolates the treatment effect from time.
+- **Vehicle / sham control** — isolates the active ingredient from the delivery
+  (injection stress, vehicle solvent, sham surgery).
+- **Positive control** — a treatment known to produce the effect, to confirm the
+  assay can detect one at all.
+- **Concurrent, not historical** — controls run at the same time as the treatment;
+  historical controls reintroduce time confounding.
+
+## Blinding
+
+Blinding prevents expectation from biasing measurement and behavior:
+- **Single-blind:** the subject doesn't know the assignment.
+- **Double-blind:** neither subject nor experimenter/assessor knows.
+- **Blinded outcome assessment:** at minimum, whoever measures the outcome shouldn't
+  know the group — cheap and high-value even in animal/bench work.
+Allocation concealment (the person enrolling can't foresee the next assignment) is
+distinct from blinding and just as important; a sealed seeded schedule provides it.
+
+## Batch effects and plate layout (especially omics / HTS)
+
+Batch effects are systematic technical differences between processing groups and are
+a leading cause of irreproducible high-throughput results.
+- **Never let batch align with the biological condition.** If all cases are in batch
+  1 and all controls in batch 2, condition and batch are perfectly confounded and
+  no normalization can separate them.
+- **Randomize or block sample-to-batch and position-within-plate.** Spread each
+  condition across all batches and across plate positions.
+- **Avoid edge effects:** evaporation and thermal gradients make outer wells differ;
+  don't load all controls into edge columns. Randomize positions, or include
+  replicates spanning edge and interior.
+- **Include anchor/reference samples** in every batch to estimate and correct batch
+  shifts.
+- Use `assign_factorial_runs()` / the randomization functions to generate a
+  randomized processing order and position map.
+
+## Documentation
+
+Record, and ideally pre-register: the randomization method, the seed, block sizes,
+stratification factors, the schedule itself, and the planned analysis (which must
+include block/stratum/cluster terms). This is what makes the study auditable and the
+primary analysis confirmatory rather than exploratory.

package/org-skills/experimental-design/references/sequential_and_adaptive.md

@@ -0,0 +1,97 @@
+# Sequential and Adaptive Designs
+
+A fixed design commits to a single sample size and one analysis at the end.
+**Sequential** and **adaptive** designs allow looks at the data *during* the study and
+let you stop early (for benefit, harm, or futility) or modify the design — saving
+participants, time, and money. The catch: every interim look at the data is another
+chance to cross the significance threshold by luck, so the error rate must be
+controlled explicitly. Peeking at accumulating data and stopping the first time
+p < 0.05 inflates the Type I error rate badly (to ~0.20+ with a few looks) — this is
+the core problem these methods solve.
+
+## Why naive peeking fails
+
+If you test at α = 0.05 at each of K interim analyses and stop at the first
+significant result, the *overall* false-positive rate is far above 0.05 — roughly
+0.08 for 2 looks, ~0.14 for 5, ~0.20 for 10. The fix is to spend your total α across
+the looks so the *cumulative* Type I error stays at 0.05.
+
+## Group-sequential designs
+
+Pre-plan a fixed number of interim analyses (e.g. after 25%, 50%, 75%, 100% of data)
+and use **adjusted, more stringent boundaries** at each look so the overall α is
+preserved. Common boundary families:
+
+- **Pocock:** constant (equally stringent) nominal significance level at every look.
+  Easier to stop early, but pays a larger penalty at the final analysis.
+- **O'Brien–Fleming:** very stringent early (hard to stop in the first looks), relaxing
+  toward the planned final α. Most popular in confirmatory trials because the final
+  boundary is close to the unadjusted 0.05 and early stopping is reserved for dramatic
+  effects.
+- **Alpha-spending functions (Lan–DeMets):** generalize the above by defining how much
+  α is "spent" as a function of information accrued, so the number and timing of looks
+  need not be fixed in advance — only the spending function is.
+
+You can stop for:
+- **Efficacy** — the effect crosses the upper boundary.
+- **Futility** — the effect is so small that continuing is unlikely to ever reach
+  significance (a non-binding or binding lower boundary / conditional power threshold).
+- **Harm** — safety boundary crossed.
+
+Group-sequential designs require a modestly larger maximum sample size than a fixed
+design (to pay for the looks), but the *expected* sample size is usually smaller
+because many trials stop early.
+
+### Tooling
+
+Python support is thinner than for fixed designs; common options:
+- **statsmodels** has limited sequential utilities; for full boundary computation,
+  most practitioners call R packages via `rpy2` or a subprocess:
+  - R `gsDesign` — the standard for group-sequential boundaries and spending functions.
+  - R `rpact` — confirmatory adaptive and group-sequential designs.
+- For custom rules, **simulate** the whole sequential procedure (generate data, apply
+  the boundaries look by look, repeat) to confirm the realized Type I error and to
+  estimate expected sample size and power. This mirrors the simulation approach in the
+  **statistical-power** skill and is the most flexible route.
+
+## Adaptive designs
+
+Broader than group-sequential: the design itself can change at an interim based on
+accumulating data, within a pre-specified plan that still controls error. Main types:
+
+- **Sample-size re-estimation:** recompute the required n at an interim using the
+  observed nuisance parameter (e.g. the variance or control-arm rate), without
+  unblinding the treatment effect. Protects against a misjudged variance at planning.
+- **Adaptive randomization:** shift allocation probabilities toward the better-
+  performing arm as data accrue (response-adaptive), or to improve covariate balance.
+- **Drop-the-loser / arm selection:** start with several arms or doses and drop
+  inferior ones at interims (seamless phase II/III).
+- **Adaptive enrichment:** narrow enrollment to a subgroup that appears to benefit.
+
+Adaptive designs are powerful but easy to get wrong: any adaptation that uses the
+unblinded treatment effect can inflate Type I error and bias the final effect estimate
+unless the method explicitly corrects for it. Two non-negotiables:
+1. **Pre-specify** the adaptation rule and the error-control method before the study.
+2. **Validate by simulation** that the *entire* procedure preserves the Type I error
+   rate and yields acceptable power and unbiased-enough estimates.
+
+## When to use them
+
+- **Confirmatory trials, expensive or risky enrollment** — group-sequential with
+  O'Brien–Fleming boundaries to allow ethical early stopping.
+- **Uncertain nuisance parameters at planning** — blinded sample-size re-estimation.
+- **Many candidate doses/arms** — adaptive arm selection / seamless designs.
+- **Pure exploration / fixed cheap data** — usually not worth the overhead; a fixed
+  design is simpler and the analysis is unambiguous.
+
+## Practical checklist
+
+- Decide the **number and timing** of interim analyses (or the spending function).
+- Choose a **boundary family** matched to how eager you are to stop early.
+- Specify **futility** rules if you want to stop for lack of effect.
+- Inflate the **maximum** sample size to cover the looks; report the **expected**
+  sample size too.
+- Pre-register the full sequential/adaptive plan, including the stopping rules.
+- Have an independent **data monitoring committee** look at unblinded interims in
+  human trials, not the study team.
+- **Simulate** the design end to end to confirm error control before running it.

package/org-skills/fastapi-expert/LICENSE.txt

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

package/org-skills/fastapi-expert/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: fastapi-expert
+description: "Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke to create REST endpoints, define Pydantic models, implement authentication flows, set up async SQLAlchemy database operations, add JWT authentication, build WebSocket endpoints, or generate OpenAPI documentation."
+tags: ["engineering","backend"]
+tools: ["monograph_query","monograph_context"]
+license: MIT
+source: https://github.com/Jeffallan/claude-skills
+source_path: "skills/fastapi-expert"
+source_commit: 882ef55e377dbf9a4dbe496bb41ac6ccd0e555cf
+---
+# FastAPI Expert
+
+Deep expertise in async Python, Pydantic V2, and production-grade API development with FastAPI.
+
+## When to Use This Skill
+
+- Building REST APIs with FastAPI
+- Implementing Pydantic V2 validation schemas
+- Setting up async database operations
+- Implementing JWT authentication/authorization
+- Creating WebSocket endpoints
+- Optimizing API performance
+
+## Core Workflow
+
+1. **Analyze requirements** — Identify endpoints, data models, auth needs
+2. **Design schemas** — Create Pydantic V2 models for validation
+3. **Implement** — Write async endpoints with proper dependency injection
+4. **Secure** — Add authentication, authorization, rate limiting
+5. **Test** — Write async tests with pytest and httpx; run `pytest` after each endpoint group and verify OpenAPI docs at `/docs`
+
+> **Checkpoint after each step:** confirm schemas validate correctly, endpoints return expected HTTP status codes, and `/docs` reflects the intended API surface before proceeding.
+
+## Minimal Complete Example
+
+Schema + endpoint + dependency injection in one cohesive unit:
+
+```python
+# schemas.py
+from pydantic import BaseModel, EmailStr, field_validator, model_config
+
+class UserCreate(BaseModel):
+    model_config = model_config(str_strip_whitespace=True)
+
+    email: EmailStr
+    password: str
+    name: str | None = None
+
+    @field_validator("password")
+    @classmethod
+    def password_strength(cls, v: str) -> str:
+        if len(v) < 8:
+            raise ValueError("Password must be at least 8 characters")
+        return v
+
+class UserResponse(BaseModel):
+    model_config = model_config(from_attributes=True)
+
+    id: int
+    email: EmailStr
+    name: str | None = None
+```
+
+```python
+# routers/users.py
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from typing import Annotated
+
+from app.database import get_db
+from app.schemas import UserCreate, UserResponse
+from app import crud
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(payload: UserCreate, db: DbDep) -> UserResponse:
+    existing = await crud.get_user_by_email(db, payload.email)
+    if existing:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Email already registered")
+    return await crud.create_user(db, payload)
+```
+
+```python
+# crud.py
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.models import User
+from app.schemas import UserCreate
+from app.security import hash_password
+
+async def get_user_by_email(db: AsyncSession, email: str) -> User | None:
+    result = await db.execute(select(User).where(User.email == email))
+    return result.scalar_one_or_none()
+
+async def create_user(db: AsyncSession, payload: UserCreate) -> User:
+    user = User(email=payload.email, hashed_password=hash_password(payload.password), name=payload.name)
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    return user
+```
+
+## JWT Authentication Snippet
+
+```python
+# security.py
+from datetime import datetime, timedelta, timezone
+from jose import JWTError, jwt
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from typing import Annotated
+
+SECRET_KEY = "read-from-env"  # use os.environ / settings
+ALGORITHM = "HS256"
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")
+
+def create_access_token(subject: str, expires_delta: timedelta = timedelta(minutes=30)) -> str:
+    payload = {"sub": subject, "exp": datetime.now(timezone.utc) + expires_delta}
+    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
+
+async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]) -> str:
+    try:
+        data = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        subject: str | None = data.get("sub")
+        if subject is None:
+            raise ValueError
+        return subject
+    except (JWTError, ValueError):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials")
+
+CurrentUser = Annotated[str, Depends(get_current_user)]
+```
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
+| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
+| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
+| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
+| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
+| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+
+## Constraints
+
+### MUST DO
+- Use type hints everywhere (FastAPI requires them)
+- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
+- Use `Annotated` pattern for dependency injection
+- Use async/await for all I/O operations
+- Use `X | None` instead of `Optional[X]`
+- Return proper HTTP status codes
+- Document endpoints (auto-generated OpenAPI)
+
+### MUST NOT DO
+- Use synchronous database operations
+- Skip Pydantic validation
+- Store passwords in plain text
+- Expose sensitive data in responses
+- Use Pydantic V1 syntax (`@validator`, `class Config`)
+- Mix sync and async code improperly
+- Hardcode configuration values
+
+## Output Templates
+
+When implementing FastAPI features, provide:
+1. Schema file (Pydantic models)
+2. Endpoint file (router with endpoints)
+3. CRUD operations if database involved
+4. Brief explanation of key decisions
+
+## Knowledge Reference
+
+FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger
+
+[Documentation](https://jeffallan.github.io/claude-skills/skills/backend/fastapi-expert/)

package/org-skills/fastapi-expert/references/async-sqlalchemy.md

@@ -0,0 +1,146 @@
+# Async SQLAlchemy
+
+## Engine & Session Setup
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_pre_ping=True,
+)
+
+async_session = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+class Base(DeclarativeBase):
+    pass
+```
+
+## Model Definition
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy import String, ForeignKey, DateTime, func
+from datetime import datetime
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    username: Mapped[str] = mapped_column(String(50), unique=True)
+    hashed_password: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+
+    # Relationships
+    posts: Mapped[list["Post"]] = relationship(back_populates="author", lazy="selectin")
+
+class Post(Base):
+    __tablename__ = "posts"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str] = mapped_column(String(200))
+    content: Mapped[str]
+    author_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+
+    author: Mapped["User"] = relationship(back_populates="posts")
+```
+
+## Database Dependency
+
+```python
+from typing import AsyncGenerator
+from fastapi import Depends
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+# Type alias for injection
+DB = Annotated[AsyncSession, Depends(get_db)]
+```
+
+## CRUD Operations
+
+```python
+from sqlalchemy import select, update, delete
+from sqlalchemy.orm import selectinload
+
+async def get_user(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(select(User).where(User.id == user_id))
+    return result.scalar_one_or_none()
+
+async def get_user_with_posts(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(
+        select(User)
+        .options(selectinload(User.posts))
+        .where(User.id == user_id)
+    )
+    return result.scalar_one_or_none()
+
+async def get_users(db: AsyncSession, skip: int = 0, limit: int = 100) -> list[User]:
+    result = await db.execute(select(User).offset(skip).limit(limit))
+    return list(result.scalars().all())
+
+async def create_user(db: AsyncSession, user_in: UserCreate) -> User:
+    user = User(**user_in.model_dump())
+    db.add(user)
+    await db.flush()
+    await db.refresh(user)
+    return user
+
+async def update_user(db: AsyncSession, user_id: int, user_in: UserUpdate) -> User:
+    await db.execute(
+        update(User)
+        .where(User.id == user_id)
+        .values(**user_in.model_dump(exclude_unset=True))
+    )
+    return await get_user(db, user_id)
+
+async def delete_user(db: AsyncSession, user_id: int) -> bool:
+    result = await db.execute(delete(User).where(User.id == user_id))
+    return result.rowcount > 0
+```
+
+## Lifespan Handler
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Shutdown
+    await engine.dispose()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Quick Reference
+
+| Operation | Method |
+|-----------|--------|
+| Select one | `result.scalar_one_or_none()` |
+| Select many | `result.scalars().all()` |
+| Eager load | `.options(selectinload(...))` |
+| Create | `db.add(obj)` + `await db.flush()` |
+| Update | `update(Model).where(...).values(...)` |
+| Delete | `delete(Model).where(...)` |
+| Commit | `await db.commit()` |
+| Rollback | `await db.rollback()` |