sentence-struct 0.1.0__tar.gz

sentence_struct-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Unit tests
+        run: uv run pytest -m "not integration" -q
+
+      - name: Integration tests (GiNza)
+        run: uv run pytest -m integration -q
+
+      - name: Build package
+        run: uv build

sentence_struct-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+# Publish release to PyPI (Trusted Publishing + uv)
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build
+        run: uv build
+
+      - name: Smoke test (wheel)
+        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+
+      - name: Smoke test (sdist)
+        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sentence-struct
+    permissions:
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: false
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        run: uv publish

sentence_struct-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# Tools
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.idea/
+.vscode/
+
+# OS / local
+.DS_Store
+.env
+*.local
+
+# Package outputs
+out/
+*.json.bak

sentence_struct-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

sentence_struct-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- Initial public API: `analyze(text, language="ja")` → document dict with
+  `sentences[].tokens` and `sentences[].chunks`.
+- Japanese backend via GiNza / Sudachi (segmentation, token merge, chunking, taxonomy).
+- CLI: `sentence-struct`.
+- GitHub Actions CI and uv-based PyPI release workflow (Trusted Publishing).

sentence_struct-0.1.0/LICENSE

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

sentence_struct-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: sentence-struct
+Version: 0.1.0
+Summary: Multilingual sentence structure analysis: sentences with tokens and syntactic chunks
+Project-URL: Homepage, https://github.com/memshare-project/sentence-struct
+Project-URL: Repository, https://github.com/memshare-project/sentence-struct
+Project-URL: Issues, https://github.com/memshare-project/sentence-struct/issues
+Project-URL: Changelog, https://github.com/memshare-project/sentence-struct/blob/main/CHANGELOG.md
+Author: sentence-struct contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chunking,japanese,linguistics,nlp,sentence-structure,tokenization
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: ginza>=5.2.1
+Requires-Dist: ja-ginza>=5.2.0
+Requires-Dist: spacy>=3.8.0
+Requires-Dist: sudachidict-core>=20240409
+Requires-Dist: sudachipy>=0.6.8
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: ja-full
+Requires-Dist: sudachidict-full>=20240409; extra == 'ja-full'
+Description-Content-Type: text/markdown
+
+# sentence-struct
+
+Analyze text into a learner-friendly structure:
+
+**document → sentences[] → { tokens[], chunks[] }**
+
+Chunks are siblings of tokens and reference them via `tokenIndices` (not nested).
+
+Japanese (`ja`) is implemented first via GiNza / Sudachi. More languages later.
+
+## Install
+
+```bash
+pip install sentence-struct
+# or
+uv add sentence-struct
+```
+
+Optional larger Sudachi dictionary:
+
+```bash
+pip install "sentence-struct[ja-full]"
+```
+
+Requires Python ≥ 3.11. First install pulls spaCy / GiNza / Sudachi (hundreds of MB).
+
+## Usage
+
+```python
+from sentence_struct import analyze
+
+doc = analyze("秋が近づくにつれ、朝晩の涼しさが心地よい。", language="ja")
+print(doc["sentence_count"], doc["token_count"], doc["chunk_count"])
+print(doc["sentences"][0]["tokens"][0])
+print(doc["sentences"][0]["chunks"][0])
+```
+
+CLI:
+
+```bash
+sentence-struct "秋が近づく。"
+sentence-struct -f essay.txt -o out.json
+```
+
+## Schema (abbreviated)
+
+```json
+{
+  "language": "ja",
+  "text": "...",
+  "sentences": [
+    {
+      "index": 1,
+      "text": "...",
+      "tokens": [
+        {"text": "秋", "pos": "名詞", "posGroup": "名詞", "lemma": "秋", "reading": "アキ"}
+      ],
+      "chunks": [
+        {"type": "NP", "typeGroup": "NP", "tokenIndices": [0, 1], "text": "秋が", "role": "nsubj"}
+      ]
+    }
+  ]
+}
+```
+
+## Develop (uv)
+
+```bash
+uv sync
+uv run pytest -m "not integration"
+uv run pytest -m integration
+uv run sentence-struct "今日は良い天気です。"
+```
+
+## Release
+
+See [RELEASING.md](RELEASING.md). Tag `vX.Y.Z` → GitHub Actions builds with **uv** and publishes to PyPI via Trusted Publishing.
+
+## License
+
+MIT

sentence_struct-0.1.0/README.md

@@ -0,0 +1,81 @@
+# sentence-struct
+
+Analyze text into a learner-friendly structure:
+
+**document → sentences[] → { tokens[], chunks[] }**
+
+Chunks are siblings of tokens and reference them via `tokenIndices` (not nested).
+
+Japanese (`ja`) is implemented first via GiNza / Sudachi. More languages later.
+
+## Install
+
+```bash
+pip install sentence-struct
+# or
+uv add sentence-struct
+```
+
+Optional larger Sudachi dictionary:
+
+```bash
+pip install "sentence-struct[ja-full]"
+```
+
+Requires Python ≥ 3.11. First install pulls spaCy / GiNza / Sudachi (hundreds of MB).
+
+## Usage
+
+```python
+from sentence_struct import analyze
+
+doc = analyze("秋が近づくにつれ、朝晩の涼しさが心地よい。", language="ja")
+print(doc["sentence_count"], doc["token_count"], doc["chunk_count"])
+print(doc["sentences"][0]["tokens"][0])
+print(doc["sentences"][0]["chunks"][0])
+```
+
+CLI:
+
+```bash
+sentence-struct "秋が近づく。"
+sentence-struct -f essay.txt -o out.json
+```
+
+## Schema (abbreviated)
+
+```json
+{
+  "language": "ja",
+  "text": "...",
+  "sentences": [
+    {
+      "index": 1,
+      "text": "...",
+      "tokens": [
+        {"text": "秋", "pos": "名詞", "posGroup": "名詞", "lemma": "秋", "reading": "アキ"}
+      ],
+      "chunks": [
+        {"type": "NP", "typeGroup": "NP", "tokenIndices": [0, 1], "text": "秋が", "role": "nsubj"}
+      ]
+    }
+  ]
+}
+```
+
+## Develop (uv)
+
+```bash
+uv sync
+uv run pytest -m "not integration"
+uv run pytest -m integration
+uv run sentence-struct "今日は良い天気です。"
+```
+
+## Release
+
+See [RELEASING.md](RELEASING.md). Tag `vX.Y.Z` → GitHub Actions builds with **uv** and publishes to PyPI via Trusted Publishing.
+
+## License
+
+MIT

sentence_struct-0.1.0/RELEASING.md

@@ -0,0 +1,111 @@
+# Releasing sentence-struct
+
+Standard flow: **bump version → CHANGELOG → commit → tag → push tag → Actions publishes to PyPI**.
+
+## One-time setup
+
+### 1. GitHub Environment
+
+Repo → **Settings → Environments → New environment** → name: `pypi`  
+(Must match `.github/workflows/release.yml` `environment.name`.)
+
+Optional: add required reviewers for production publishes.
+
+### 2. PyPI Trusted Publisher
+
+1. Create the project on PyPI (or claim the name with a first manual upload / pending publisher).
+2. Project → **Publishing** → **Add a new pending/trusted publisher**:
+   - Owner: your GitHub org/user
+   - Repository: `sentence-struct`
+   - Workflow: `release.yml`
+   - Environment: `pypi`
+3. No `PYPI_TOKEN` secret needed when Trusted Publishing is configured.
+
+### 3. Test PyPI (optional)
+
+Add a second environment `testpypi` and a workflow that runs:
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+with a matching Trusted Publisher on TestPyPI.
+
+## Release checklist
+
+1. **Green CI on main**  
+   Unit + integration tests pass.
+
+2. **Bump version** (keep these in sync):
+   - `pyproject.toml` → `[project].version`
+   - `src/sentence_struct/__init__.py` → `__version__`
+
+   With uv (example):
+
+   ```bash
+   # edit version fields, then:
+   uv lock
+   ```
+
+3. **Update CHANGELOG.md**  
+   Move items under `## Unreleased` into `## [X.Y.Z] - YYYY-MM-DD`.
+
+4. **Commit on main**
+
+   ```bash
+   git add -A
+   git commit -m "Release vX.Y.Z"
+   git push origin main
+   ```
+
+5. **Create annotated tag and push**
+
+   ```bash
+   git tag -a "vX.Y.Z" -m "Release vX.Y.Z"
+   git push origin "vX.Y.Z"
+   ```
+
+   Tag pattern must match the workflow: `v1.2.3`, `v1.2.3rc1`, `v1.2.3a1`, `v1.2.3b1`.
+
+6. **Optional: GitHub Release UI**
+
+   ```bash
+   gh release create "vX.Y.Z" --title "vX.Y.Z" --notes-file CHANGELOG.md
+   ```
+
+   Publishing is triggered by the **git tag push**, not by the GitHub Release form (unless you also push the tag).
+
+7. **Watch Actions**  
+   Workflow **Release**: build → smoke import → `uv publish`.
+
+8. **Verify**
+
+   ```bash
+   pip index versions sentence-struct
+   uvx sentence-struct "秋が近づく。"
+   ```
+
+## Versioning
+
+Follow [SemVer](https://semver.org/):
+
+| Change | Bump |
+|--------|------|
+| Break public schema / API | MAJOR |
+| New language / features | MINOR |
+| Bugfix | PATCH |
+| Pre-release | `X.Y.ZrcN` / `aN` / `bN` |
+
+## Bad release?
+
+- Prefer **yank** on PyPI (Options → Yank) with a reason, then ship a fixed version.
+- Avoid deleting published files unless necessary; yanked is enough for most cases.
+- You generally **cannot** re-upload the same filename after delete.
+
+## Local dry-run
+
+```bash
+uv build
+uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+# Do NOT run uv publish against production unless intentional.
+```

sentence_struct-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sentence-struct"
+version = "0.1.0"
+description = "Multilingual sentence structure analysis: sentences with tokens and syntactic chunks"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "sentence-struct contributors" }]
+keywords = [
+    "nlp",
+    "japanese",
+    "tokenization",
+    "chunking",
+    "sentence-structure",
+    "linguistics",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Linguistic",
+]
+# Japanese is the only backend today; future languages will be extras or additional deps.
+dependencies = [
+    "ginza>=5.2.1",
+    "ja-ginza>=5.2.0",
+    "spacy>=3.8.0",
+    "sudachidict-core>=20240409",
+    "sudachipy>=0.6.8",
+]
+
+[project.optional-dependencies]
+ja-full = ["sudachidict-full>=20240409"]
+dev = ["pytest>=8.0", "pytest-cov>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/memshare-project/sentence-struct"
+Repository = "https://github.com/memshare-project/sentence-struct"
+Issues = "https://github.com/memshare-project/sentence-struct/issues"
+Changelog = "https://github.com/memshare-project/sentence-struct/blob/main/CHANGELOG.md"
+
+[project.scripts]
+sentence-struct = "sentence_struct.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-cov>=6.0"]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: needs GiNza Japanese model (slower)",
+]
+
+[tool.coverage.run]
+source = ["sentence_struct"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+exclude_lines = [
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]

sentence_struct-0.1.0/src/sentence_struct/__init__.py

@@ -0,0 +1,15 @@
+"""sentence-struct: multilingual sentence structure analysis."""
+
+from sentence_struct.api import SUPPORTED_LANGUAGES, analyze, analyze_sentences
+from sentence_struct.models import Chunk, Sentence, Token
+
+__all__ = [
+    "SUPPORTED_LANGUAGES",
+    "Chunk",
+    "Sentence",
+    "Token",
+    "analyze",
+    "analyze_sentences",
+]
+
+__version__ = "0.1.0"

sentence_struct-0.1.0/src/sentence_struct/api.py

@@ -0,0 +1,44 @@
+"""Public analyze() entrypoint with language dispatch."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sentence_struct.models import Sentence
+from sentence_struct.serialize import document_to_dict
+
+SUPPORTED_LANGUAGES = frozenset({"ja"})
+
+
+def analyze_sentences(text: str, *, language: str = "ja") -> list[Sentence]:
+    """Analyze text into Sentence objects (tokens + chunks per sentence)."""
+    lang = language.lower().strip()
+    if lang not in SUPPORTED_LANGUAGES:
+        supported = ", ".join(sorted(SUPPORTED_LANGUAGES))
+        raise ValueError(f"Unsupported language {language!r}. Supported: {supported}")
+
+    if lang == "ja":
+        from sentence_struct.backends.ja.segment import analyze as analyze_ja
+
+        return analyze_ja(text)
+
+    raise ValueError(f"Unsupported language {language!r}")
+
+
+def analyze(text: str, *, language: str = "ja") -> dict[str, Any]:
+    """Analyze text into the public document dict.
+
+    Schema::
+
+        {
+          "language": "ja",
+          "text": "...",
+          "sentences": [
+            {"index": 1, "text": "...", "tokens": [...], "chunks": [...]}
+          ]
+        }
+
+    Chunks are siblings of tokens and reference them via ``tokenIndices``.
+    """
+    sentences = analyze_sentences(text, language=language)
+    return document_to_dict(text, sentences, language=language.lower().strip())

sentence_struct-0.1.0/src/sentence_struct/backends/__init__.py

@@ -0,0 +1 @@
+"""Language backends. Japanese ships first; more languages later."""

sentence_struct-0.1.0/src/sentence_struct/backends/ja/__init__.py

@@ -0,0 +1,5 @@
+"""Japanese backend (GiNza / Sudachi)."""
+
+from sentence_struct.backends.ja.segment import analyze
+
+__all__ = ["analyze"]