ai-knot 0.3.0__tar.gz

ai_knot-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Something doesn't work as expected
+labels: bug
+---
+
+## Environment
+
+- OS: <!-- e.g. macOS 14, Ubuntu 22.04, Windows 11 -->
+- Python version: <!-- e.g. 3.11.9 -->
+- ai-knot version: <!-- e.g. 0.1.0 — run `ai-knot --version` or `pip show ai-knot` -->
+- Storage backend: <!-- yaml / sqlite / postgres -->
+- LLM provider: <!-- openai / anthropic / yandex / gigachat / qwen / openai-compat -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behaviour
+
+<!-- What should happen -->
+
+## Actual behaviour
+
+<!-- What actually happens — include the full traceback if there is one -->
+
+```
+paste error output here
+```
+
+## Minimal reproducing example
+
+```python
+# Paste the smallest snippet that triggers the bug
+```
+
+## Additional context
+
+<!-- Anything else that might be relevant: custom storage path, concurrent access, specific LLM model, etc. -->

ai_knot-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Propose a new feature or improvement
+labels: enhancement
+---
+
+## Problem
+
+<!-- What are you trying to do that ai-knot doesn't support yet?
+     Be specific: "I want to store facts in Redis" is better than "more backends". -->
+
+## Proposed solution
+
+<!-- How would you like it to work? Include API sketch if relevant. -->
+
+```python
+# Example of what the API could look like
+```
+
+## Alternatives considered
+
+<!-- What workarounds have you tried? Why don't they work for your case? -->
+
+## Would you be willing to implement this?
+
+- [ ] Yes, I can open a PR
+- [ ] I can help test/review
+- [ ] No, just reporting the need
+
+## Additional context
+
+<!-- Links, related issues, prior art in other libraries, etc. -->

ai_knot-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+## Summary
+
+<!-- What does this PR do? 2-3 bullet points. -->
+
+- 
+- 
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring (no functional change)
+- [ ] Documentation
+- [ ] CI / DevOps
+
+## Principal Python Developer review checklist
+
+> Reviewer applies `skills/principal_python_developer.md` before approving.
+
+- [ ] All public classes and functions have docstrings
+- [ ] `from __future__ import annotations` present in every new module
+- [ ] All type annotations correct and `mypy --strict` passes
+- [ ] No bare `except:` — specific exceptions only
+- [ ] No mutable default arguments (use `field(default_factory=...)`)
+- [ ] `StorageBackend` protocol fully satisfied (if storage changes)
+- [ ] No hardcoded secrets or absolute paths
+- [ ] `ruff check` and `ruff format --check` pass clean
+
+## Test checklist
+
+- [ ] New behaviour covered by unit tests
+- [ ] LLM calls mocked (no real API calls in tests)
+- [ ] Storage tests include round-trip + multi-agent isolation
+- [ ] `pytest --cov-fail-under=80` passes
+- [ ] Both YAML and SQLite backends tested (if storage-related)
+
+## Documentation
+
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Docstrings updated for changed public API
+- [ ] `ARCHITECTURE.md` updated if new layer or extension point added
+
+## Screenshots / output (if applicable)
+
+<!-- Paste CLI output or relevant logs -->

ai_knot-0.3.0/.github/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in ai-knot, please report it responsibly:
+
+1. **Do not** open a public issue.
+2. Email the maintainers or open a private security advisory via
+   [GitHub Security Advisories](https://github.com/alsoleg89/ai-knot/security/advisories/new).
+3. Include a description of the vulnerability, steps to reproduce, and potential impact.
+
+We will acknowledge receipt within 48 hours and aim to release a fix within 7 days
+for critical issues.
+
+## Scope
+
+- ai-knot library code (`src/ai_knot/`)
+- CLI interface
+- Storage backends (YAML, SQLite, PostgreSQL)
+- LLM provider integrations
+
+## Out of Scope
+
+- Vulnerabilities in third-party dependencies (report upstream)
+- Issues requiring physical access to the machine
+- Social engineering attacks

ai_knot-0.3.0/.github/workflows/benchmark.yml

@@ -0,0 +1,41 @@
+name: Benchmarks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    name: Performance Benchmarks
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run benchmarks
+        run: |
+          pytest tests/test_performance.py -m slow \
+            --benchmark-json=benchmark.json \
+            --benchmark-min-rounds=5 \
+            -v --no-cov
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results-${{ github.run_id }}-${{ github.sha }}
+          path: benchmark.json
+          retention-days: 90
+

ai_knot-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Mypy
+        run: mypy src/ai_knot/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,openai,mcp]"
+
+      - name: Run tests
+        run: |
+          if [ "${{ matrix.python-version }}" = "3.12" ]; then
+            pytest -n auto --timeout=10 -m "not slow" \
+              --cov=ai_knot --cov-report=xml --cov-report=term-missing
+          else
+            pytest -n auto --timeout=10 -m "not slow" --no-cov
+          fi
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  test-npm:
+    name: Test (TypeScript)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: npm
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: npm/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm test
+
+  test-e2e:
+    name: E2E (MCP server)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,mcp]"
+
+      - name: Run E2E tests
+        # --no-cov: coverage is measured via subprocess, not import; 80% threshold would fail
+        run: pytest tests/test_mcp_e2e.py -v -m integration --no-cov

ai_knot-0.3.0/.github/workflows/npm-publish.yml

@@ -0,0 +1,32 @@
+name: Publish to npm
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: npm
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dev dependencies
+        run: npm ci
+        env:
+          AI_KNOT_SKIP_PYTHON_INSTALL: "1"
+
+      - name: Build (ESM + CJS)
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

ai_knot-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ai_knot-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Create Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.2.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate version format
+        run: |
+          if ! echo "${{ inputs.version }}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Error: version must be in X.Y.Z format (e.g. 0.2.0)"
+            exit 1
+          fi
+
+      - name: Create and push tag
+        run: |
+          git config user.name "alsoleg89"
+          git config user.email "155813332+alsoleg89@users.noreply.github.com"
+          git tag "v${{ inputs.version }}"
+          git push origin "v${{ inputs.version }}"

ai_knot-0.3.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+coverage.xml
+.coverage
+.coverage.*
+*.log
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.ai_knot/

ai_knot-0.3.0/.mlc-config.json

@@ -0,0 +1,29 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^https://shields\\.io"
+    },
+    {
+      "pattern": "^https://img\\.shields\\.io"
+    },
+    {
+      "pattern": "^https://github\\.com/.*/actions/workflows"
+    },
+    {
+      "pattern": "^https://pypi\\.org/project/ai-knot"
+    },
+    {
+      "pattern": "^http://localhost"
+    },
+    {
+      "pattern": "^https://github\\.com/alsoleg89/ai-knot/compare/"
+    },
+    {
+      "pattern": "^https://github\\.com/alsoleg89/ai-knot/releases/tag/"
+    }
+  ],
+  "timeout": "10s",
+  "retryOn429": true,
+  "retryCount": 3,
+  "aliveStatusCodes": [200, 206]
+}

ai_knot-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-PyYAML>=6.0
+          - httpx>=0.27
+        args: [--strict]

ai_knot-0.3.0/ARCHITECTURE.md

@@ -0,0 +1,157 @@
+# ai-knot — Architecture
+
+## Design goals
+
+| Goal | How |
+|---|---|
+| **Zero vendor lock-in** | Pluggable `StorageBackend` protocol |
+| **Zero mandatory cloud deps** | Only `click`, `pyyaml`, `httpx` required |
+| **Human-readable storage** | YAML files by default |
+| **Signal over noise** | LLM distillation + Ebbinghaus decay |
+| **Framework-agnostic** | Plain Python objects, no base classes to inherit |
+
+---
+
+## Layer diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  CLI (ai_knot.cli)          Integrations (*.integrations) │
+├─────────────────────────────────────────────────────────────┤
+│                  KnowledgeBase (ai_knot.knowledge)         │  ← public API
+├──────────────┬──────────────────┬───────────────────────────┤
+│  Extractor   │  TFIDFRetriever  │  apply_decay / forgetting  │
+│  (LLM calls) │  (TF-IDF search) │  (Ebbinghaus curve)        │
+├──────────────┴──────────────────┴───────────────────────────┤
+│              StorageBackend (protocol)                        │
+│  YAMLStorage          SQLiteStorage         (future: PG …)  │
+├─────────────────────────────────────────────────────────────┤
+│              Core types: Fact, MemoryType, ConversationTurn   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Dependency rules (no circular imports)
+
+```
+types  ←  storage  ←  forgetting
+                  ←  retriever
+                  ←  extractor
+                  ←  knowledge  ←  cli
+                                ←  integrations
+```
+
+`knowledge.py` is the top of the internal dependency graph.  
+Nothing in `storage/`, `forgetting.py`, or `retriever.py` may import from `knowledge.py`.
+
+---
+
+## Core types (`ai_knot.types`)
+
+### `Fact`
+The atomic unit of knowledge.
+
+| Field | Type | Description |
+|---|---|---|
+| `content` | `str` | Human-readable knowledge string |
+| `type` | `MemoryType` | `semantic` / `procedural` / `episodic` |
+| `importance` | `float` | 0.0–1.0; controls decay speed |
+| `retention_score` | `float` | Current Ebbinghaus score (updated on recall) |
+| `access_count` | `int` | Times retrieved — increases stability |
+| `tags` | `list[str]` | Optional labels |
+| `id` | `str` | 8-char UUID hex |
+| `created_at` | `datetime` | UTC |
+| `last_accessed` | `datetime` | UTC |
+
+### `MemoryType`
+`SEMANTIC` — facts about the world/user  
+`PROCEDURAL` — how the user wants things done  
+`EPISODIC` — specific past events  
+
+---
+
+## Storage layer
+
+### `StorageBackend` protocol
+
+```python
+def save(self, agent_id: str, facts: list[Fact]) -> None: ...
+def load(self, agent_id: str) -> list[Fact]: ...
+def delete(self, agent_id: str, fact_id: str) -> None: ...
+def list_agents(self) -> list[str]: ...
+```
+
+`save` is a **full replace** — the caller always loads, mutates, then saves.
+
+Backends are responsible for:
+- Namespacing by `agent_id`
+- Serialising all `Fact` fields including datetime with UTC timezone
+
+### YAMLStorage
+File layout: `{base_dir}/{agent_id}/knowledge.yaml`  
+Key: `fact.id` (8-char hex)  
+Human-readable, Git-trackable, editable by hand.
+
+### SQLiteStorage
+Single `.db` file. Schema:
+```sql
+CREATE TABLE facts (
+    id TEXT, agent_id TEXT,
+    content TEXT, type TEXT,
+    importance REAL, retention REAL,
+    access_count INTEGER, tags TEXT,
+    created_at TEXT, last_accessed TEXT,
+    PRIMARY KEY (agent_id, id)
+)
+```
+
+---
+
+## Forgetting curve (`ai_knot.forgetting`)
+
+```
+retention(t) = exp(−t / stability)
+
+stability = 168h × importance × (1 + ln(1 + access_count))
+```
+
+- `t` = hours since `last_accessed`
+- Base stability = 168 h (1 week) for `importance=1.0, access_count=0`
+- Applied via `apply_decay(facts)` **before** every retrieval in `KnowledgeBase.recall()`
+- After retrieval, `access_count` is incremented and `last_accessed` is updated → reinforcement
+
+---
+
+## Retrieval (`ai_knot.retriever`)
+
+`TFIDFRetriever.search(query, facts, top_k)` — zero external dependencies.
+Returns `list[tuple[Fact, float]]` — each tuple is `(fact, hybrid_score)`.
+
+Scoring:
+```
+hybrid_score = 0.6 × tfidf + 0.2 × retention_score + 0.2 × importance
+```
+
+TF-IDF is computed fresh per query (no index) — suitable for knowledge bases up to ~10k facts.
+
+`KnowledgeBase.recall_facts_with_scores()` exposes `(Fact, float)` pairs to callers that need
+relevance scores (e.g. integration adapters). `recall()` and `recall_facts()` unpack the scores
+internally and work as before.
+
+---
+
+## Extraction (`ai_knot.extractor`)
+
+`Extractor.extract(turns)` sends the conversation to an LLM and parses the returned JSON array of facts.  
+Supports `openai` and `anthropic` providers via `httpx`.  
+Deduplication: Jaccard word-similarity ≥ 0.8 → keep first occurrence.
+
+---
+
+## Extension points
+
+| What | Where | Interface |
+|---|---|---|
+| New storage backend | `src/ai_knot/storage/` | `StorageBackend` protocol |
+| New LLM provider | `Extractor._call_<provider>` | Returns `list[dict]` from LLM |
+| New integration | `src/ai_knot/integrations/` | Import `KnowledgeBase`, wrap |
+| New retriever | Replace `TFIDFRetriever` | `.search(query, facts, top_k)` |