ldaca-web-app 0.1.0__tar.gz

ldaca_web_app-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+
+.venv/
+/build/
+dist/

ldaca_web_app-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: ldaca-web-app
+Version: 0.1.0
+Summary: LDaCA Web App - FastAPI backend with bundled production frontend for the Language Data Commons of Australia
+Author: Australian Text Analytics Platform
+License: MIT
+Keywords: corpus,fastapi,ldaca,linguistics,text-analytics,web-app
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.14
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: bertopic>=0.17.3
+Requires-Dist: docworkspace>=0.2.1
+Requires-Dist: fastapi-users[sqlalchemy]>=14.0.1
+Requires-Dist: fastapi[standard]>=0.135.0
+Requires-Dist: fastexcel>=0.18.0
+Requires-Dist: google-auth-oauthlib>=1.2.2
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: ldaca-loader
+Requires-Dist: openai>=2.26.0
+Requires-Dist: psutil>=6.1.0
+Requires-Dist: pyairtable>=3.3.0
+Requires-Dist: pyarrow>=16.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: tbb>=2022.3.1; sys_platform != 'darwin'
+Provides-Extra: deploy
+Requires-Dist: ipython>=9.5.0; extra == 'deploy'
+Requires-Dist: jupyter-server-proxy>=4.4.0; extra == 'deploy'
+Description-Content-Type: text/markdown
+
+# LDaCA Web App
+
+All-in-one Python package for the LDaCA platform: a FastAPI backend with a bundled production React frontend. Install once, run with a single command.
+
+## Quick start
+
+```bash
+# Install and run (backend + frontend on one port)
+uvx ldaca-web-app
+
+# Or run only the backend API
+uvx ldaca-web-app --backend
+
+# Custom port
+uvx ldaca-web-app --port 9000
+```
+
+## Start here
+
+- Full docs: `docs/index.md`
+- Run locally: `docs/user-guide/running-locally.md`
+- Configuration: `docs/reference/configuration.md`

ldaca_web_app-0.1.0/README.md

@@ -0,0 +1,22 @@
+# LDaCA Web App
+
+All-in-one Python package for the LDaCA platform: a FastAPI backend with a bundled production React frontend. Install once, run with a single command.
+
+## Quick start
+
+```bash
+# Install and run (backend + frontend on one port)
+uvx ldaca-web-app
+
+# Or run only the backend API
+uvx ldaca-web-app --backend
+
+# Custom port
+uvx ldaca-web-app --port 9000
+```
+
+## Start here
+
+- Full docs: `docs/index.md`
+- Run locally: `docs/user-guide/running-locally.md`
+- Configuration: `docs/reference/configuration.md`

ldaca_web_app-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "ldaca-web-app"
+version = "0.1.0"
+description = "LDaCA Web App - FastAPI backend with bundled production frontend for the Language Data Commons of Australia"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Australian Text Analytics Platform" }]
+keywords = [
+    "ldaca",
+    "text-analytics",
+    "corpus",
+    "linguistics",
+    "fastapi",
+    "web-app",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "aiosqlite>=0.21.0",
+    "bertopic>=0.17.3",
+    "fastapi-users[sqlalchemy]>=14.0.1",        # Includes fastapi, python-multipart, sqlalchemy
+    "fastapi[standard]>=0.135.0",               # Includes uvicorn, pydantic, starlette
+    "fastexcel>=0.18.0",
+    "google-auth-oauthlib>=1.2.2",              # Includes google-auth
+    "httpx>=0.27.0",
+    "pydantic-settings>=2.0.0",
+    "psutil>=6.1.0",                            # Process management for proper cleanup of child processes
+    "docworkspace>=0.2.1",
+    "ldaca-loader",
+    "pyarrow>=16.0.0",
+    "tbb>=2022.3.1 ; sys_platform != 'darwin'",
+    "openai>=2.26.0",
+    "pyairtable>=3.3.0",
+]
+
+[project.optional-dependencies]
+deploy = ["jupyter-server-proxy>=4.4.0", "ipython>=9.5.0"]
+
+[project.scripts]
+ldaca-web-app = "ldaca_web_app.cli:main"
+ldaca_web_app = "ldaca_web_app.cli:main"
+
+[tool.pytest.ini_options]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+pythonpath = ["src"]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "workspace: marks tests related to workspace functionality",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["twine>=6.2.0", "pytest-asyncio>=0.23.0"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/src/ldaca_web_app/resources/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ldaca_web_app"]
+include = ["src/ldaca_web_app/resources/**"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.uv.sources]
+ldaca-loader = { git = "https://github.com/Australian-Text-Analytics-Platform/ldaca-tabulator", branch = "ldaca_web_app_integration" }

ldaca_web_app-0.1.0/src/ldaca_web_app/__init__.py

@@ -0,0 +1,14 @@
+"""Public package exports for backend app entrypoints.
+
+Used by:
+- desktop/runtime launchers and external embedding contexts
+
+Why:
+- Provides stable import surface for app object and startup helpers.
+"""
+
+from .core.workspace import workspace_manager
+from .deploy import start_backend, start_frontend
+from .main import app
+
+__all__ = ["app", "workspace_manager", "start_backend", "start_frontend"]

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/__init__.py

@@ -0,0 +1,8 @@
+"""Analysis domain package.
+
+Used by:
+- workspace analysis routers and task manager serialization code
+
+Why:
+- Groups request/result contracts and implementation-specific schema modules.
+"""

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/implementations/concordance.py

@@ -0,0 +1,58 @@
+"""Concordance analysis request/result schema module.
+
+Used by:
+- concordance analysis API routes and task persistence payloads
+
+Why:
+- Keeps concordance-specific request/result contracts separated from route logic.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+from ..models import BaseAnalysisRequest
+from ..results import BaseAnalysisResult
+
+
+class ConcordanceRequest(BaseAnalysisRequest):
+    """Request payload schema for concordance runs.
+
+    Used by:
+    - concordance route/task creation flows
+
+    Why:
+    - Validates all search/context/pagination-related analysis inputs.
+    """
+
+    node_ids: List[str]
+    node_columns: Optional[Dict[str, str]] = None
+    search_word: str
+    num_left_tokens: int = 50
+    num_right_tokens: int = 50
+    regex: bool = False
+    whole_word: bool = False
+    case_sensitive: bool = False
+    combined: bool = False
+
+
+class ConcordanceResult(BaseAnalysisResult):
+    """Serializable concordance result wrapper.
+
+    Used by:
+    - analysis task result serialization helpers
+
+    Why:
+    - Provides a consistent JSON output shape for concordance payloads.
+    """
+
+    def __init__(self, results: List[Dict[str, Any]], total_hits: int):
+        self.results = results
+        self.total_hits = total_hits
+
+    def to_json(self, **kwargs: Any) -> Dict[str, Any]:
+        """Return JSON-serializable concordance payload."""
+        return {
+            "results": self.results,
+            "total_hits": self.total_hits,
+        }

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/implementations/quotation.py

@@ -0,0 +1,69 @@
+"""Quotation analysis request/result schema module.
+
+Used by:
+- quotation analysis API routes and worker task payload marshalling
+
+Why:
+- Encapsulates quotation-specific request/result contracts.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from ..models import BaseAnalysisRequest
+from ..results import BaseAnalysisResult
+
+
+class QuotationEngineConfig(BaseModel):
+    """Configuration schema for quotation extraction engines.
+
+    Used by:
+    - `QuotationRequest`
+
+    Why:
+    - Supports local and remote engine selection with optional model/auth fields.
+    """
+
+    type: str = "local"  # "local" or "remote"
+    model: Optional[str] = None
+    url: Optional[str] = None
+    api_key: Optional[str] = None
+
+
+class QuotationRequest(BaseAnalysisRequest):
+    """Request payload schema for quotation analysis.
+
+    Used by:
+    - quotation run/update endpoints
+
+    Why:
+    - Validates node/column/engine/paging options for quotation workflows.
+    """
+
+    node_id: str
+    column: str
+    engine: Optional[QuotationEngineConfig] = None
+    page: Optional[int] = 1
+    page_size: Optional[int] = 50
+    sort_by: Optional[str] = None
+    descending: Optional[bool] = True
+    context_length: Optional[int] = None
+
+
+class QuotationResult(BaseAnalysisResult):
+    """Serializable quotation result wrapper.
+
+    Used by:
+    - analysis task result persistence/rehydration paths
+
+    Why:
+    - Preserves arbitrary quotation payloads behind unified result interface.
+    """
+
+    def __init__(self, data: Dict[str, Any]):
+        self.data = data
+
+    def to_json(self, **kwargs: Any) -> Dict[str, Any]:
+        """Return JSON-serializable quotation payload."""
+        return self.data

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/implementations/sequential_analysis.py

@@ -0,0 +1,58 @@
+"""Sequential analysis request schema module.
+
+Used by:
+- sequential analysis routes and task persistence models
+
+Why:
+- Keeps sequential-analysis specific request fields versioned in one place.
+"""
+
+from typing import List, Optional
+
+from pydantic import Field
+
+from ..models import BaseAnalysisRequest
+
+
+class SequentialAnalysisRequest(BaseAnalysisRequest):
+    """
+    Request model for sequential analysis.
+
+    Used by:
+    - sequential analysis run/update endpoints
+
+    Why:
+    - Validates temporal grouping and binning parameters.
+
+    Refactor note:
+    - `column_type`, `numeric_origin`, and `numeric_interval` are declared twice;
+        remove duplicated declarations to reduce schema ambiguity.
+    """
+
+    node_id: Optional[str] = Field(None, description="Node ID to analyze")
+    time_column: str = Field(..., description="Column containing time/numeric data")
+    group_by_columns: Optional[List[str]] = Field(
+        None, description="Columns to group by"
+    )
+    frequency: str = Field(
+        "monthly", description="Frequency (daily, weekly, monthly, yearly)"
+    )
+    sort_by_time: bool = Field(True, description="Whether to sort by time")
+    column_type: str = Field(
+        "datetime", description="Column type (datetime or numeric)"
+    )
+    numeric_origin: Optional[float] = Field(
+        None, description="Origin for numeric binning"
+    )
+    numeric_interval: Optional[float] = Field(
+        None, description="Interval for numeric binning"
+    )
+    column_type: str = Field(
+        "datetime", description="Column type (datetime or numeric)"
+    )
+    numeric_origin: Optional[float] = Field(
+        None, description="Origin for numeric binning"
+    )
+    numeric_interval: Optional[float] = Field(
+        None, description="Interval for numeric binning"
+    )

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/implementations/token_frequency.py

@@ -0,0 +1,37 @@
+"""Token-frequency analysis request schema module.
+
+Used by:
+- token-frequency routes and worker task request validation
+
+Why:
+- Keeps token-frequency analysis input contract centralized.
+"""
+
+from typing import Dict, List, Optional
+
+from pydantic import Field
+
+from ..models import BaseAnalysisRequest
+
+
+class TokenFrequencyRequest(BaseAnalysisRequest):
+    """
+    Request model for token-frequency analysis.
+
+    Used by:
+    - token-frequency run/update endpoints
+
+    Why:
+    - Validates node selection, stop-word, and token-limit parameters.
+    """
+
+    node_ids: List[str] = Field(..., description="List of node IDs to analyze (1 or 2)")
+    node_columns: Optional[Dict[str, str]] = Field(
+        None, description="Map of node_id to column name"
+    )
+    stop_words: Optional[List[str]] = Field(
+        None, description="List of stop words to exclude"
+    )
+    token_limit: Optional[int] = Field(
+        None, description="Limit on number of tokens returned"
+    )

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/implementations/topic_modeling.py

@@ -0,0 +1,39 @@
+"""Topic-modeling analysis request schema module.
+
+Used by:
+- topic-modeling routes and worker task request validation
+
+Why:
+- Keeps topic-modeling specific input contract centralized.
+"""
+
+from pydantic import Field
+
+from ..models import BaseAnalysisRequest
+
+
+class TopicModelingRequest(BaseAnalysisRequest):
+    """
+    Request model for topic-modeling analysis.
+
+    Used by:
+    - topic-modeling run/update endpoints
+
+    Why:
+    - Validates node selection and clustering configuration inputs.
+
+    """
+
+    node_ids: list[str] = Field(..., description="List of node IDs to analyze")
+    node_columns: dict[str, str] | None = Field(
+        None, description="Map of node_id to column name"
+    )
+    min_topic_size: int = Field(
+        5, description="DBSCAN min_points (minimum cluster size)"
+    )
+    random_seed: int = Field(
+        42, description="Random seed used for reproducible topic-modeling runs"
+    )
+    representative_words_count: int = Field(
+        5, description="Number of representative words to keep per topic"
+    )

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/manager.py

@@ -0,0 +1,148 @@
+"""Analysis storage manager.
+
+Provides per-user in-memory storage for analysis task records.  Each
+``AnalysisTask`` tracks the ``workspace_id`` it was created for, so
+tasks can be bulk-cleared when a workspace is unloaded.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from .models import AnalysisStatus, AnalysisTask, BaseAnalysisRequest
+
+# In-memory storage: user_id -> TaskManagerStore
+_TASK_MANAGER_STORE: Dict[str, TaskManagerStore] = {}
+
+
+class TaskManagerStore:
+    """Per-user in-memory storage for analysis task records."""
+
+    def __init__(self) -> None:
+        self.tasks: Dict[str, AnalysisTask] = {}
+        self.current_task_ids: Dict[str, str] = {}
+
+    def get_task(self, task_id: str) -> Optional[AnalysisTask]:
+        return self.tasks.get(task_id)
+
+    def save_task(self, task: AnalysisTask) -> None:
+        self.tasks[task.task_id] = task
+
+    def get_all_tasks(self) -> List[AnalysisTask]:
+        return list(self.tasks.values())
+
+    def set_current_task(self, tab: str, task_id: str) -> None:
+        self.current_task_ids[tab] = task_id
+
+    def get_current_task_ids(self, tab: str) -> List[str]:
+        task_id = self.current_task_ids.get(tab)
+        return [task_id] if task_id else []
+
+    def clear_task(self, task_id: str) -> None:
+        if task_id in self.tasks:
+            del self.tasks[task_id]
+        for tab, current_id in list(self.current_task_ids.items()):
+            if current_id == task_id:
+                del self.current_task_ids[tab]
+
+    def clear_all(self) -> List[str]:
+        ids = list(self.tasks.keys())
+        self.tasks.clear()
+        self.current_task_ids.clear()
+        return ids
+
+    def clear_workspace(self, workspace_id: str) -> List[str]:
+        """Remove all tasks belonging to *workspace_id* and return their IDs."""
+        to_remove = [
+            tid for tid, task in self.tasks.items() if task.workspace_id == workspace_id
+        ]
+        for tid in to_remove:
+            self.clear_task(tid)
+        return to_remove
+
+
+class TaskManager:
+    """Per-user task storage keyed by task_id with per-tab current mapping."""
+
+    def __init__(self, user_id: str) -> None:
+        self.user_id = user_id
+        if user_id not in _TASK_MANAGER_STORE:
+            _TASK_MANAGER_STORE[user_id] = TaskManagerStore()
+        self.store = _TASK_MANAGER_STORE[user_id]
+
+    def create_task(
+        self,
+        request: BaseAnalysisRequest | dict[str, Any],
+    ) -> str:
+        """Create and store a new pending analysis task.
+
+        The current workspace is resolved automatically from
+        ``workspace_manager`` so callers don't need to pass it.
+        """
+        from ..core.workspace import workspace_manager
+
+        workspace_id = workspace_manager.get_current_workspace_id(self.user_id) or ""
+        task_id = str(uuid4())
+        normalized_request = self._normalize_request(request)
+        task = AnalysisTask(
+            task_id=task_id,
+            user_id=self.user_id,
+            workspace_id=workspace_id,
+            request=normalized_request,
+            status=AnalysisStatus.PENDING,
+        )
+        self.store.save_task(task)
+        return task_id
+
+    def get_task(self, task_id: str) -> Optional[AnalysisTask]:
+        return self.store.get_task(task_id)
+
+    def save_task(self, task: AnalysisTask) -> None:
+        self.store.save_task(task)
+
+    def set_current_task(self, tab: str, task_id: str) -> None:
+        self.store.set_current_task(tab, task_id)
+
+    def get_current_task_ids(self, tab: str) -> List[str]:
+        return self.store.get_current_task_ids(tab)
+
+    def update_task(self, task_id: str, result: Any) -> None:
+        task = self.store.get_task(task_id)
+        if task is None:
+            return
+        task.result = result
+        task.status = AnalysisStatus.COMPLETED
+        task.updated_at = datetime.now()
+        self.store.save_task(task)
+
+    def clear_task(self, task_id: str) -> None:
+        self.store.clear_task(task_id)
+
+    def clear_all(self) -> List[str]:
+        return self.store.clear_all()
+
+    def clear_workspace(self, workspace_id: str) -> List[str]:
+        """Clear all tasks belonging to *workspace_id*."""
+        return self.store.clear_workspace(workspace_id)
+
+    def get_all_tasks(self) -> List[AnalysisTask]:
+        return self.store.get_all_tasks()
+
+    def _normalize_request(
+        self, request: BaseAnalysisRequest | dict[str, Any]
+    ) -> BaseAnalysisRequest:
+        if isinstance(request, BaseAnalysisRequest):
+            return request
+        return BaseAnalysisRequest.model_validate(request)
+
+
+def get_task_manager(user_id: str) -> TaskManager:
+    """Return the analysis task manager for a user.
+
+    A single user can only have one workspace loaded at a time, so the
+    manager is keyed by *user_id* only.  Individual tasks track their
+    ``workspace_id`` internally.
+    """
+    return TaskManager(user_id)

ldaca_web_app-0.1.0/src/ldaca_web_app/analysis/models.py

@@ -0,0 +1,83 @@
+"""Analysis data models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, Generic, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .results import BaseAnalysisResult
+
+
+class AnalysisStatus(str, Enum):
+    """Lifecycle states for analysis tasks.
+
+    Used by:
+    - `AnalysisTask`
+    - analysis/task APIs and worker sync helpers
+
+    Why:
+    - Keeps task status values consistent across storage and API responses.
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class BaseAnalysisRequest(BaseModel):
+    """Base request model for all analyses."""
+
+    model_config = ConfigDict(extra="allow")
+    # Additional common fields can go here
+
+
+TRequest = TypeVar("TRequest", bound=BaseAnalysisRequest)
+TResult = TypeVar("TResult", bound=BaseAnalysisResult)
+
+
+class AnalysisTask(BaseModel, Generic[TRequest, TResult]):
+    """Container for a single analysis task."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    task_id: str
+    user_id: str
+    workspace_id: str
+    status: AnalysisStatus = AnalysisStatus.PENDING
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+    request: TRequest
+    result: Optional[TResult] = None
+    error: Optional[str] = None
+
+    def complete(self, result: TResult) -> None:
+        """Mark task completed and attach result payload.
+
+        Used by:
+        - `analysis.manager.TaskManager.update_task`
+        - worker sync paths that finalize memory tasks
+
+        Why:
+        - Provides one canonical status transition to `COMPLETED`.
+        """
+        self.result = result
+        self.status = AnalysisStatus.COMPLETED
+        self.updated_at = datetime.now()
+
+    def fail(self, error: str) -> None:
+        """Mark task failed with error details.
+
+        Used by:
+        - worker sync and error propagation paths
+
+        Why:
+        - Standardizes failure transition metadata for UI/task APIs.
+        """
+        self.error = error
+        self.status = AnalysisStatus.FAILED
+        self.updated_at = datetime.now()