LLMOS Bridge Monorepo Workspace

This workspace contains multiple Python packages related to the LLMOS Bridge project. It is structured as a Poetry-managed monorepo where each package lives under packages/ and the root serves as a lightweight workspace for shared tooling and convenient CLI entry points.

Whether you're a newcomer or returning contributor, this document will help you get up and running quickly: installing dependencies, running packages, and understanding the development workflow.

🧩 Repository Structure

LLMOS-Bridge/ # workspace root ├─ packages/ # individual Python projects │ ├─ llmos-bridge/ # main daemon package │ ├─ langchain-llmos/ # support library for LangChain │ └─ ... # more packages may be added ├─ root_pkg/ # tiny helper package for workspace CLI ├─ docs/ # documentation source files ├─ examples/ # usage examples and demos ├─ scripts/ # utility scripts (setup, testing, etc.) ├─ Makefile # convenient shortcuts for common tasks ├─ pyproject.toml # workspace-level dependencies & config └─ README.md # this file

✅ Prerequisites

Before diving in, install the following tools:

• Python 3.11+ – the project is pinned to 3.11 in all packages.
• Poetry 1.5+ – used for dependency management and packaging.
• Git – for checking out the repository.
• make (optional) – used by the provided Makefile for convenience. On Windows, you can use Git Bash or WSL to run make, or use a PowerShell script instead.

📦 Setting Up the Development Environment

1. Clone the repository

ash git clone https://github.com/llmos-bridge/LLMOS-Bridge.git cd LLMOS-Bridge

2. Install workspace dependencies

The workspace root is configured as a tooling-only Poetry project. It installs a minimal wrapper package ( oot_pkg) and declares path dependencies on each subpackage so their requirements are available in the root environment.

powershell poetry install

This will:

• create a virtual environment (stored under Poetry’s cache)
• install oot_pkg (the thin wrapper used for CLI delegation)
• install every package listed via path in the root pyproject.toml
• bundle their dependencies ( yper, ich, etc.) into the env

You can activate the environment manually with poetry shell or just use poetry run for one-off invocations.

3. Installing dependencies for a specific package

If you only need to work on one package, change directory and install there:

powershell cd packages/llmos-bridge poetry install # installs llmos-bridge and its dependencies

This keeps the workspace env separate and is useful for isolated package work.

🚀 Running Packages and the CLI

Workspace-level CLI (recommended)

The root environment provides a convenient llmos-bridge command that forwards into the main package. You can run it from the workspace root without changing directories:

`powershell

get help for the top-level CLI

poetry run llmos-bridge --help

daemon control

poetry run llmos-bridge daemon start poetry run llmos-bridge daemon status poetry run llmos-bridge daemon stop

other command groups

posrun = poetry run llmos-bridge modules list llmos-bridge plans submit path\to\plan.json llmos-bridge app validate path\to\config.app.yaml `

The wrapper works because oot_pkg imports the real CLI from packages/llmos-bridge at runtime.

Running directly from a package

Alternatively, operate inside a package directory if you prefer:

powershell cd packages/llmos-bridge poetry run llmos-bridge daemon start

This approach is equivalent but keeps the environment scoped to that package.

Cheat sheet of useful commands

Use the Makefile at the root for shortcuts (see section below) or type them directly with poetry run.

• Start daemon: poetry run llmos-bridge daemon start
• Stop daemon: poetry run llmos-bridge daemon stop
• Status: poetry run llmos-bridge daemon status
• List modules: poetry run llmos-bridge modules list
• Submit plan: poetry run llmos-bridge plans submit
• Validate app: poetry run llmos-bridge app validate

🧪 Testing and Quality

Run the full test suite from the workspace root:

ash poetry run pytest

This will discover tests in all packages/*/tests directories. You can also target an individual package by cd-ing into it first.

Linting, formatting, and type checks are configured via uff and mypy in the root pyproject.toml; run them with poetry run ruff and poetry run mypy, or integrate with your editor.

🛠 Makefile Shortcuts

A Makefile at the root provides quick aliases to common operations, e.g.

`makefile daemon-start: poetry run llmos-bridge daemon start

daemon-status: poetry run llmos-bridge daemon status

etc.

`

Just run make daemon-start instead of typing the full command. On Windows, you can achieve the same with a PowerShell script or functions in your profile.

➕ Adding a New Package

To contribute a new package to the monorepo:

1. Create packages/my-package/ and initialise a new Poetry project there.
2. Write the code and tests as usual, ensuring the package name is unique.
3. Add a path dependency in the root pyproject.toml: oml [tool.poetry.dependencies] my-package = { path = "packages/my-package", develop = true }
4. If the package exposes CLI commands, add entry points under [tool.poetry.scripts] in its own pyproject. To make them available at the workspace root, also export a wrapper in oot_pkg and update the root [tool.poetry.scripts].
5. Update the root Makefile with any new shortcuts you need.

📚 Documentation and Further Reading

• The docs/ directory contains markdown reference material on agents, tools, memory, and more.
• CLI usage: poetry run llmos-bridge --help and poetry run llmos-bridge --help for detailed command help.
• See packages/llmos-bridge/README.md for package-specific information (e.g. configuration options, architecture).
• For architecture and design discussions, consult the various project documents such as LLMOS_Bridge_Bilan_Et_Feuille_De_Route.md.

---

Welcome aboard! Feel free to expand this README with additional sections as the project grows, such as deployment instructions, coding standards, or contributor guidelines.