orchid-cli 0.1.0__tar.gz

orchid_cli-0.1.0/.editorconfig

@@ -0,0 +1,22 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.py]
+indent_style = space
+indent_size = 4
+max_line_length = 120
+
+[*.{yml,yaml,json,toml}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false

orchid_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,157 @@
+# orchid-cli (Typer CLI) — CI + Semantic Release
+
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  # ── Lint ────────────────────────────────────────────────────
+
+  ruff:
+    name: Ruff lint & format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check orchid_cli/
+      - run: ruff format --check orchid_cli/
+
+  commit-lint:
+    name: Commit message check
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install gitlint
+      - run: gitlint --commits "${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
+
+  # ── Test ────────────────────────────────────────────────────
+
+  test:
+    name: Tests + coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]" pytest-cov
+      - name: Run tests
+        run: |
+          pytest tests/ \
+            --cov=orchid_cli \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            --junitxml=report.xml \
+            -x
+      - name: Upload coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+          if-no-files-found: ignore
+      - name: Upload test report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-report
+          path: report.xml
+          if-no-files-found: ignore
+      - name: Coverage summary
+        if: hashFiles('coverage.xml') != ''
+        uses: irongut/CodeCoverageSummary@v1.3.0
+        with:
+          filename: "**/coverage.xml"
+          format: markdown
+          output: both
+          badge: true
+          fail_below_min: false
+          thresholds: "50 75"
+      - name: Add coverage PR comment
+        if: github.event_name == 'pull_request' && hashFiles('code-coverage-results.md') != ''
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: coverage
+          path: code-coverage-results.md
+
+  # ── Build ───────────────────────────────────────────────────
+
+  build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+    needs: [ruff, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  # ── Release (semantic-release on main push) ─────────────────
+
+  release:
+    name: Semantic release
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [ruff, test, build]
+    permissions:
+      contents: write
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install python-semantic-release build
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Bump version & tag
+        id: version
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          OUTPUT=$(semantic-release version --push --tag --commit 2>&1) || true
+          echo "$OUTPUT"
+          if echo "$OUTPUT" | grep -q "no release will be made"; then
+            echo "released=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "released=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Build distribution
+        if: steps.version.outputs.released == 'true'
+        run: python -m build
+      - name: Publish GitHub Release
+        if: steps.version.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: semantic-release publish
+      # 4. Publish to PyPI via trusted publishing (OIDC)
+      - name: Publish to PyPI
+        if: steps.version.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1

orchid_cli-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Ruff
+.ruff_cache/
+
+# pytest
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# SQLite (local dev databases)
+*.db
+*.sqlite3
+
+# mypy
+.mypy_cache/

orchid_cli-0.1.0/.gitlint

@@ -0,0 +1,15 @@
+# Gitlint — enforce Conventional Commits for semantic-release
+# https://jorisroovers.com/gitlint/
+
+[general]
+contrib = contrib-title-conventional-commits
+ignore = merge-commit,revert-commit
+
+[title-max-length]
+line-length = 72
+
+[body-max-line-length]
+line-length = 120
+
+[contrib-title-conventional-commits]
+types = feat,fix,perf,refactor,docs,style,test,build,ci,chore

orchid_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+# Pre-commit hooks — run automatically before each commit
+# Install: pip install pre-commit && pre-commit install
+# Manual:  pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/jorisroovers/gitlint
+    rev: v0.19.1
+    hooks:
+      - id: gitlint

orchid_cli-0.1.0/AGENTS.md

@@ -0,0 +1,130 @@
+# orchid-cli — AI Context
+
+## What This Package Is
+
+**orchid-cli** is the Typer-based command-line interface for the Orchid multi-agent AI framework. It imports `orchid` (the library) as a dependency and provides terminal access to all chat operations, config validation, RAG indexing, and Claude Code skill generation. It mirrors the full functionality of `orchid-api` but runs locally with no server, Docker, or external database required (defaults to SQLite).
+
+## Package Structure
+
+```
+orchid-cli/
+  orchid_cli/
+    main.py          Typer entry point — registers sub-commands
+    bootstrap.py     Shared startup: load config, build graph, init SQLite storage
+    commands/
+      chat.py        Full CRUD: create, list, delete, history, send, interactive, rename, share
+      config.py      validate command (checks agents.yaml)
+      index.py       seed command (batch-index RAG data)
+      skill.py       generate command (Claude Code skills from agents.yaml)
+  pyproject.toml
+```
+
+## Key Dependencies
+
+| Package | Role |
+|---------|------|
+| `orchid` | Core framework (agents, graph, RAG, persistence) |
+| `typer` | CLI framework |
+| `rich` | Terminal formatting |
+| `pyyaml` | YAML config loading |
+| `pydantic-settings` | Environment config |
+| `httpx` | Async HTTP (for MCP calls) |
+| `langchain-core` | LangGraph message types |
+
+## Architecture Rules (Apply When Editing This Package)
+
+1. **This is a thin CLI layer.** It calls `orchid` SDK functions and displays results. Business logic belongs in `orchid/`, not here.
+
+2. **`bootstrap.py` mirrors `orchid-api/main.py:lifespan()`.** Both load config, build the graph, and initialize storage. Keep them in sync when adding new startup steps.
+
+3. **`OrchidContext` dataclass holds runtime state.** Created once by `bootstrap()`, passed to commands. Contains: `graph`, `reader`, `chat_repo`, `config`, `model`.
+
+4. **Default storage is SQLite** at `~/.orchid/chats.db` (no Docker, no PostgreSQL needed). Overridable via `CHAT_STORAGE_CLASS` and `CHAT_DB_DSN` env vars.
+
+5. **No agent or framework code here.** No `BaseAgent` subclasses, no graph wiring, no RAG logic. Those belong in `orchid/` or consumer projects.
+
+6. **Config resolution:** CLI args > env vars > `orchid.yml` > hardcoded defaults.
+
+## Commands
+
+```bash
+# Chat operations
+orchid chat create    --config <path>          # Create new chat session
+orchid chat list      --config <path>          # List all chats
+orchid chat delete    --config <path> <id>     # Delete a chat
+orchid chat history   --config <path> <id>     # Show chat messages
+orchid chat send      --config <path> "msg"    # Send single message
+orchid chat interactive --config <path>        # Interactive REPL mode
+orchid chat rename    --config <path> <id>     # Rename a chat
+orchid chat share     --config <path> <id>     # Promote RAG to user scope
+
+# Config
+orchid config validate <agents.yaml>           # Validate agent config
+
+# RAG indexing
+orchid index seed     --config <path>          # Batch-index RAG data
+
+# Skill generation (Claude Code)
+orchid skill generate <agents.yaml>            # Generate Claude Code skills
+orchid skill generate <agents.yaml> -o ./out   # Custom output directory
+orchid skill generate <agents.yaml> --include agent1,agent2  # Filter by name
+orchid skill generate <agents.yaml> --overwrite              # Overwrite existing
+orchid skill generate <agents.yaml> --zip                    # Create zip archive
+```
+
+### Interactive Mode Slash Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/switch <id>` | Switch to another chat |
+| `/list` | List all chats |
+| `/new` | Create new chat |
+| `/history` | Show current chat history |
+| `/rename <name>` | Rename current chat |
+| `/quit` | Exit interactive mode |
+
+Chat ID prefix matching is supported (type first few chars of UUID).
+
+## Bootstrap Defaults
+
+| Parameter | Default | Env Override |
+|-----------|---------|-------------|
+| LLM model | `ollama/llama3.2` | `LITELLM_MODEL` |
+| Vector backend | `qdrant` | `VECTOR_BACKEND` |
+| Qdrant URL | `http://qdrant:6333` | `QDRANT_URL` |
+| Embedding model | `text-embedding-3-small` | `EMBEDDING_MODEL` |
+| Storage class | `orchid_ai.persistence.sqlite.SQLiteChatStorage` | `CHAT_STORAGE_CLASS` |
+| Storage DSN | `~/.orchid/chats.db` | `CHAT_DB_DSN` |
+
+## Running
+
+```bash
+# Install:
+pip install -e ../orchid -e .
+
+# Quick test:
+orchid chat send "Tell me about LeBron" --config ../examples/basketball/orchid.yml
+
+# Interactive session:
+orchid chat interactive --config ../examples/basketball/orchid.yml
+
+# Validate config:
+orchid config validate ../examples/basketball/agents.yaml
+```
+
+Requires Ollama running on host with models: `llama3.2`, `nomic-embed-text`.
+
+## Code Style
+
+- Python 3.11+, Ruff, line length 120
+- `from __future__ import annotations` in every file
+- Imports: `from orchid_ai.xxx` (never `from src.xxx`)
+- All async operations use `asyncio.run()` or Typer's async support
+- No vendor-specific code — platform integrations belong in consumers
+
+## Common Pitfalls
+
+- The `--config` flag points to `orchid.yml` (top-level config), not `agents.yaml`. The agents config path is resolved from `AGENTS_CONFIG_PATH` inside `orchid.yml`.
+- `bootstrap()` sets `ORCHID_CONFIG` as an env var so the orchid library can find the YAML. Don't remove this.
+- Chat persistence auto-creates `~/.orchid/chats.db` on first run. The directory is created automatically.
+- Embedding dimension mismatch (768 vs 1536 vs 3072) causes silent retrieval failures. Switching models requires re-indexing Qdrant.

orchid_cli-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

orchid_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to orchid-cli
+
+## Development Setup
+
+```bash
+cd orchid-cli
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ../orchid -e ".[dev]"
+pre-commit install
+```
+
+The last command installs git hooks that **automatically run ruff (lint + format) and gitlint (commit message check) before every commit**.
+
+## Commit Message Convention
+
+This project uses **[Conventional Commits](https://www.conventionalcommits.org/)** to enable automatic semantic versioning. Every commit message must follow this format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+| Type | Description | Version Bump |
+|------|-------------|-------------|
+| `feat` | New feature | **minor** (0.X.0) |
+| `fix` | Bug fix | **patch** (0.0.X) |
+| `perf` | Performance improvement | **patch** (0.0.X) |
+| `refactor` | Code refactor (no feature/fix) | none |
+| `docs` | Documentation only | none |
+| `style` | Formatting, whitespace | none |
+| `test` | Adding/updating tests | none |
+| `build` | Build system, dependencies | none |
+| `ci` | CI/CD configuration | none |
+| `chore` | Maintenance tasks | none |
+
+### Breaking Changes
+
+Append `!` after the type or add `BREAKING CHANGE:` in the footer for a **major** bump:
+
+```
+feat!: rename orchid chat send to orchid chat message
+```
+
+### Examples
+
+```
+feat(commands): add orchid chat export command
+fix(bootstrap): handle missing orchid.yml gracefully
+docs: update command reference in README
+test(chat): add interactive mode edge case tests
+ci: add coverage reporting to GitLab pipeline
+```
+
+### Validation
+
+Commit messages are validated in CI via [gitlint](https://jorisroovers.com/gitlint/). To check locally:
+
+```bash
+pip install gitlint
+gitlint
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -x                       # all tests
+pytest tests/ --cov=orchid_cli         # with coverage
+ruff check orchid_cli/                 # lint
+ruff format orchid_cli/                # format
+```
+
+## Merge Requests
+
+1. Create a feature branch from `main`
+2. Use conventional commit messages
+3. Ensure tests pass and linting is clean
+4. Keep MRs focused -- one feature or fix per MR

orchid_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Orchid Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orchid_cli-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: orchid-cli
+Version: 0.1.0
+Summary: Orchid CLI — command-line interface for the Orchid agent framework
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: orchid-ai>=1.1.0
+Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: gitlint>=0.19.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'