pykel 1.0.0__tar.gz

pykel-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report something that isn't working as expected
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear, concise description of what's wrong.
+
+**To Reproduce**
+Minimal code to reproduce the behavior:
+
+```python
+# your repro here
+```
+
+**Expected behavior**
+What you expected to happen instead.
+
+**Environment**
+- kel version: `python -c "import kel; print(kel.__version__)"`
+- Python version:
+- OS:
+- Relevant extras installed (e.g. `kel[qdrant]`):
+
+**Additional context**
+Anything else that might help — logs, tracebacks, related issues.

pykel-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/kprasad7/kel/security/advisories/new
+    about: Please report security vulnerabilities privately, not as a public issue.

pykel-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest a new capability or improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+**What problem does this solve?**
+Describe the use case — what are you trying to build, and what's missing?
+
+**Proposed solution**
+What would the API/behavior look like? A sketch is great:
+
+```python
+# how you'd want to use it
+```
+
+**Alternatives considered**
+Any workarounds you're using today, or other approaches you thought about.
+
+**Additional context**
+Links to similar features in other frameworks, related issues, etc.

pykel-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+## Checklist
+
+- [ ] `ruff check src tests` passes
+- [ ] `mypy src` passes
+- [ ] `pytest -q` passes
+- [ ] New/changed provider or vector-store adapters remain credentials-optional (work via env vars / ambient cloud credentials with no explicit key)
+- [ ] Tests added or updated for the change
+- [ ] Docs (`README.md`/`USAGE.md`/`CHANGELOG.md`) updated if user-facing behavior changed
+
+## Related issues
+
+<!-- e.g. Closes #123 -->

pykel-1.0.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

pykel-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install kel (dev)
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src tests
+
+      - name: mypy
+        run: mypy src
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install kel (dev)
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q

pykel-1.0.0/.github/workflows/security.yml

@@ -0,0 +1,92 @@
+name: DevSecOps
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+  schedule:
+    # weekly, so newly-disclosed CVEs in already-merged dependencies get
+    # caught even when nobody pushes new code that week
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  trivy-scan:
+    name: Trivy (vulnerabilities, secrets, misconfig)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Trivy filesystem scan (report, non-blocking)
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln,secret,misconfig
+          format: sarif
+          output: trivy-results.sarif
+          severity: CRITICAL,HIGH,MEDIUM
+          exit-code: "0"
+
+      - name: Upload results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: trivy-results.sarif
+
+      - name: Fail build on CRITICAL findings
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln,secret
+          severity: CRITICAL
+          exit-code: "1"
+
+  pip-audit:
+    name: pip-audit (known CVEs in dependencies)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Upgrade pip
+        run: pip install --upgrade pip
+
+      - name: Install kel with all extras
+        run: pip install -e ".[all]"
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Run pip-audit
+        # GHSA-f4j7-r4q5-qw2c / PYSEC-2026-311 (chromadb): pre-auth code
+        # injection in a *running Chroma server* via trust_remote_code=true
+        # on the collections endpoint. kel only ships a chromadb client
+        # adapter (kel.retrieval.chroma_store) — it never runs a Chroma
+        # server or sets that flag — so this finding doesn't apply here.
+        # No fixed chromadb version exists yet (affects 1.0.0 through
+        # latest); revisit and drop this ignore once one ships.
+        run: pip-audit --ignore-vuln GHSA-f4j7-r4q5-qw2c
+
+  bandit:
+    name: Bandit (Python SAST)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Bandit
+        run: pip install bandit
+
+      - name: Run Bandit (medium severity and above)
+        run: bandit -r src/kel -ll -f txt

pykel-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+.env

pykel-1.0.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project 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).
+
+## [Unreleased]
+
+### Added
+- PEP 561 `py.typed` marker and dynamic single-sourced versioning.
+- PyPI metadata: classifiers, keywords, `project.urls`.
+- Ruff lint and mypy type-check jobs in CI.
+- ASCII banner shown by the `kel` CLI (`kel --version` / bare `kel`).
+- CHANGELOG, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY docs and GitHub issue/PR templates.
+
+## [0.1.0] - 2026-07-24
+
+### Added
+- Core model gateway with Anthropic, OpenAI, Cohere, Gemini, and Mistral adapters — all credentials-optional by design (env vars / ambient cloud credentials work with no explicit key).
+- Observability (tracer, spans, sinks), budget tracking, rate limiting, and response caching.
+- Context window management and memory (episodic + semantic) subsystems.
+- Retrieval: Qdrant, Pinecone, Weaviate, Chroma, and pgvector vector stores; recursive text splitter; PDF loader.
+- Agent runtime with graph-based execution, streaming, human-in-the-loop interrupts, and structured output.
+- Tooling: web fetch (SSRF-hardened), web search, SQL, and shell tools.
+- Testing utilities: cassette recording/replay, LLM-graded evals, span/trace assertions.
+- Storage: file/S3 blob storage, checkpointing (hardened against unsafe deserialization).
+- Lightweight, stdlib-only monitoring dashboard with live-refreshing metrics.
+- `.md`-based agent specs, CLI (`run`/`eval`/`trace`), and `serve()` HTTP runtime.
+- DevSecOps pipeline: Trivy, pip-audit, and Bandit scanning; Dependabot.
+
+[Unreleased]: https://github.com/kprasad7/kel/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/kprasad7/kel/releases/tag/v0.1.0

pykel-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,54 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+our community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards
+of acceptable behavior and will take appropriate, fair corrective action
+in response to any behavior deemed inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, pull
+requests, discussions) and when an individual is officially representing
+the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers via a GitHub issue marked confidential or by
+contacting the repository owner directly through GitHub. All complaints
+will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

pykel-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to kel
+
+Thanks for considering a contribution. This project is young, so small,
+focused pull requests are the easiest to review and merge.
+
+## Getting set up
+
+```bash
+git clone https://github.com/kprasad7/kel.git
+cd kel
+python -m venv .venv
+. .venv/Scripts/activate   # Windows; use `source .venv/bin/activate` on macOS/Linux
+pip install -e ".[dev]"
+```
+
+## Before opening a PR
+
+Run the same checks CI runs:
+
+```bash
+ruff check src tests
+mypy src
+pytest -q
+```
+
+All three must pass. If you touch a provider or vector-store adapter that
+requires a third-party SDK, install it via the relevant extra (e.g.
+`pip install -e ".[qdrant]"`) and add tests against an injected fake
+client — tests should never require live credentials or a live account.
+
+## Guidelines
+
+- **Credentials stay optional.** Every provider/store adapter must work
+  when no explicit API key is passed, falling back to environment
+  variables or ambient cloud credentials (IAM role, Workload Identity,
+  IRSA). Don't add a required-key check that breaks that path.
+- **No new abstractions for their own sake.** kel's whole pitch is fewer
+  layers than the alternatives — prefer a direct implementation over a new
+  interface unless at least two call sites need it.
+- **Security-sensitive changes** (deserialization, subprocess/shell
+  execution, URL fetching, SQL construction) need a one-line comment
+  explaining why the operation is safe, not just that it works.
+- **Docstrings over comments** for adapters: explain what real-world
+  deployment scenario a design choice serves (e.g. "works under EKS IRSA
+  with no key at all"), not what the code does line by line.
+
+## Reporting bugs / requesting features
+
+Open a [GitHub issue](https://github.com/kprasad7/kel/issues). For
+security vulnerabilities, see [SECURITY.md](SECURITY.md) instead of
+filing a public issue.