specops-ai 0.2.0__tar.gz

specops_ai-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync
+      - run: uv run ruff check src/ tests/ examples/
+      - run: uv run ruff format --check src/ tests/ examples/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync
+      - run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest --cov=src/specops_ai --cov-report=term-missing --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

specops_ai-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # For trusted publishing to PyPI
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync
+      - run: uv run pytest
+      - run: uv build
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

specops_ai-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+.kiro/
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+coverage.xml
+.python-version

specops_ai-0.2.0/.specops/replays/async-demo.json

@@ -0,0 +1,21 @@
+{
+  "session_id": "async-demo",
+  "seed": 123,
+  "recorded_at": "2026-05-08T10:00:12.936257+00:00",
+  "calls": [
+    {
+      "func_name": "async_llm_call",
+      "args_hash": "d48b44f006b90439",
+      "result": "The result is 1",
+      "timestamp": "2026-05-08T10:00:12.948413+00:00",
+      "call_index": 0
+    },
+    {
+      "func_name": "async_llm_call",
+      "args_hash": "e4a14bfacad6c780",
+      "result": "The result is 3",
+      "timestamp": "2026-05-08T10:00:12.959633+00:00",
+      "call_index": 1
+    }
+  ]
+}

specops_ai-0.2.0/.specops/replays/demo-session.json

@@ -0,0 +1,25 @@
+{
+  "session_id": "demo-session",
+  "seed": 42,
+  "recorded_at": "2026-05-08T10:00:11.587987+00:00",
+  "calls": [
+    {
+      "func_name": "search",
+      "args_hash": "62d3caec26bba24c",
+      "result": [
+        "result_95",
+        "result_14",
+        "result_87"
+      ],
+      "timestamp": "2026-05-08T10:00:11.589353+00:00",
+      "call_index": 0
+    },
+    {
+      "func_name": "call_llm",
+      "args_hash": "4e06c0d3d19cecb7",
+      "result": "France's capital city is Paris.",
+      "timestamp": "2026-05-08T10:00:11.589450+00:00",
+      "call_index": 1
+    }
+  ]
+}

specops_ai-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,173 @@
+# Contributing to SpecOps
+
+Thank you for your interest in SpecOps! We use **spec-driven development** — every feature begins as a written specification before any code is written.
+
+## Development Workflow
+
+```
+1. Idea / Issue
+2. Write Spec (requirements → design → tasks)
+3. Review Spec (PR against docs/specs/)
+4. Implement (code follows the approved spec)
+5. Review Code (PR against src/)
+6. Ship
+```
+
+### Why Spec-First?
+
+- Forces clear thinking before coding
+- Creates shared understanding across contributors
+- Produces documentation as a side effect
+- Makes code review faster (reviewers already know the intent)
+- Enables AI agents to assist with implementation
+
+## How to Contribute
+
+### 1. Pick or Propose Work
+
+- Check [open issues](https://github.com/kripikroli/specops-ai/issues) for `good-first-issue` or `help-wanted`
+- Or open a new issue describing what you'd like to build
+
+### 2. Write a Spec
+
+Create a branch and add your spec to `docs/specs/`:
+
+```
+docs/specs/
+├── requirements.md    # What the system must do
+├── design.md          # How it will work (architecture)
+└── tasks.md           # Ordered implementation steps
+```
+
+**Spec templates:**
+
+<details>
+<summary>Requirements Template</summary>
+
+```markdown
+## Feature: [Name]
+
+### Problem
+What problem does this solve?
+
+### Requirements
+- FR-1: The system shall...
+- FR-2: The system shall...
+
+### Non-Requirements
+- What is explicitly out of scope
+
+### Success Criteria
+- How do we know this is done?
+```
+</details>
+
+<details>
+<summary>Design Template</summary>
+
+```markdown
+## Design: [Feature Name]
+
+### Approach
+High-level description of the solution.
+
+### API
+Public interface (functions, classes, decorators).
+
+### Internal Architecture
+How components interact.
+
+### Trade-offs
+What alternatives were considered and why this approach was chosen.
+```
+</details>
+
+<details>
+<summary>Tasks Template</summary>
+
+```markdown
+## Tasks: [Feature Name]
+
+### Prerequisites
+- What must exist before starting
+
+### Implementation Steps
+1. [ ] Step one — description
+2. [ ] Step two — description
+
+### Verification
+- How to confirm each step works
+```
+</details>
+
+### 3. Submit Spec PR
+
+Open a PR with your spec files. Label it `spec`. The team reviews the spec before implementation begins.
+
+### 4. Implement
+
+Once the spec is approved:
+
+1. Create a feature branch from `main`
+2. Follow the tasks in your spec
+3. Write tests alongside implementation
+4. Open a PR referencing the spec
+
+## Development Setup
+
+We use [**uv**](https://docs.astral.sh/uv/) as our package manager. See [DEVELOPMENT.md](DEVELOPMENT.md) for full details.
+
+```bash
+# Clone
+git clone https://github.com/kripikroli/specops-ai.git
+cd specops-ai
+
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies (creates .venv automatically)
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+## Code Standards
+
+- **Python 3.10+** minimum
+- **Ruff** for linting and formatting
+- **mypy** strict mode for type checking
+- **pytest** for all tests
+- Docstrings on all public APIs (Google style)
+- 80%+ test coverage for new code
+
+## CI Pipeline
+
+All PRs run through GitHub Actions:
+
+1. **Lint** — `ruff check` + `ruff format --check`
+2. **Type check** — `mypy src/`
+3. **Test** — `pytest` on Python 3.10, 3.11, 3.12 with coverage
+
+PRs must pass all checks before merge. See `.github/workflows/ci.yml`.
+
+## Commit Messages
+
+Use conventional commits:
+
+```
+feat: add @trace_agent decorator
+fix: handle async context propagation
+docs: update Phase 1 spec with token tracking
+test: add integration tests for OTel export
+```
+
+## Code of Conduct
+
+Be respectful, constructive, and collaborative. We're building tools to make agents reliable — let's be reliable to each other too.

specops_ai-0.2.0/DEVELOPMENT.md

@@ -0,0 +1,77 @@
+# Development Guide
+
+SpecOps uses [**uv**](https://docs.astral.sh/uv/) as its package manager.
+
+## Prerequisites
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## Getting Started
+
+```bash
+git clone https://github.com/kripikroli/specops-ai.git
+cd specops-ai
+uv sync          # Creates .venv, installs all deps + dev group
+```
+
+## Common Commands
+
+| Task | Command |
+|------|---------|
+| Install all deps | `uv sync` |
+| Add a runtime dependency | `uv add <package>` |
+| Add a dev dependency | `uv add --dev <package>` |
+| Remove a dependency | `uv remove <package>` |
+| Run tests | `uv run pytest` |
+| Run tests with coverage | `uv run pytest --cov=src/specops_ai` |
+| Lint | `uv run ruff check src/ tests/` |
+| Format | `uv run ruff format src/ tests/` |
+| Type check | `uv run mypy src/` |
+| Run any command in venv | `uv run <cmd>` |
+| Run a CLI tool without installing | `uvx <tool>` |
+| Build package | `uv build` |
+| Publish to PyPI | `uv publish` |
+| Update lockfile | `uv lock` |
+| Upgrade a dependency | `uv lock --upgrade-package <pkg>` |
+
+## Lockfile
+
+`uv.lock` is committed to the repository. This ensures all contributors and CI get identical dependency versions.
+
+After adding or removing dependencies, `uv.lock` updates automatically. Commit the updated lockfile with your change.
+
+## Python Version
+
+uv manages the Python version. The project requires Python 3.10+. To pin a specific version locally:
+
+```bash
+uv python pin 3.12
+```
+
+The `.python-version` file is gitignored — each developer can use their preferred minor version.
+
+## CI
+
+GitHub Actions runs on every push to `main` and on PRs:
+
+| Job | What it does | Command |
+|-----|-------------|---------|
+| **lint** | Ruff check + format | `uv run ruff check src/ tests/ examples/` |
+| **typecheck** | mypy strict | `uv run mypy src/` |
+| **test** | pytest on 3.10/3.11/3.12 | `uv run pytest --cov=src/specops_ai` |
+
+See `.github/workflows/ci.yml` for the full config.
+
+### Release
+
+Releases are triggered by pushing a version tag:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+This runs tests, builds the wheel, and publishes to PyPI via `.github/workflows/release.yml`.

specops_ai-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A-aron Paul Luminding
+
+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.