piilot-pack-compta

Expert-comptable tools — payroll journal import, protected reference KBs

🧩 This repo is both a template and a working "hello" plugin.

Just want to demo / dogfood? Install it as-is, it loads as plugin hello with one module and one migration — no edits required.

Want to start your own plugin? Fork via gh repo create --template, then rename everything to your namespace in one go:

./init-plugin.sh <namespace> "<description>" <category>

See the Piilot plugin development guide for the full workflow.

What it does

TODO: one-paragraph summary of this plugin's purpose and the problem it solves for a Piilot company.

What this template demonstrates (SDK v0.3)

The hello plugin is a functional showcase of the Piilot SDK v0.2+ primitives, pinned to piilot-sdk>=0.3.0. Fork the template and start from a plugin that already wires:

Full reference: see the Piilot plugin development guide.

Dual distribution

• Backend — piilot-pack-compta on PyPI, tagged v<version>.
• Frontend — piilot-pack-compta-ui on npm, tagged ui-v<version>.

Both ship from this single repo; the two release workflows publish independently so a backend hot-fix doesn't force a frontend release and vice-versa.

Install

Self-hosted Piilot (docker-compose.selfhost.yml)

# Drop the package into /app/plugins/
pip install piilot-pack-compta
# or for a git-based install while the SDK is still pre-PyPI:
pip install git+https://github.com/Kinetics-Consulting-V2/piilot-pack-compta.git@v0.1.0

# Restart the backend
docker compose restart backend

Piilot Cloud (SaaS)

Add the dependency to the core's requirements.txt:

piilot-pack-compta @ git+https://github.com/Kinetics-Consulting-V2/piilot-pack-compta.git@v0.1.0

Coolify rebuilds the backend image; the loader picks up the plugin at startup and applies migrations. Enable for a given company via:

curl -X PUT \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "X-Company-Id: $COMPANY_ID" \
  https://api.piilot.ai/admin/plugins/hello/activations/$COMPANY_ID

Usage

TODO: how a user interacts with the plugin (module screens, agent tools, integrations…).

Development

Local setup

# Clone next to the Piilot core
cd /opt/factory/projects
git clone https://github.com/Kinetics-Consulting-V2/piilot-pack-compta.git

# Install in editable mode with dev extras
cd piilot-pack-compta
pip install -e .[dev]

Then add the plugin as a bind mount in the core's docker-compose.override.yml (gitignored):

services:
  backend:
    volumes:
      - ../piilot-pack-compta:/app/plugins/piilot-pack-compta

Restart the backend and watch for:

[plugins] Loaded: hello v0.1.0 (handlers=1, tools=0)

Run the tests

pytest

Versioning

This plugin follows Semantic Versioning. The sdk_compat range in pyproject.toml pins the Piilot SDK versions we build against. Watch the core's docs/SDK_CHANGELOG.md for breaking changes.

License

Apache-2.0. See LICENSE.