shackle 0.1.0__tar.gz

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

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type-check with mypy
+        run: mypy src/shackle/
+
+      - name: Run tests
+        run: pytest --cov=shackle --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false

shackle-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

shackle-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.env.*
+*.log
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.tox/
+.nox/
+.hypothesis/
+*.mo
+*.pot
+*.swp
+*~
+.DS_Store
+Thumbs.db
+.claude/
+
+# Internal — never push to public repo
+CLAUDE.md
+ROADMAP.md
+BACKLOG.md
+docs/ideology/
+docs/development/
+mdfiles/

shackle-0.1.0/CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to ShackleAI are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-02-18
+
+### Added
+- MkDocs Material documentation site (`mkdocs.yml`, docs index, examples index)
+- GitHub Actions CI workflow: test, lint, type-check on push (Python 3.12 + 3.13)
+- GitHub Actions release workflow: publish to PyPI on tag via trusted publisher (OIDC)
+- `docs` optional dependency group (`mkdocs-material`, `mkdocstrings[python]`)
+- README badges (PyPI version, Python versions, license, CI status)
+
+### Changed
+- `pyproject.toml` URLs updated to `shackle-ai/shackle` GitHub org
+- Documentation URL changed to GitHub Pages (`shackle-ai.github.io/shackle`)
+- README: added `init`, `validate`, `cost`, `logs` CLI commands; added Documentation section
+- Author email updated to `useshackleai@gmail.com`
+
+### Fixed
+- 5 ruff violations in test files (unused imports, import sorting)
+
+## [0.1.0-alpha.8] — 2026-02-18
+
+### Added
+- 3 complete example projects:
+  - `01_research_writer/` — sequential, 2 agents (research then write)
+  - `02_parallel_analysis/` — parallel, 3 agents (market, tech, finance)
+  - `03_hierarchical_fleet/` — hierarchical, manager + 3 workers
+- Getting Started guide (`docs/getting-started.md`) — zero to running in 5 minutes
+- Concepts documentation: agents.md, voyages.md, fleets.md, tools.md
+
+### Changed
+- Examples restructured from flat files to self-contained directories (main.py, shackle.yaml, README.md)
+- Example 03 uses fleet/voyages YAML format with `${SHACKLE_LLM_MODEL:-gpt-4o-mini}` env var interpolation
+
+## [0.1.0-alpha.7] — 2026-02-18
+
+### Added
+- Environment variable interpolation in YAML: `${VAR}` and `${VAR:-default}` syntax
+- Fleet/voyages YAML format: `voyages` list with `cargo` (tasks), `mode`, and `fleet.name`
+- `model` alias for `llm_model` in YAML agent definitions
+- Pydantic schema validation for workflow YAML (`config/schema.py`)
+- Schema validates agent references in tasks and cargo
+- `discover_config()`: walks up directories to find `shackle.yaml`
+- 23 new tests (321 total, 98.32% coverage)
+
+### Changed
+- `load_workflow()` now interpolates env vars before YAML parsing
+- `load_workflow()` validates data against Pydantic schema before building Voyage
+- `config/__init__.py` exports `discover_config`
+
+## [0.1.0-alpha.6] — 2026-02-18
+
+### Added
+- CLI `shackle init <name>`: scaffolds new project with shackle.yaml, main.py, .env.example, README.md
+- CLI `shackle validate <file>`: validates YAML workflow with Rich error output
+- CLI `shackle cost <file>`: estimates LLM cost per agent with pricing table
+- CLI `shackle logs`: displays filtered Ship's Log entries from structlog output
+- CLI `shackle sail --voyage <name>`: named voyage selection from YAML
+- `cli/templates.py`: scaffold templates for `shackle init`
+- `cli/output.py`: Rich formatting helpers (agent_color, print_voyage_result, print_cost_estimate)
+- YAML tool resolution: agents with `tools: [file_read, web_search]` get real Tool instances (CO-1)
+- Tool execution logging: duration_s and output_len logged on every tool call (CO-2)
+- 30 new tests (298 total, 98.26% coverage)
+
+### Changed
+- `cli/app.py` rewritten with all commands (init, sail, validate, cost, logs, serve, version)
+- `config/yaml_loader.py`: `_parse_agents()` resolves tool names via registry
+- `tools/base.py`: `execute()` logs timing with `time.monotonic()`
+- `engine/__init__.py`: docstring clarifies orchestration lives in `voyage.py` by design (CO-3)
+
+### Fixed
+- CO-1: YAML loader now resolves tool names to Tool instances
+- CO-2: Tool.execute() now logs duration and output length per CLAUDE.md rule #13
+- CO-3: engine/ package docstring updated to explain architecture intent
+
+## [0.1.0-alpha.5] — 2026-02-18
+
+### Added
+- Tool model: `requires_approval` (bool), `timeout` (int), `category` (Literal) fields
+- Tool timeout enforcement via `asyncio.wait_for()` in `Tool.execute()`
+- `ToolCategory` type alias for category validation
+- 7 Tier 1 built-in tools: `file_read`, `file_write`, `web_search`, `code_execute`, `http_request`, `directory_list`, `json_parse`
+- Path sandboxing in file tools (prevents directory traversal attacks)
+- Tool registry: `get_builtin_tool(name)` and `list_builtin_tools()`
+- All built-in tools have `category="builtin"`
+- 100 new tests (268 total, 98.44% coverage)
+
+### Changed
+- `@tool` decorator accepts `requires_approval`, `timeout`, `category` parameters
+- `Tool.execute()` delegates to `Tool._invoke()` for timeout wrapping
+- `tools/__init__.py` expanded with registry and all built-in tool re-exports
+
+## [0.1.0-alpha.4] — 2026-02-18
+
+### Added
+- `on_failure` strategy enforcement: `"stop"` (abort), `"retry"` (retry up to max_retries), `"skip"` (mark as skipped, continue)
+- Task-level timeout: `asyncio.wait_for()` wraps agent execution, configurable via `task.timeout`
+- Voyage-level timeout: wraps entire `sail()` execution, configurable via `voyage.timeout`
+- Agent cost limit enforcement: raises `CostLimitError` when cumulative LLM cost exceeds `agent.cost_limit`
+- `TaskStatus.SKIPPED` enum value for skip strategy
+- `Voyage.timeout` field (0 = no limit)
+- `Voyage._run_task()` helper: unified task execution with retry/skip/timeout handling
+- 14 new tests (168 total, 98.90% coverage)
+
+## [0.1.0-alpha.3] — 2026-02-18
+
+### Changed
+- Reorganized flat `src/shackle/` into subdirectory layout per ideology Section 9
+- New packages: `core/`, `engine/`, `llm/`, `tools/`, `observability/`, `config/`
+- All subpackage `__init__.py` files provide re-exports (public API unchanged)
+- Internal imports use full subpackage paths (`from shackle.core.agent import Agent`)
+- `from shackle import Agent, Task, Voyage` continues to work (zero breaking changes)
+
+## [0.1.0-alpha.2] — 2026-02-18
+
+### Added
+- Agent: `cost_limit` (max USD per execution), `verbose` (detailed logging)
+- Task: `timeout` (seconds before timeout), `output_schema` (Pydantic structured output)
+- Voyage: `on_failure` (stop/retry/skip strategy), `max_retries`, `metadata`
+- Fleet: `voyages` (available voyage names), `config` (fleet-level settings)
+- Pin: `from_agent`, `to_agent`, `status` (pending/delivered/acknowledged), `trace_id`
+- Memory: `backend` (local/redis/postgresql), `context_window`, `persistent`
+- VoyageResult: `total_tokens`, `trace_id`, `pins`, `agent_logs`, `computed_total_tokens`
+- 32 new tests (154 total, 98.81% coverage)
+- Ruff baseline: clean (0 violations)
+- MyPy baseline: clean (0 errors, strict mode)
+
+### Changed
+- Ruff config: added `runtime-evaluated-base-classes` for Pydantic, ignored B008 for Typer
+- Import cleanup: TYPE_CHECKING blocks, `collections.abc`, `datetime.UTC`
+
+## [0.1.0-alpha.1] — 2024-12-01
+
+### Added
+
+**Core Framework**
+- `Agent` class: LLM-powered worker with role, goal, backstory, tools, and memory
+- `Task` class: unit of work with description, expected output, context chaining
+- `Voyage` class: orchestrator with `sail()` entry point
+- `Fleet` class: agent group with captain/recruit/get_agent
+- `Tool` class: wraps sync/async callables with OpenAI function-calling schema
+- `@tool` decorator: auto-infers JSON Schema from function signatures
+- `Pin` / `PinBoard`: voyage checkpoints for execution audit trail
+- `Memory`: two-tier short-term + long-term agent memory with keyword search
+
+**Orchestration**
+- Sequential execution mode with automatic context chaining
+- Parallel execution mode via `asyncio.gather()`
+- Hierarchical execution mode with captain oversight
+
+**LLM Integration**
+- `LLMClient`: async wrapper around LiteLLM supporting 100+ providers
+- `CostTracker`: async-safe per-call and per-voyage cost accumulation
+- `CostLimitError`: automatic budget enforcement
+- Retry logic: 3 attempts with exponential backoff via tenacity
+
+**Interfaces**
+- FastAPI REST API: `/health`, `/voyages/sail`, `/voyages/sail-from-workflow`
+- Typer CLI: `shackle sail`, `shackle serve`, `shackle version`
+- YAML workflow loader: declarative voyage definitions
+
+**Observability**
+- structlog integration: JSON and console output modes
+- OpenTelemetry tracing: spans on LLM calls, tool execution, voyage runs
+- Environment-based configuration via `SHACKLE_*` variables
+
+**Quality**
+- 122 tests, 98.77% code coverage
+- Full LLM mocking strategy (zero real API calls in tests)
+- PEP 561 type stubs (py.typed marker)
+- Apache 2.0 license
+
+**Documentation**
+- Platform ideology document
+- Architecture Decision Records
+- Maritime terminology reference
+- Stage-by-stage development documentation
+- Competitive positioning analysis
+- Contributing guide
+
+### Maritime Terminology
+- Fleet (not crew), Voyage (not workflow), Pin (not message)
+- `voyage.sail()` (not run/execute)
+- `DistressError` (not CrewError)
+- Health endpoint returns `{"status": "seaworthy"}`
+- Voyage statuses: docked, sailing, arrived, wrecked

shackle-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to ShackleAI
+
+Thank you for your interest in contributing to ShackleAI. This guide will help you get started.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/shackleai/shackle.git
+cd shackle
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Verify installation
+pytest
+shackle version
+```
+
+## Code Standards
+
+### Maritime Terminology
+All code, docs, and user-facing text must use maritime terminology. See `docs/ideology/TERMINOLOGY.md` for the complete reference.
+
+**Critical**: Never use "Crew" — this term belongs to CrewAI.
+
+### Python Style
+- Python 3.11+ required
+- Async-first: all orchestration code must be async
+- Pydantic v2 BaseModel for all data classes
+- Type hints on all functions and methods
+- Docstrings on every class and public method
+- `__all__` exports on every module
+
+### Linting & Formatting
+```bash
+ruff check src/ tests/          # Lint
+ruff format src/ tests/         # Format
+mypy src/shackle/               # Type check
+```
+
+## Testing
+
+### Requirements
+- **>90% test coverage** — enforced by CI
+- Unit tests for every class and method
+- Mock all LLM calls — never hit real APIs in tests
+- Test failure modes, not just happy paths
+
+### Running Tests
+```bash
+pytest                           # Full suite with coverage
+pytest -x                        # Stop on first failure
+pytest tests/test_agent.py -v    # Single module
+pytest -k "test_sail"            # Filter by name
+```
+
+### Writing Tests
+```python
+# Use the fixtures from conftest.py
+async def test_my_feature(researcher, mock_llm_client):
+    # mock_llm_client.complete is already an AsyncMock
+    task = Task(description="...", expected_output="...")
+    result = await researcher.execute(task)
+    assert result.status == TaskStatus.COMPLETED
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Write tests first (TDD encouraged)
+4. Implement the feature
+5. Ensure all tests pass and coverage is >90%
+6. Run linting: `ruff check src/ tests/`
+7. Submit a PR with a clear description
+
+### PR Title Convention
+- `feat: add timeout support for tasks`
+- `fix: correct cost tracking for parallel voyages`
+- `docs: update terminology reference`
+- `test: add integration tests for hierarchical mode`
+- `refactor: move core models to core/ subpackage`
+
+## Architecture
+
+Before making significant changes, read:
+- `docs/ideology/IDEOLOGY.md` — Platform vision and standards
+- `docs/ideology/ARCHITECTURE.md` — Architecture Decision Records
+- `docs/development/08-ALIGNMENT-GAPS.md` — Known gaps and roadmap
+
+## Questions?
+
+Open an issue on GitHub with the "question" label.

shackle-0.1.0/LICENSE

@@ -0,0 +1,113 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work.
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to the Licensor for inclusion in the Work by the copyright
+   owner or by an individual or Legal Entity authorized to submit on
+   behalf of the copyright owner.
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by the Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file.
+
+5. Submission of Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty.
+
+8. Limitation of Liability.
+
+9. Accepting Warranty or Additional Liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2024 ShackleAI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.