neuroscore 0.1.0__tar.gz

neuroscore-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+.ruff_cache/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.env.local
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+*.tsbuildinfo
+
+# Turbo
+.turbo/
+
+# pnpm
+pnpm-debug.log*
+
+# SQLite
+*.db
+*.sqlite
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build outputs
+packages/*/dist/
+apps/*/dist/
+
+# Test
+.coverage
+htmlcov/
+.pytest_cache/
+
+# NeuroScore local data
+.neuroscore/

neuroscore-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: neuroscore
+Version: 0.1.0
+Summary: Cognitive scoring engine for developer artifacts
+Project-URL: Homepage, https://github.com/hoklims/neuroscore
+Project-URL: Documentation, https://github.com/hoklims/neuroscore/tree/main/docs
+Project-URL: Repository, https://github.com/hoklims/neuroscore
+Project-URL: Issues, https://github.com/hoklims/neuroscore/issues
+Author: NeuroScore Contributors
+License-Expression: MIT
+Keywords: cognitive,documentation,prompts,quality,scoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2.10
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: embedding
+Requires-Dist: numpy<3,>=1.26; extra == 'embedding'
+Requires-Dist: scikit-learn<2,>=1.5; extra == 'embedding'
+Description-Content-Type: text/plain
+
+Cognitive scoring engine for developer artifacts. See https://github.com/hoklims/neuroscore

neuroscore-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "neuroscore"
+version = "0.1.0"
+description = "Cognitive scoring engine for developer artifacts"
+requires-python = ">=3.12"
+license = "MIT"
+readme = {text = "Cognitive scoring engine for developer artifacts. See https://github.com/hoklims/neuroscore", content-type = "text/plain"}
+authors = [{ name = "NeuroScore Contributors" }]
+keywords = ["scoring", "cognitive", "prompts", "documentation", "quality"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.10,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoklims/neuroscore"
+Documentation = "https://github.com/hoklims/neuroscore/tree/main/docs"
+Repository = "https://github.com/hoklims/neuroscore"
+Issues = "https://github.com/hoklims/neuroscore/issues"
+
+[project.optional-dependencies]
+embedding = [
+  "scikit-learn>=1.5,<2",
+  "numpy>=1.26,<3",
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=6.0",
+  "ruff>=0.9",
+  "pyright>=1.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/neuroscore"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

neuroscore-0.1.0/src/neuroscore/__init__.py

@@ -0,0 +1,30 @@
+"""NeuroScore — Cognitive scoring engine for developer artifacts."""
+
+from neuroscore.models import (
+    Artifact,
+    ArtifactType,
+    ComparisonRun,
+    ConfidenceEstimate,
+    EvidenceSpan,
+    ScoreDimension,
+    ScoreRun,
+    Suggestion,
+)
+from neuroscore.persistence import PersistenceError
+from neuroscore.pipeline import compare_artifacts, score_artifact
+
+__all__ = [
+    "Artifact",
+    "ArtifactType",
+    "ComparisonRun",
+    "ConfidenceEstimate",
+    "EvidenceSpan",
+    "PersistenceError",
+    "ScoreDimension",
+    "ScoreRun",
+    "Suggestion",
+    "compare_artifacts",
+    "score_artifact",
+]
+
+__version__ = "0.1.0"

neuroscore-0.1.0/src/neuroscore/config.py

@@ -0,0 +1,84 @@
+"""Configuration management for NeuroScore.
+
+All configuration is driven by environment variables with sensible defaults.
+No config files — keep it simple and 12-factor compliant.
+
+Environment variables:
+    NEUROSCORE_DB_PATH      — SQLite database path (default: ~/.neuroscore/runs.db)
+    NEUROSCORE_DB_ENABLED   — Enable persistence (default: true)
+    NEUROSCORE_PROVIDER     — Default scoring provider (default: rules_baseline)
+    NEUROSCORE_API_PORT     — API server port (default: 8420)
+    NEUROSCORE_API_HOST     — API server host (default: 127.0.0.1)
+    NEUROSCORE_LOG_LEVEL    — Logging level (default: WARNING)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from neuroscore.types import ProviderName
+
+_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+_FALSE_VALUES = frozenset({"0", "false", "no", "off"})
+
+
+def _env_bool(key: str, default: bool) -> bool:
+    val = os.environ.get(key, "").lower()
+    if val in _TRUE_VALUES:
+        return True
+    if val in _FALSE_VALUES:
+        return False
+    return default
+
+
+@dataclass(frozen=True)
+class NeuroScoreConfig:
+    """Immutable configuration snapshot."""
+
+    db_path: Path
+    db_enabled: bool
+    default_provider: ProviderName
+    api_port: int
+    api_host: str
+    log_level: str
+
+    @staticmethod
+    def from_env() -> NeuroScoreConfig:
+        """Build configuration from environment variables."""
+        db_path_str = os.environ.get("NEUROSCORE_DB_PATH")
+        db_path = Path(db_path_str) if db_path_str else Path.home() / ".neuroscore" / "runs.db"
+
+        provider_str = os.environ.get("NEUROSCORE_PROVIDER", "rules_baseline")
+        try:
+            provider = ProviderName(provider_str)
+        except ValueError:
+            provider = ProviderName.RULES_BASELINE
+
+        return NeuroScoreConfig(
+            db_path=db_path,
+            db_enabled=_env_bool("NEUROSCORE_DB_ENABLED", default=True),
+            default_provider=provider,
+            api_port=int(os.environ.get("NEUROSCORE_API_PORT", "8420")),
+            api_host=os.environ.get("NEUROSCORE_API_HOST", "127.0.0.1"),
+            log_level=os.environ.get("NEUROSCORE_LOG_LEVEL", "WARNING").upper(),
+        )
+
+
+# Module-level singleton — loaded once, immutable
+_config: NeuroScoreConfig | None = None
+
+
+def get_config() -> NeuroScoreConfig:
+    """Get the current configuration (lazy-loaded from environment)."""
+    global _config
+    if _config is None:
+        _config = NeuroScoreConfig.from_env()
+    return _config
+
+
+def reset_config() -> None:
+    """Reset config cache. Useful for testing."""
+    global _config
+    _config = None

neuroscore-0.1.0/src/neuroscore/detection.py

@@ -0,0 +1,56 @@
+"""Artifact type detection heuristics."""
+
+from __future__ import annotations
+
+import re
+
+from neuroscore.types import ArtifactType
+
+# File extension → type mapping
+_EXTENSION_MAP: dict[str, ArtifactType] = {
+    ".md": ArtifactType.MARKDOWN,
+    ".markdown": ArtifactType.MARKDOWN,
+    ".py": ArtifactType.CODE,
+    ".js": ArtifactType.CODE,
+    ".ts": ArtifactType.CODE,
+    ".tsx": ArtifactType.CODE,
+    ".jsx": ArtifactType.CODE,
+    ".rs": ArtifactType.CODE,
+    ".go": ArtifactType.CODE,
+    ".java": ArtifactType.CODE,
+    ".c": ArtifactType.CODE,
+    ".cpp": ArtifactType.CODE,
+    ".h": ArtifactType.CODE,
+    ".rb": ArtifactType.CODE,
+    ".sh": ArtifactType.CODE,
+    ".diff": ArtifactType.DIFF,
+    ".patch": ArtifactType.DIFF,
+    ".txt": ArtifactType.PLAINTEXT,
+}
+
+# Content-based heuristics (checked in order)
+_DIFF_PATTERN = re.compile(r"^(diff --git|---|\+\+\+|@@)", re.MULTILINE)
+_MARKDOWN_PATTERN = re.compile(r"^#{1,6}\s|\*\*|__|\[.+\]\(.+\)|```", re.MULTILINE)
+_CODE_INDICATORS = re.compile(
+    r"(def |class |function |const |let |var |import |from |#include|package )", re.MULTILINE
+)
+
+
+def detect_artifact_type(content: str, filename: str | None = None) -> ArtifactType:
+    """Detect artifact type from filename extension or content heuristics."""
+    if filename:
+        for ext, artifact_type in _EXTENSION_MAP.items():
+            if filename.endswith(ext):
+                return artifact_type
+
+    # Content-based detection
+    if _DIFF_PATTERN.search(content):
+        return ArtifactType.DIFF
+
+    if _MARKDOWN_PATTERN.search(content):
+        return ArtifactType.MARKDOWN
+
+    if _CODE_INDICATORS.search(content):
+        return ArtifactType.CODE
+
+    return ArtifactType.PLAINTEXT

neuroscore-0.1.0/src/neuroscore/features.py

@@ -0,0 +1,220 @@
+"""Text feature extraction for scoring pipeline."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TextFeatures:
+    """Extracted text features used by scoring providers."""
+
+    char_count: int
+    word_count: int
+    line_count: int
+    sentence_count: int
+    avg_word_length: float
+    avg_sentence_length: float
+    avg_line_length: float
+    vocabulary_richness: float  # unique words / total words
+    question_count: int
+    exclamation_count: int
+    imperative_ratio: float  # estimated ratio of imperative sentences
+    list_item_count: int
+    heading_count: int
+    code_block_count: int
+    link_count: int
+    paragraph_count: int
+    max_nesting_depth: int
+    whitespace_ratio: float
+    uppercase_ratio: float
+    punctuation_density: float
+    repeated_phrase_count: int
+    long_sentence_count: int  # sentences > 30 words
+    short_sentence_count: int  # sentences < 5 words
+    passive_voice_estimate: int
+    hedge_word_count: int
+
+
+_SENTENCE_SPLIT = re.compile(r"[.!?]+\s+|[.!?]+$|\n\n+")
+_WORD_SPLIT = re.compile(r"\s+")
+_HEDGE_WORDS = frozenset(
+    {
+        "maybe",
+        "perhaps",
+        "possibly",
+        "somewhat",
+        "relatively",
+        "fairly",
+        "might",
+        "could",
+        "would",
+        "should",
+        "seem",
+        "seems",
+        "appeared",
+        "apparently",
+        "arguably",
+        "roughly",
+        "approximately",
+        "basically",
+        "generally",
+        "usually",
+        "often",
+        "sometimes",
+        "probably",
+    }
+)
+_PASSIVE_PATTERN = re.compile(r"\b(is|are|was|were|been|being|be)\s+\w+ed\b", re.IGNORECASE)
+_IMPERATIVE_STARTS = frozenset(
+    {
+        "do",
+        "don't",
+        "use",
+        "add",
+        "remove",
+        "create",
+        "delete",
+        "run",
+        "make",
+        "set",
+        "get",
+        "put",
+        "check",
+        "ensure",
+        "verify",
+        "note",
+        "see",
+        "try",
+        "avoid",
+        "keep",
+        "write",
+        "read",
+        "install",
+        "update",
+        "configure",
+        "implement",
+        "define",
+        "return",
+        "pass",
+        "call",
+    }
+)
+_LIST_ITEM = re.compile(r"^\s*[-*+•]\s|^\s*\d+[.)]\s", re.MULTILINE)
+_HEADING = re.compile(r"^#{1,6}\s", re.MULTILINE)
+_CODE_BLOCK = re.compile(r"```[\s\S]*?```|~~~[\s\S]*?~~~")
+_LINK = re.compile(r"\[.+?\]\(.+?\)|https?://\S+")
+_REPEATED_PHRASE_MIN_WORDS = 3
+
+
+def extract_features(content: str) -> TextFeatures:
+    """Extract text features from artifact content."""
+    lines = content.split("\n")
+    words = _WORD_SPLIT.split(content.strip())
+    words = [w for w in words if w]
+    sentences = [s.strip() for s in _SENTENCE_SPLIT.split(content) if s.strip()]
+
+    char_count = len(content)
+    word_count = len(words)
+    line_count = len(lines)
+    sentence_count = max(len(sentences), 1)
+
+    avg_word_length = sum(len(w) for w in words) / word_count if word_count > 0 else 0.0
+    avg_sentence_length = word_count / sentence_count if sentence_count > 0 else 0.0
+    avg_line_length = char_count / line_count if line_count > 0 else 0.0
+
+    unique_words = set(w.lower() for w in words)
+    vocabulary_richness = len(unique_words) / word_count if word_count > 0 else 0.0
+
+    lower_words = [w.lower() for w in words]
+    hedge_word_count = sum(1 for w in lower_words if w in _HEDGE_WORDS)
+
+    question_count = content.count("?")
+    exclamation_count = content.count("!")
+
+    # Estimate imperative sentences
+    imperative_count = 0
+    for sent in sentences:
+        first_word = sent.split()[0].lower().rstrip(".,!?:") if sent.split() else ""
+        if first_word in _IMPERATIVE_STARTS:
+            imperative_count += 1
+    imperative_ratio = imperative_count / sentence_count if sentence_count > 0 else 0.0
+
+    list_item_count = len(_LIST_ITEM.findall(content))
+    heading_count = len(_HEADING.findall(content))
+    code_block_count = len(_CODE_BLOCK.findall(content))
+    link_count = len(_LINK.findall(content))
+
+    paragraphs = re.split(r"\n\s*\n", content)
+    paragraph_count = len([p for p in paragraphs if p.strip()])
+
+    # Estimate nesting depth from indentation
+    max_nesting = 0
+    for line in lines:
+        stripped = line.lstrip()
+        if stripped:
+            indent = len(line) - len(stripped)
+            depth = indent // 2  # assume 2-space indent
+            max_nesting = max(max_nesting, depth)
+
+    whitespace_ratio = (
+        sum(1 for c in content if c.isspace()) / char_count if char_count > 0 else 0.0
+    )
+    uppercase_ratio = sum(1 for c in content if c.isupper()) / char_count if char_count > 0 else 0.0
+    punct_chars = sum(1 for c in content if c in ".,;:!?()[]{}\"'-/\\@#$%^&*")
+    punctuation_density = punct_chars / char_count if char_count > 0 else 0.0
+
+    # Detect repeated phrases (3+ words, appearing 2+ times)
+    repeated = _count_repeated_phrases(lower_words)
+
+    # Sentence length distribution
+    long_sentences = 0
+    short_sentences = 0
+    for sent in sentences:
+        wc = len(sent.split())
+        if wc > 30:
+            long_sentences += 1
+        elif wc < 5:
+            short_sentences += 1
+
+    passive_count = len(_PASSIVE_PATTERN.findall(content))
+
+    return TextFeatures(
+        char_count=char_count,
+        word_count=word_count,
+        line_count=line_count,
+        sentence_count=sentence_count,
+        avg_word_length=avg_word_length,
+        avg_sentence_length=avg_sentence_length,
+        avg_line_length=avg_line_length,
+        vocabulary_richness=vocabulary_richness,
+        question_count=question_count,
+        exclamation_count=exclamation_count,
+        imperative_ratio=imperative_ratio,
+        list_item_count=list_item_count,
+        heading_count=heading_count,
+        code_block_count=code_block_count,
+        link_count=link_count,
+        paragraph_count=paragraph_count,
+        max_nesting_depth=max_nesting,
+        whitespace_ratio=whitespace_ratio,
+        uppercase_ratio=uppercase_ratio,
+        punctuation_density=punctuation_density,
+        repeated_phrase_count=repeated,
+        long_sentence_count=long_sentences,
+        short_sentence_count=short_sentences,
+        passive_voice_estimate=passive_count,
+        hedge_word_count=hedge_word_count,
+    )
+
+
+def _count_repeated_phrases(words: list[str], min_words: int = 3) -> int:
+    """Count n-gram phrases that appear more than once."""
+    if len(words) < min_words * 2:
+        return 0
+    phrases: dict[tuple[str, ...], int] = {}
+    for i in range(len(words) - min_words + 1):
+        phrase = tuple(words[i : i + min_words])
+        phrases[phrase] = phrases.get(phrase, 0) + 1
+    return sum(1 for count in phrases.values() if count > 1)

neuroscore-0.1.0/src/neuroscore/models.py

@@ -0,0 +1,100 @@
+"""Domain models for NeuroScore."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from neuroscore.types import ArtifactType, DimensionName, ProviderName
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex
+
+
+# Bumped on breaking changes to the output schema.
+# Consumers should check this before parsing.
+SCHEMA_VERSION = "0.1.0"
+
+
+class Artifact(BaseModel):
+    """An input artifact to be scored."""
+
+    content: str
+    artifact_type: ArtifactType | None = None
+    filename: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ConfidenceEstimate(BaseModel):
+    """Confidence level for a score, with method attribution."""
+
+    value: float = Field(ge=0.0, le=1.0, description="Confidence level 0-1")
+    method: str = Field(description="How confidence was estimated")
+
+
+class EvidenceSpan(BaseModel):
+    """A text range supporting a score."""
+
+    start: int = Field(ge=0, description="Start byte offset in artifact content")
+    end: int = Field(ge=0, description="End byte offset in artifact content")
+    text: str = Field(description="The matched text content")
+    explanation: str = Field(description="Why this span is relevant")
+    dimension: DimensionName = Field(description="Which dimension this evidence supports")
+
+
+class Suggestion(BaseModel):
+    """A rewrite suggestion for improving the artifact."""
+
+    start: int = Field(ge=0)
+    end: int = Field(ge=0)
+    original: str
+    replacement: str
+    rationale: str
+    dimension: DimensionName
+
+
+class ScoreDimension(BaseModel):
+    """A single scoring dimension result."""
+
+    name: DimensionName
+    value: float = Field(ge=0.0, le=1.0, description="Normalized score 0-1")
+    confidence: ConfidenceEstimate
+    explanation: str
+    evidence: list[EvidenceSpan] = Field(default_factory=list)
+
+
+class ScoreRun(BaseModel):
+    """A complete scoring execution result."""
+
+    schema_version: str = Field(default=SCHEMA_VERSION, description="Output schema version")
+    id: str = Field(default_factory=_new_id)
+    artifact: Artifact
+    artifact_type_resolved: ArtifactType
+    provider: ProviderName
+    overall_score: float = Field(ge=0.0, le=1.0)
+    dimensions: list[ScoreDimension]
+    suggestions: list[Suggestion] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=_utc_now)
+    duration_ms: float = Field(ge=0.0, description="Scoring duration in milliseconds")
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ComparisonRun(BaseModel):
+    """A/B comparison of two scored artifacts."""
+
+    schema_version: str = Field(default=SCHEMA_VERSION, description="Output schema version")
+    id: str = Field(default_factory=_new_id)
+    run_a: ScoreRun
+    run_b: ScoreRun
+    delta_overall: float = Field(description="Score B - Score A")
+    dimension_deltas: dict[DimensionName, float] = Field(default_factory=dict)
+    winner: str = Field(description="'a', 'b', or 'tie'")
+    created_at: datetime = Field(default_factory=_utc_now)