feat: add CITATION.cff, CODE_OF_CONDUCT.md, and CONTRIBUTING.md; update README with citation info; implement GitHub Actions for testing

Author: iw4p

.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: tests
+
+on:
+    push:
+    pull_request:
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ["3.9", "3.10", "3.11", "3.12"]
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+            - name: Install dependencies
+              run: |
+                  python -m pip install --upgrade pip
+                  pip install -e .
+                  pip install -r requirements-dev.txt
+            - name: Run tests
+              run: pytest -q

CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+title: partialjson
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - family-names: Akbarzadeh
+    given-names: Nima
+    orcid: "https://orcid.org/0009-0005-8143-8083"
+repository-code: "https://github.com/iw4p/partialjson"
+keywords: [python, json, parsing, streaming]
+version: 1.0.0
+date-released: 2025-10-05
+

CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+We are committed to a welcoming and inclusive community. We expect all contributors and users to be respectful and constructive.
+
+- Be kind and professional.
+- Assume good intent; seek to understand before responding.
+- No harassment, discrimination, or personal attacks.
+
+Violations may be reported confidentially to the maintainer at iw4p@protonmail.com. We will take appropriate action.

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to partialjson
+
+Thanks for your interest in contributing! This project welcomes bug reports, feature requests, and pull requests.
+
+## Getting started
+
+- Fork and clone the repository
+- Create a virtual environment and install dependencies
+- Run tests to ensure a clean baseline
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install -r requirements-dev.txt
+pytest -q
+```
+
+## Development workflow
+
+- Create a feature branch from `main`
+- Add tests for new behavior
+- Run `pytest` locally and ensure all tests pass
+- Submit a pull request with a clear description and motivation
+
+## Code style
+
+- Prefer small, readable functions and clear naming
+- Add focused docstrings where non-obvious decisions are made
+- Keep public API changes minimal and documented in `CHANGELOG.md`
+
+## Reporting issues
+
+Please include:
+
+- Expected behavior and what happened instead
+- Minimal reproducible example
+- Environment details (Python version, OS)
+
+Thank you for helping improve partialjson!

README.md

@@ -47,6 +47,18 @@ Also can be found on [pypi](https://pypi.org/project/partialjson/)
 - Install the package by pip package manager.
 - After installing, you can use it and call the library.
 
+## Testing
+
+```bash
+pip install -e .
+pip install -r requirements-dev.txt
+pytest -q
+```
+
+## Citation
+
+If you use this software, please cite it using the metadata in `CITATION.cff`.
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=iw4p/partialjson&type=Date)](https://star-history.com/#iw4p/partialjson&Date)

paper/paper.bib

@@ -0,0 +1,22 @@
+@misc{rfc8259,
+  title = {The {JavaScript} Object Notation ({JSON}) Data Interchange Format},
+  author = {Bray, Tim},
+  howpublished = {RFC 8259},
+  year = {2017},
+  doi = {10.17487/RFC8259}
+}
+
+@inproceedings{ijson,
+  title = {ijson: Iterative JSON parser for Python},
+  author = {Iglesias, Ivan},
+  year = {2014},
+  url = {https://pypi.org/project/ijson/}
+}
+
+@misc{python-json,
+  title = {json — JSON encoder and decoder},
+  author = {{Python Software Foundation}},
+  year = {2024},
+  url = {https://docs.python.org/3/library/json.html}
+}
+

paper/paper.md

@@ -0,0 +1,46 @@
+---
+title: "partialjson: Parsing incomplete JSON streams safely in Python"
+tags:
+  - Python
+  - JSON
+  - streaming
+  - parsing
+  - LLM
+  - OpenAI
+authors:
+  - name: Nima Akbarzadeh
+    orcid: 0009-0005-8143-8083
+    affiliation: 1
+affiliations:
+  - name: Independent Researcher
+    index: 1
+date: 2025-10-05
+bibliography: paper.bib
+---
+
+# Summary
+
+partialjson is a small Python library for extracting useful data from partial or incomplete JSON inputs, such as streaming responses from Large Language Models (LLMs) and truncated payloads. It is commonly used to parse the output of models from providers like OpenAI. The library recovers as much structure as possible while remaining faithful to JSON semantics, helping researchers and practitioners work with unreliable or progressive sources (e.g., HTTP chunked transfer, LLM token streams, and log tails).
+
+# Statement of need
+
+Many data-centric research workflows increasingly consume JSON incrementally. A prominent use case is parsing streaming responses from LLMs, which often output JSON token by token but may be interrupted or malformed. Standard parsers reject these incomplete buffers, forcing researchers to build ad-hoc workarounds like buffering, regexes, or fragile state machines to repair the invalid JSON. partialjson provides a focused, lightweight solution: it parses arrays, objects, strings, numbers, booleans, and nulls from incomplete inputs and returns the maximal valid prefix. This enables early inspection, progress reporting, and robust ingestion pipelines for LLM outputs without bespoke parser code.
+
+# Functionality
+
+partialjson exposes a simple factory‑style API to parse any incoming buffer and return Python data structures. It supports a strict mode for standards‑compliant behavior and a relaxed mode for pragmatic recovery of incomplete strings or numbers. Typical usage requires only a few lines of code and integrates with stream readers or callback loops. The library is pure‑Python with no runtime dependencies and works across supported CPython versions.
+
+Key features:
+
+- Parse incomplete objects and arrays, recovering maximal valid structure
+- Handle strings, numbers, booleans, and nulls with optional relaxed handling
+- Report remaining unparsed tail for resumed parsing
+- Minimal API and small footprint
+
+See the project README for installation and examples.
+
+# Acknowledgements
+
+We thank open‑source JSON tooling and prior libraries that inspired streaming‑oriented parsing approaches.
+
+# References

partialjson/__init__.py

@@ -6,7 +6,7 @@
 
 from .json_parser import JSONParser
 
-__version__ = "0.1.0"
+__version__ = "1.0.0"
 __author__ = "Nima Akbarzadeh"
 __author_email__ = "iw4p@protonmail.com"
 __license__ = "MIT"

requirements-dev.txt

@@ -0,0 +1 @@
+pytest>=7.0