Metadata-Version: 2.2
Name: bisos.startAiActivity
Version: 0.1
Summary: bisos.startAiActivity: Install AI Collaborative Development Templates
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.common
Requires-Dist: bisos.pyDblock
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

=====================================================================
bisos.startAiActivity: Install AI Collaborative Development Templates
=====================================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.startAiActivity* installs the ByStar AI collaborative development
template set (``CLAUDE.md``, ``AI-AGENTS.org``, ``AI-WORKFLOW.org``,
``AI-Activity.org``, ``AI-DevStatus.org``, ``AI-WorkPlan.org``) into any
project directory or git repo root, wiring it for collaborative
development with Claude Code.

bisos.startAiActivity is a python package that uses the
`PyCS-Framework <https://github.com/bisos-pip/pycs>`__. It provides the
``startAiActivity.cs`` command and a pure-Python dblock expansion engine
(``py-dblock.cs``) for updating org-mode dynamic blocks without Emacs.

.. _table-of-contents:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Part of BISOS — ByStar Internet Services Operating
   System <#part-of-bisos--bystar-internet-services-operating-system>`__
-  `bisos.startAiActivity is a Command-Only PyCS
   Facility <#bisosstartaiactivity-is-a-command-only-pycs-facility>`__
-  `Post-Installation Setup <#post-installation-setup>`__
-  `Installation <#installation>`__

   -  `Installation With pip <#installation-with-pip>`__
   -  `Installation With pipx <#installation-with-pipx>`__
   -  `Post-Installation Basic
      Testing <#post-installation-basic-testing>`__

-  `Usage <#usage>`__

   -  `Set Templates Base Directory <#set-templates-base-directory>`__
   -  `Install Templates Into a
      Project <#install-templates-into-a-project>`__
   -  `Update Dblocks in Org Files <#update-dblocks-in-org-files>`__

-  `Key Files <#key-files>`__

   -  ```py3/bin/startAiActivity.cs`` <#py3binstartaiactivitycs>`__
   -  ```py3/bin/py-dblock.cs`` <#py3binpy-dblockcs>`__
   -  ```py3/bisos/startAiActivity/updateDblock.py`` <#py3bisosstartaiactivityupdatedblockpy>`__
   -  ```py3/bisos/startAiActivity/dblock_particulars.py`` <#py3bisosstartaiactivitydblock_particularspy>`__
   -  `PyPi and Github Packaging <#pypi-and-github-packaging>`__

-  `Documentation and Blee-Panels <#documentation-and-blee-panels>`__

   -  `bisos.startAiActivity
      Blee-Panels <#bisosstartaiactivity-blee-panels>`__

-  `Support <#support>`__
-  `Planned Improvements <#planned-improvements>`__

Part of BISOS — ByStar Internet Services Operating System
=========================================================

Layered on top of Debian, **BISOS** (By\* Internet Services Operating
System) is a unified and universal framework for developing both
internet services and software-service continuums that use internet
services. See `Bootstrapping ByStar, BISOS and
Blee <https://github.com/bxGenesis/start>`__ for information about
getting started with BISOS.

**BISOS** is a foundation for **The Libre-Halaal ByStar Digital
Ecosystem** which is described as a cure for losses of autonomy and
privacy in a book titled: `Nature of
Polyexistentials <https://github.com/bxplpc/120033>`__

*bisos.startAiActivity* is part of BISOS. It is a standalone package
that can be used independently of the full BISOS environment.

bisos.startAiActivity is a Command-Only PyCS Facility
=====================================================

bisos.startAiActivity is a command-line tool. It is a PyCS single-unit
command service. PyCS is a framework that converges development of CLI
tools and services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.startAiActivity uses the PyCS-Framework to:

#. Install AI collaborative development templates (symlinks and
   safe-copies) into any project directory or git repo root.
#. Expand ``b:ai:file/particulars`` org-mode dynamic blocks in installed
   files using pure Python, without requiring Emacs or ``bx-dblock``.
#. Manage persistent user-config parameters (e.g. ``templates`` base
   path) via ``~/.config/bisos/startAiActivity.cs/``.

The core of PyCS-Framework is the *bisos.b* package (the
PyCS-Foundation). See `bisos.b <https://github.com/bisos-pip/b>`__ for
an overview.

Post-Installation Setup
=======================

After installing, configure the templates base directory. If
``/bisos/apps/defaults/ai-templates`` exists on your system it is used
as the default automatically. Otherwise, set it explicitly:

.. code:: bash

   startAiActivity.cs -i userConfig_set --parName=templates --parValue=/path/to/ai-templates

Verify the setting:

.. code:: bash

   startAiActivity.cs -i userConfig_get --parName=templates

The AI templates are maintained at:
https://github.com/bisos/defaults/tree/master/ai-templates

Installation
============

The sources for the bisos.startAiActivity pip package are maintained at:
https://github.com/bisos-pip/startAiActivity.

The bisos.startAiActivity pip package is available at PYPI as
https://pypi.org/project/bisos.startAiActivity

You can install bisos.startAiActivity with pip or pipx.

Installation With pip
---------------------

If you need access to bisos.startAiActivity as a python module, you can
install it with pip:

.. code:: bash

   pip install bisos.startAiActivity

Installation With pipx
----------------------

If you only need access to bisos.startAiActivity on command-line, you
can install it with pipx:

.. code:: bash

   pipx install bisos.startAiActivity

The following commands are made available:

-  ``startAiActivity.cs`` — installs AI collaborative development
   templates
-  ``py-dblock.cs`` — updates org-mode dynamic blocks in files (pure
   Python)

Post-Installation Basic Testing
-------------------------------

After installation, run:

.. code:: bash

   startAiActivity.cs
   startAiActivity.cs -i userConfig_get --parName=templates

Usage
=====

Set Templates Base Directory
----------------------------

.. code:: bash

   startAiActivity.cs -i userConfig_set --parName=templates --parValue=/path/to/ai-templates

Install Templates Into a Project
--------------------------------

Install into the current directory:

.. code:: bash

   startAiActivity.cs -i initiate --activity=bisos-pip

Install at the git repo root:

.. code:: bash

   startAiActivity.cs -i initiate --root=repo --activity=bisos-pip

Available activities match subdirectories under the templates base (e.g.
``bisos-pip``, ``bisos-core``, ``xu-single``, ``blee-panels``,
``lcnt``). Run ``startAiActivity.cs -i examples`` to see all available
activities.

Update Dblocks in Org Files
---------------------------

.. code:: bash

   py-dblock.cs -i updateDblocks AI-WorkPlan.org AI-DevStatus.org

Key Files
=========

An overview of the relevant files of the bisos.startAiActivity package:

``py3/bin/startAiActivity.cs``
------------------------------

The main CS-MU (Command-Services Multi-Unit). Provides the ``initiate``,
``userConfig_get``, and ``userConfig_set`` commands. Uses
``bisos.b.userConfig_csu`` for persistent parameter management.

``py3/bin/py-dblock.cs``
------------------------

A CS command that applies pure-Python org-mode dblock expansion to one
or more files. Imports ``dblock_particulars`` to register the
``b:ai:file/particulars`` handler.

``py3/bisos/startAiActivity/updateDblock.py``
---------------------------------------------

General dblock dispatch engine. Handlers register under a signature
string via ``registerHandler(sig, fn)``. ``expandAll(filePath)`` does a
single-pass regex substitution over the file, dispatching each
``####+BEGIN: <signature>`` block to its registered handler.

``py3/bisos/startAiActivity/dblock_particulars.py``
---------------------------------------------------

Self-registering handler for the ``b:ai:file/particulars`` dblock
signature. Derives the ``activity`` from the ``AI-Activity.org`` symlink
and builds the companion-docs list by scanning the directory.

PyPi and Github Packaging
-------------------------

All bisos-pip repos in the https://github.com/bisos-pip github
organization follow the same structure. They all have
`setup.py <./setup.py>`__ files driven by
`pypiProc.sh <./pypiProc.sh>`__.

Documentation and Blee-Panels
=============================

bisos.startAiActivity is part of ByStar Digital Ecosystem
http://www.by-star.net.

This module's primary documentation is in the form of Blee-Panels.
Additional information is also available in:
http://www.by-star.net/PLPC/180047

bisos.startAiActivity Blee-Panels
---------------------------------

bisos.startAiActivity Blee-Panels are in the ``./panels`` directory.
From within Blee and BISOS these panels are accessible under the Blee
"Panels" menu.

See
`file:./panels/bisos.startAiActivity/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.startAiActivity/_nodeBase_/fullUsagePanel-en.org>`__
for a starting point.

Support
=======

| For support, criticism, comments and questions; please contact the
  author/maintainer
| `Mohsen Banan <http://mohsen.1.banan.byname.net>`__ at:
  http://mohsen.1.banan.byname.net/contact

Planned Improvements
====================

-  Upload to PyPI and test as pipx install
-  Write fullUsagePanel-en.org Blee-Panel
