Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

v0.5.0: schema v6 — tier + content_type + raw_file

Jordan0c590e6addd4
diff --git a/pyproject.toml b/pyproject.toml
index bd397a6..8b45eb6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "hyperresearch"
-version = "0.4.0"
+version = "0.5.0"
description = "Agent-driven research knowledge base. Browse, collect, and synthesize web sources into a searchable wiki."
readme = "README.md"
license = "MIT"
diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.py
index 3a81bf5..91efa94 100644
--- a/src/hyperresearch/__init__.py
+++ b/src/hyperresearch/__init__.py
@@ -1,3 +1,3 @@
"""Hyperresearch — agent-driven research knowledge base."""
-__version__ = "0.4.0"
+__version__ = "0.5.0"
diff --git a/src/hyperresearch/core/db.py b/src/hyperresearch/core/db.py
index e387a29..037e165 100644
--- a/src/hyperresearch/core/db.py
+++ b/src/hyperresearch/core/db.py
@@ -5,7 +5,7 @@ from __future__ import annotations
import sqlite3
from pathlib import Path
-SCHEMA_VERSION = 5
+SCHEMA_VERSION = 6
SCHEMA_SQL = """
PRAGMA journal_mode=WAL;
@@ -24,6 +24,10 @@ CREATE TABLE IF NOT EXISTS notes (
CHECK (status IN ('draft','review','evergreen','stale','deprecated','archive')),
type TEXT NOT NULL DEFAULT 'note'
CHECK (type IN ('note','raw','index','moc')),
+ tier TEXT
+ CHECK (tier IS NULL OR tier IN ('ground_truth','institutional','practitioner','commentary','unknown')),
+ content_type TEXT
+ CHECK (content_type IS NULL OR content_type IN ('paper','docs','article','blog','forum','dataset','policy','code','book','transcript','review','unknown')),
source TEXT,
parent TEXT,
deprecated INTEGER NOT NULL DEFAULT 0,
@@ -136,6 +140,13 @@ CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
);
"""
+# Indexes on columns added by migrations — must run AFTER migrate() so that
+# existing DBs have had the columns added by ALTER TABLE before we index them.
+POST_MIGRATE_INDEXES_SQL = """
+CREATE INDEX IF NOT EXISTS idx_notes_tier ON notes(tier);
+CREATE INDEX IF NOT EXISTS idx_notes_content_type ON notes(content_type);
+"""
+
def get_connection(db_path: Path) -> sqlite3.Connection:
"""Open a SQLite connection with WAL mode and FK enforcement."""
@@ -157,6 +168,10 @@ def init_schema(conn: sqlite3.Connection) -> None:
)
conn.commit()
- # Run any pending migrations
+ # Run any pending migrations (may ALTER TABLE to add new columns)
from hyperresearch.core.migrations import migrate
migrate(conn, SCHEMA_VERSION)
+
+ # Indexes that depend on migration-added columns run last
+ conn.executescript(POST_MIGRATE_INDEXES_SQL)
+ conn.commit()
diff --git a/src/hyperresearch/core/migrations.py b/src/hyperresearch/core/migrations.py
index 0b65aca..da3ab01 100644
--- a/src/hyperresearch/core/migrations.py
+++ b/src/hyperresearch/core/migrations.py
@@ -3,10 +3,28 @@
from __future__ import annotations
import sqlite3
+from collections.abc import Callable
-# Each migration is a SQL script that upgrades from version N-1 to N.
+# Each migration upgrades from version N-1 to N. May be either:
+# - a SQL string (executed via executescript)
+# - a callable(conn) for migrations that need conditional logic (e.g. ADD COLUMN)
# Migrations MUST be idempotent (safe to re-run).
-MIGRATIONS: dict[int, str] = {
+
+
+def _migrate_v6_tier_content_type(conn: sqlite3.Connection) -> None:
+ """Add tier and content_type columns to notes (idempotent)."""
+ existing = {row[1] for row in conn.execute("PRAGMA table_info(notes)")}
+ if "tier" not in existing:
+ conn.execute("ALTER TABLE notes ADD COLUMN tier TEXT")
+ if "content_type" not in existing:
+ conn.execute("ALTER TABLE notes ADD COLUMN content_type TEXT")
+ conn.executescript("""
+ CREATE INDEX IF NOT EXISTS idx_notes_tier ON notes(tier);
+ CREATE INDEX IF NOT EXISTS idx_notes_content_type ON notes(content_type);
+ """)
+
+
+MIGRATIONS: dict[int, str | Callable[[sqlite3.Connection], None]] = {
2: """
CREATE TABLE IF NOT EXISTS tag_aliases (
alias TEXT PRIMARY KEY,
@@ -47,6 +65,7 @@ CREATE INDEX IF NOT EXISTS idx_assets_type ON assets(type);
-- removed from code. Left as vestigial columns in existing DBs for compatibility.
-- New vaults won't have them. No structural changes needed.
""",
+ 6: _migrate_v6_tier_content_type,
}
@@ -66,9 +85,12 @@ def migrate(conn: sqlite3.Connection, target_version: int) -> list[int]:
applied = []
for version in range(current + 1, target_version + 1):
- sql = MIGRATIONS.get(version)
- if sql:
- conn.executescript(sql)
+ migration = MIGRATIONS.get(version)
+ if migration:
+ if callable(migration):
+ migration(conn)
+ else:
+ conn.executescript(migration)
conn.execute(
"INSERT OR REPLACE INTO _meta (key, value) VALUES ('schema_version', ?)",
(str(version),),
diff --git a/src/hyperresearch/models/note.py b/src/hyperresearch/models/note.py
index e9e8cbe..f2a7770 100644
--- a/src/hyperresearch/models/note.py
+++ b/src/hyperresearch/models/note.py
@@ -25,6 +25,31 @@ class NoteType(StrEnum):
MOC = "moc"
+class Tier(StrEnum):
+ """Epistemic role of a source — how it functions as evidence."""
+ GROUND_TRUTH = "ground_truth"
+ INSTITUTIONAL = "institutional"
+ PRACTITIONER = "practitioner"
+ COMMENTARY = "commentary"
+ UNKNOWN = "unknown"
+
+
+class ContentType(StrEnum):
+ """Artifact kind — what the note physically is."""
+ PAPER = "paper"
+ DOCS = "docs"
+ ARTICLE = "article"
+ BLOG = "blog"
+ FORUM = "forum"
+ DATASET = "dataset"
+ POLICY = "policy"
+ CODE = "code"
+ BOOK = "book"
+ TRANSCRIPT = "transcript"
+ REVIEW = "review"
+ UNKNOWN = "unknown"
+
+
def slugify(text: str) -> str:
"""Convert text to a URL-friendly slug. Preserves underscores."""
text = text.lower().strip()
@@ -56,12 +81,15 @@ class NoteMeta(BaseModel):
fetch_provider: str | None = None
status: NoteStatus = NoteStatus.DRAFT
type: NoteType = NoteType.NOTE
+ tier: Tier | None = None # Epistemic role (ground_truth/institutional/practitioner/commentary)
+ content_type: ContentType | None = None # Artifact kind (paper/docs/article/blog/...)
aliases: list[str] = Field(default_factory=list)
parent: str | None = None
deprecated: bool = False # Explicitly marked as outdated
reviewed: datetime | None = None # Last time a human verified accuracy
expires: datetime | None = None # Auto-stale after this date
summary: str | None = None
+ raw_file: str | None = None # Relative path to raw artifact (e.g. raw/<id>.pdf)
@field_validator("tags", mode="before")
@classmethod