#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Timestamp: 2026-01-27
# File: src/scitex_writer/guidelines/__init__.py
"""IMRAD writing guidelines for scientific manuscripts.
Guidelines are templates/tips for writing manuscript sections.
Prompts can be built from guidelines + user content.
Usage::
from scitex_writer.guidelines import get, build, list_sections
# Get raw guidelines
tips = get("abstract")
# Build prompt with draft
prompt = build("abstract", draft="My draft text...")
Custom guidelines via environment variables:
SCITEX_WRITER_GUIDELINE_ABSTRACT=/path/to/custom.md
SCITEX_WRITER_GUIDELINE_DIR=/path/to/guidelines/
"""
import os as _os
from pathlib import Path as _Path
try:
from scitex_dev.decorators import supports_return_as as _supports_return_as
except ImportError:
def _supports_return_as(fn):
return fn
# Available sections (internal)
_SECTIONS = ["abstract", "introduction", "methods", "discussion", "proofread"]
# Default data directory
_DEFAULT_DIR = _Path(__file__).parent
__all__ = ["get", "build", "list_sections"]
def _get_path(section: str) -> _Path:
"""Get path to guideline file, checking env overrides first."""
env_key = f"SCITEX_WRITER_GUIDELINE_{section.upper()}"
if env_path := _os.environ.get(env_key):
return _Path(env_path)
if guideline_dir := _os.environ.get("SCITEX_WRITER_GUIDELINE_DIR"):
custom_path = _Path(guideline_dir) / f"{section}.md"
if custom_path.exists():
return custom_path
return _DEFAULT_DIR / f"{section}_.md"
[docs]
@_supports_return_as
def get(section: str) -> str:
"""Get writing guidelines for a manuscript section.
Args:
section: One of: abstract, introduction, methods, discussion, proofread
Returns:
Guidelines markdown content with PLACEHOLDER marker.
Raises:
ValueError: If section is not recognized.
FileNotFoundError: If guidelines file not found.
"""
section = section.lower().strip()
if section not in _SECTIONS:
raise ValueError(
f"Unknown section: '{section}'. Available: {', '.join(_SECTIONS)}"
)
path = _get_path(section)
if not path.exists():
raise FileNotFoundError(f"Guidelines not found: {path}")
return path.read_text(encoding="utf-8")
[docs]
@_supports_return_as
def build(section: str, draft: str, placeholder: str = "PLACEHOLDER") -> str:
"""Build a prompt from guidelines and user draft.
Args:
section: Section name.
draft: User's draft text.
placeholder: Placeholder to replace (default: PLACEHOLDER).
Returns:
Complete prompt with draft inserted.
"""
template = get(section)
return template.replace(placeholder, draft)
[docs]
@_supports_return_as
def list_sections() -> list[str]:
"""List available sections."""
return _SECTIONS.copy()
def _get_source(section: str) -> dict[str, str]:
"""Get info about where guidelines are loaded from."""
section = section.lower().strip()
env_key = f"SCITEX_WRITER_GUIDELINE_{section.upper()}"
if env_path := _os.environ.get(env_key):
return {"path": env_path, "source": "env"}
if guideline_dir := _os.environ.get("SCITEX_WRITER_GUIDELINE_DIR"):
custom_path = _Path(guideline_dir) / f"{section}.md"
if custom_path.exists():
return {"path": str(custom_path), "source": "custom_dir"}
return {"path": str(_DEFAULT_DIR / f"{section}_.md"), "source": "default"}
# EOF