How bdfsaraiva/parshift works
ParShift is an open-source Python package/library (published to PyPI) for analyzing conversational sequences using Gibson’s participation shift framework. It is *not* a running service or distributed system; the “architecture” is primarily:
• A Python API surface (functions/classes users call)
• Internal modules that implement parsing/annotation, statistics, and plotting
• Developer toolchain: tests, docs site, CI, packaging/release automation
Core package (parshift/)
• parshift/__init__.py
• parshift/annotation.py
Likely handles input normalization and annotation of conversational data into participation-shift labels/structures (based on the tests and CSV fixtures under tests/data).
• parshift/statistics.py
Computes metrics/statistical summaries on annotated conversations.
• parshift/plotting.py
Generates visualizations of shifts/metrics (this often depends on the outputs of annotation and/or statistics).
• parshift/oo_parshift.py
Indicates an object-oriented API (a “main class” / orchestrator). Architecturally, this is usually the “high-level workflow” component that composes:
• annotation (prepare/label data)
• statistics (compute measures)
• parshift/py.typed
Signals PEP 561 typing support (typed library). Include this as a quality/interop note (optional) rather than a functional component.
Tests (tests/)
• tests/test_*.py, tests/conftest.py, tests/data/*.csv
This is the verification suite. It also reveals implied domain objects:
• Inputs: conversation data in CSV/DF forms
• Required columns: e.g., id, target, reply etc. (as indicated by fixture names like conv_missing_id.csv)
Documentation site (docs/)
• docs/mkdocs.yml, docs/docs/*.md
A MkDocs documentation system (with images). This is a separate “Documentation build” component.
Build/Release configuration (top-level)
• pyproject.toml
Packaging/build configuration (dependencies, build backend, dev extras, tooling config).
CI/CD (.github/workflows/)
• tests.yml → test runs
• cov.yml → coverage reporting (Codecov)
• docs.yml → docs build/deploy to GitHub Pages
• publish.yml → publish to PyPI
These are critical to include as the “delivery pipeline” part of the architecture.
Library “runtime” architecture (user → API → modules)
Actors & inputs
• Actor: *Researcher / analyst / developer (Python user)*
• Inputs: *CSV files / pandas DataFrames* (inferred from tests/data and naming like df_good.csv)
Core components
• API façade: parshift (via __init__.py)
• High-level OO interface: oo_parshift.py (main orchestrator)
• Functional modules:
• annotation.py
• statistics.py
• plotting.py
Outputs
• Annotated conversation structures / labeled sequences
• Statistical results/tables
• Plots/figures
• User code → parshift API
• parshift API → (either) oo_parshift (OO workflow) and/or direct calls to annotation/statistics/plotting
• oo_parshift → annotation
• oo_parshift → statistics
• oo_parshift → plotting
• annotation → produces “annotated conversation” artifact → consumed by statistics and plotting
• “Conversation table (CSV/DF)” → “Validated/normalized conversation”
• “Normalized conversation” → “Participation-shift annotations”
• “Annotations” → “Metrics” and “Visualizations”
Delivery/tooling architecture (repo → CI → docs/PyPI)
This is the second “system” view: how the package is validated and shipped.
Components
• GitHub repository
• GitHub Actions workflows:
• Tests
• Coverage → Codecov
• Docs build → GitHub Pages
• Publish → PyPI
• Artifact outputs:
• Python distribution (wheel/sdist) on PyPI
• Hosted docs website
Key flows
• Push/PR → tests.yml (pytest)
• Push/PR → cov.yml → Codecov
• Push/tag → publish.yml → PyPI
• Push/main → docs.yml → GitHub Pages (MkDocs)
Container (Level 2)
• ParShift library (the package)
• Documentation site (MkDocs → GitHub Pages)
• CI/CD pipeline (GitHub Actions)
• PyPI distribution channel
• Codecov (coverage service)
Component (Level 3) inside ParShift
• OO orchestrator (oo_parshift)
• Annotation engine (annotation)
• Statistics engine (statistics)
• Plotting subsystem (plotting)
• Public API façade (__init__)
That “component inside package” level is the most valuable for maintainers/users.
Be explicit about boundaries
• Runtime boundary: “User environment (local Python runtime / notebook / Colab)”
• Repo/DevOps boundary: “GitHub (CI + docs + release)”
This avoids conflating “how it runs” with “how it’s shipped”.