# Civic Transparency Software Development Kit (SDK)
[](https://civic-interconnect.github.io/civic-transparency-py-sdk/)
[](https://pypi.org/project/civic-transparency-sdk/)
[](https://pypi.org/project/civic-transparency-sdk/)
[](https://github.com/civic-interconnect/civic-transparency-py-sdk/actions/workflows/ci.yml)
[](./LICENSE)
Synthetic data generation toolkit for civic transparency research and testing.
## Installation
```pwsh
pip install civic-transparency-sdk
```
## What This Package Provides
- **Synthetic Data Generation**: Create realistic transparency data for testing and research without requiring real user data. Generate controlled datasets with reproducible seeds for studying information dynamics.
- **Internal Data Structures**: Simulation-specific types (`WindowAgg`, `ContentHash`, `TopHash`) for generating and manipulating synthetic transparency data.
- **Database Integration**: Convert generated data to DuckDB/SQL databases for analysis with ready-to-use schemas and indexing patterns.
- **CLI Tools**: Command-line utilities for generating worlds, converting formats, and managing synthetic datasets.
> **Note**: This SDK generates synthetic data for research/testing. For implementing the PTag API specification, see **civic-transparency-ptag-types**, which provides the official API response types.
## Quick Start
Generate synthetic data:
```bash
# Activate environment
source .venv/bin/activate # Linux/Mac
# or
.venv\Scripts\activate # Windows
# Generate baseline world
ct-sdk generate --world A --topic-id aa55ee77 --out world_A.jsonl
# Convert to database
ct-sdk convert --jsonl world_A.jsonl --duck world_A.duckdb --schema schema/schema.sql
```
The generated DuckDB files are ready for analysis with any SQL-compatible tools or custom analysis scripts.
---
## Use Cases
- **Academic Research**: Generate controlled datasets with known parameters for studying information dynamics, coordination patterns, and transparency system behaviors.
- **Algorithm Development**: Build and test transparency tools using synthetic data that mimics real-world patterns without privacy concerns.
- **Testing & Validation**: Create reproducible test datasets for developing transparency systems without requiring real user data.
- **Education**: Provide realistic datasets for teaching transparency concepts, data analysis, and system design.
---
## Reproducibility
All generation is deterministic:
- **Seed-based randomization**: Same seed produces identical datasets
- **Version tracking**: Metadata includes package versions
- **Parameter logging**: All generation settings preserved in output
- **Schema versioning**: Database structures fully documented
**Example seeds:**
- World A (baseline): `4242`
- World B (influenced): `8484`
---
## Package Structure
```
ci.transparency.sdk/
├── cli/ # Command-line interface (ct-sdk)
├── digests.py # Content fingerprinting (SimHash64, MinHashSig)
├── hash_core.py # Content identification (HashId, ContentHash, TopHash)
├── ids.py # ID management (WorldId, TopicId)
├── io_schema.py # JSON serialization utilities
└── window_agg.py # Window aggregation structure (WindowAgg)
```
---
## Related Projects
- **Civic Transparency PTag Spec** - Official API specification
- **Civic Transparency PTag Types** - Python types for PTag API responses (use this for API implementation)
- **Civic Transparency Verify** - Statistical verification tools (private)
---
## Security Model
This package provides synthetic data generation for research and testing.
It does **not** include:
- Detection algorithms or thresholds
- Verification workflows or assessment criteria
- Operational patterns or alerting rules
These are maintained separately to prevent adversarial reverse-engineering while enabling legitimate transparency research.
---
## Documentation
Full documentation at:
[civic-interconnect.github.io/civic-transparency-py-sdk/](https://civic-interconnect.github.io/civic-transparency-py-sdk/)
- **Usage Guide** - Getting started and common workflows
- **CLI Reference** - Command-line interface details
- **SDK Reference** - Core Python APIs
- **Schema Reference** - Database schemas and integration
---
### Development
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
## Versioning
This specification follows semantic versioning.
See [CHANGELOG.md](./CHANGELOG.md) for version history.
## License
MIT © [Civic Interconnect](https://github.com/civic-interconnect)
Raw data
{
"_id": null,
"home_page": null,
"name": "civic-transparency-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "transparency, api, sdk, civic",
"author": "Civic Interconnect",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ab/a1/84a33c8a385c35781af665e908f2806a857092d1642092f7da8da4da92d1/civic_transparency_sdk-0.1.2.tar.gz",
"platform": null,
"description": "# Civic Transparency Software Development Kit (SDK)\n\n[](https://civic-interconnect.github.io/civic-transparency-py-sdk/)\n[](https://pypi.org/project/civic-transparency-sdk/)\n[](https://pypi.org/project/civic-transparency-sdk/)\n[](https://github.com/civic-interconnect/civic-transparency-py-sdk/actions/workflows/ci.yml)\n[](./LICENSE)\n\nSynthetic data generation toolkit for civic transparency research and testing.\n\n\n## Installation\n\n```pwsh\npip install civic-transparency-sdk\n```\n\n## What This Package Provides\n\n- **Synthetic Data Generation**: Create realistic transparency data for testing and research without requiring real user data. Generate controlled datasets with reproducible seeds for studying information dynamics.\n- **Internal Data Structures**: Simulation-specific types (`WindowAgg`, `ContentHash`, `TopHash`) for generating and manipulating synthetic transparency data.\n- **Database Integration**: Convert generated data to DuckDB/SQL databases for analysis with ready-to-use schemas and indexing patterns.\n- **CLI Tools**: Command-line utilities for generating worlds, converting formats, and managing synthetic datasets.\n\n> **Note**: This SDK generates synthetic data for research/testing. For implementing the PTag API specification, see **civic-transparency-ptag-types**, which provides the official API response types.\n\n\n## Quick Start\n\nGenerate synthetic data:\n\n```bash\n# Activate environment\nsource .venv/bin/activate # Linux/Mac\n# or\n.venv\\Scripts\\activate # Windows\n\n# Generate baseline world\nct-sdk generate --world A --topic-id aa55ee77 --out world_A.jsonl\n\n# Convert to database\nct-sdk convert --jsonl world_A.jsonl --duck world_A.duckdb --schema schema/schema.sql\n```\n\nThe generated DuckDB files are ready for analysis with any SQL-compatible tools or custom analysis scripts.\n---\n\n## Use Cases\n\n- **Academic Research**: Generate controlled datasets with known parameters for studying information dynamics, coordination patterns, and transparency system behaviors.\n- **Algorithm Development**: Build and test transparency tools using synthetic data that mimics real-world patterns without privacy concerns.\n- **Testing & Validation**: Create reproducible test datasets for developing transparency systems without requiring real user data.\n- **Education**: Provide realistic datasets for teaching transparency concepts, data analysis, and system design.\n\n---\n\n## Reproducibility\n\nAll generation is deterministic:\n\n- **Seed-based randomization**: Same seed produces identical datasets\n- **Version tracking**: Metadata includes package versions\n- **Parameter logging**: All generation settings preserved in output\n- **Schema versioning**: Database structures fully documented\n\n**Example seeds:**\n\n- World A (baseline): `4242`\n- World B (influenced): `8484`\n\n---\n## Package Structure\n\n```\nci.transparency.sdk/\n\u251c\u2500\u2500 cli/ # Command-line interface (ct-sdk)\n\u251c\u2500\u2500 digests.py # Content fingerprinting (SimHash64, MinHashSig)\n\u251c\u2500\u2500 hash_core.py # Content identification (HashId, ContentHash, TopHash)\n\u251c\u2500\u2500 ids.py # ID management (WorldId, TopicId)\n\u251c\u2500\u2500 io_schema.py # JSON serialization utilities\n\u2514\u2500\u2500 window_agg.py # Window aggregation structure (WindowAgg)\n```\n\n---\n\n## Related Projects\n\n- **Civic Transparency PTag Spec** - Official API specification\n- **Civic Transparency PTag Types** - Python types for PTag API responses (use this for API implementation)\n- **Civic Transparency Verify** - Statistical verification tools (private)\n\n---\n\n## Security Model\n\nThis package provides synthetic data generation for research and testing.\nIt does **not** include:\n\n- Detection algorithms or thresholds\n- Verification workflows or assessment criteria\n- Operational patterns or alerting rules\n\nThese are maintained separately to prevent adversarial reverse-engineering while enabling legitimate transparency research.\n\n---\n\n## Documentation\n\nFull documentation at:\n[civic-interconnect.github.io/civic-transparency-py-sdk/](https://civic-interconnect.github.io/civic-transparency-py-sdk/)\n\n- **Usage Guide** - Getting started and common workflows\n- **CLI Reference** - Command-line interface details\n- **SDK Reference** - Core Python APIs\n- **Schema Reference** - Database schemas and integration\n\n---\n\n### Development\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.\n\n## Versioning\n\nThis specification follows semantic versioning.\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n## License\n\nMIT \u00a9 [Civic Interconnect](https://github.com/civic-interconnect)\n",
"bugtrack_url": null,
"license": null,
"summary": "Civic Transparency SDK - Development kit for transparency applications",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/civic-interconnect/civic-transparency-py-sdk/issues",
"Documentation": "https://civic-interconnect.github.io/civic-transparency-py-sdk/latest/",
"Homepage": "https://github.com/civic-interconnect/civic-transparency-py-sdk",
"Repository": "https://github.com/civic-interconnect/civic-transparency-py-sdk"
},
"split_keywords": [
"transparency",
" api",
" sdk",
" civic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c01566edae1cd51ba01e55f6b23b1602ad7730eed06fe081f2d114be8714674",
"md5": "e6f2f1f1283b7390410806fdd1c38e41",
"sha256": "e9b7d846126e0e06d70d291cf5e85333de205659ca15aecabd9dc5051f75676b"
},
"downloads": -1,
"filename": "civic_transparency_sdk-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6f2f1f1283b7390410806fdd1c38e41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 15109,
"upload_time": "2025-10-23T14:52:07",
"upload_time_iso_8601": "2025-10-23T14:52:07.926912Z",
"url": "https://files.pythonhosted.org/packages/0c/01/566edae1cd51ba01e55f6b23b1602ad7730eed06fe081f2d114be8714674/civic_transparency_sdk-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aba184a33c8a385c35781af665e908f2806a857092d1642092f7da8da4da92d1",
"md5": "c09435f5f0d82887c4e3ac2b570697c3",
"sha256": "4f8e75b0667974d4b7c88779bc4e9e918505d8354d15988c6d77b83e9d21a411"
},
"downloads": -1,
"filename": "civic_transparency_sdk-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c09435f5f0d82887c4e3ac2b570697c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 102852,
"upload_time": "2025-10-23T14:52:09",
"upload_time_iso_8601": "2025-10-23T14:52:09.052820Z",
"url": "https://files.pythonhosted.org/packages/ab/a1/84a33c8a385c35781af665e908f2806a857092d1642092f7da8da4da92d1/civic_transparency_sdk-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 14:52:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "civic-interconnect",
"github_project": "civic-transparency-py-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "civic-transparency-sdk"
}
JSON
