kognios 1.1.0__tar.gz

kognios-1.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,48 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear, concise description of what went wrong.
+
+## Minimal reproduction
+
+```python
+# paste the smallest snippet that reproduces the issue
+from kognios import Agent, AnthropicModel
+
+agent = Agent(model=AnthropicModel())
+agent.run("...")
+```
+
+## Expected behaviour
+
+What you expected to happen.
+
+## Actual behaviour
+
+What actually happened. Include the **full traceback** if applicable.
+
+```
+Traceback (most recent call last):
+  ...
+```
+
+## Environment
+
+| Item | Version |
+|---|---|
+| Python | `python --version` |
+| kognios | `pip show kognios` |
+| Provider | Anthropic / OpenAI / Groq / Gemini |
+| Model | e.g. claude-sonnet-4-6 |
+| OS | Windows / macOS / Linux |
+
+## Additional context
+
+Anything else that might help — screenshots, related issues, etc.

kognios-1.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature request
+about: Propose a new feature or improvement
+title: "[FEAT] "
+labels: enhancement
+assignees: ''
+---
+
+## Summary
+
+One sentence describing the feature.
+
+## Problem / motivation
+
+What problem does this solve? Who benefits?
+
+## Proposed solution
+
+Describe what the API / behaviour should look like. Code examples are great.
+
+```python
+# e.g.
+from kognios.models.cohere import CohereModel
+agent = Agent(model=CohereModel(), ...)
+```
+
+## Alternatives considered
+
+Other approaches you thought about and why you ruled them out.
+
+## Checklist
+
+- [ ] I've checked the [ROADMAP](../ROADMAP.md) — this isn't already planned
+- [ ] I've searched [existing issues](https://github.com/lavkeshdwivedi/kogniOS/issues) for duplicates
+- [ ] I'm willing to submit a PR for this (optional but appreciated!)

kognios-1.1.0/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Summary
+
+<!-- 1-3 bullet points describing what this PR does and why -->
+
+- 
+- 
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+- [ ] Refactor / cleanup
+
+## Testing
+
+<!-- Describe how you tested this change -->
+
+- [ ] Added / updated unit tests in `tests/`
+- [ ] All existing tests pass (`pytest tests/ -v`)
+- [ ] Linter passes (`ruff check kognios tests`)
+- [ ] Tested manually with a real provider (optional but helpful)
+
+## Checklist
+
+- [ ] My code follows the project's [coding conventions](CONTRIBUTING.md#coding-conventions)
+- [ ] I've updated the docstrings / README / CHANGELOG where appropriate
+- [ ] No new external dependencies added (or explained in the PR description)

kognios-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "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: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check kognios tests
+
+      - name: Format check
+        run: ruff format --check kognios tests
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

kognios-1.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Temp files
+*.b64.txt
+C*Tempreadme*.txt
+*Tempreadme*.txt
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# Databases
+*.db
+
+# OS
+.DS_Store
+Thumbs.db

kognios-1.1.0/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to Kogni·OS are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.1.0] — 2026-07-07
+
+### Added
+- **`kognios serve` streaming** — `POST /stream` SSE endpoint; each token delivered as `data: {"text": "..."}`, terminated with `data: [DONE]`.
+- **`kognios serve` session management** — `POST /session` creates a named session backed by `ShortTermMemory`; `POST /session/{id}/run` and `POST /session/{id}/stream` are stateful across turns; `DELETE /session/{id}` cleans up.
+- **`kognios serve --kb <db>`** — attach a `SQLiteKnowledge` knowledge base (created by `kognios ingest`) to the served agent; all endpoints (stateless and session) use it for RAG.
+- **`kognios serve` health endpoint** — `GET /health` returns `{"status": "ok", "provider": ..., "model": ...}`.
+- **All 8 providers in `kognios serve`** — mistral, cohere, and bedrock now available via `--provider`.
+- **`kognios eval <dataset.json>`** — CLI command to run a JSON eval dataset against any provider/model; supports `--scorer contains|exact_match|regex_match` and `--threshold`.
+- **`kognios ingest <file>`** — CLI command to ingest documents (plain text, PDF, HTML, CSV, JSON, DOCX, URL) into a persistent SQLite knowledge base (`--backend fts|vector`). Reports chunk count on completion.
+- **Smart fact injection** — `Agent._build_system` calls `LongTermMemory.semantic_recall(query, top_k=5)` instead of `all_facts()` when `embed_fn` is set, so only query-relevant facts enter the system prompt.
+- **`LongTermMemory` safe as agent memory** — `Agent.run` and `arun` now guard `memory.append` with `hasattr`, so `LongTermMemory` can be passed as the `memory` argument without raising `AttributeError`.
+- **`KnowledgeBase.load()` returns chunk count** — `SQLiteKnowledge.load()` and `NumpyVectorKnowledge.load()` now return `int` (number of chunks stored).
+
+---
+
+## [Unreleased — pre-1.1 additions]
+
+### Added
+- **Prometheus Tracer sink** — `prometheus_sink()` factory in `kognios/tracing.py`.
+  Records span duration as `kognios_span_duration_seconds` (Histogram) and errors as
+  `kognios_span_errors_total` (Counter), both labelled by `span.name`.
+  Requires `prometheus-client>=0.17`; install via `pip install 'kognios[prometheus]'`.
+  New `prometheus` optional extra added to `pyproject.toml`; also included in `[all]`.
+- **Redis memory plugin example** — `examples/redis_memory_plugin/` with a
+  `RedisLongTermMemory` class duck-typing the `LongTermMemory` interface
+  (`remember`, `recall`, `facts`), Redis hash storage, optional TTL, lazy import,
+  entry-point registration under `kognios.memory`, and 15 unit tests requiring no
+  real Redis server.
+- **PyPI build readiness** — `python -m build` produces `dist/kognios-1.0.0.whl`
+  and `dist/kognios-1.0.0.tar.gz`; both pass `python -m twine check dist/*`.
+  Ready to upload with `python -m twine upload dist/*`.
+
+### Changed
+- Default `pytest` run now excludes integration tests automatically via
+  `addopts = "-m 'not integration'"` in `pyproject.toml`. Run integration
+  tests explicitly with `pytest -m integration`.
+
+---
+
+## [1.0.0] — 2026-07-06
+
+### Added
+- **Plugin system** — third-party providers/tools/memory discoverable via Python entry points (`kognios.providers`, `kognios.tools`, `kognios.memory`)
+- **`__version__`** attribute (importlib.metadata)
+- **Stable public API** with semantic versioning guarantees from this release onward
+
+### v1.0 features (all shipped in this release)
+- `AgentEvaluator` — run test datasets through an agent; scorers: `exact_match`, `contains`, `regex_match`, `llm_judge`
+- Guardrails — `block_keywords`, `max_length`, `pii_scrubber`, `profanity_filter`; `input_guardrails`/`output_guardrails` on `Agent`
+- `Tracer` — span-based observability for LLM calls and tool executions; sink callbacks and OpenTelemetry stub
+
+---
+
+## [0.3.0] — 2026-07-06
+
+### Added
+- **Providers**: Ollama (local), Mistral, Cohere Command R+, AWS Bedrock
+- **Parallel tool execution** — `asyncio.gather` across tool calls in `arun`/`astream`
+- **Token counting** — `agent.last_usage` dict accumulated across the full run
+- **Persistent sessions** — `ShortTermMemory.save(path)` / `.load(path)`
+- **`NumpyVectorKnowledge`** — cosine similarity semantic search with pluggable `embed_fn`
+- **`LongTermMemory.semantic_recall(query)`** — semantic search over stored facts
+- **Knowledge loaders** — HTML, CSV, JSON, DOCX, GitHub repo crawler
+- **Multi-step planning** — `Agent.plan_and_run()` / `aplan_and_run()`
+- **Agent-to-agent messaging** — `Agent.send()` / `asend()`
+- **`code_interpreter` builtin** — subprocess-isolated exec with timeout
+- **`browse` builtin** — Playwright (headless Chromium) with urllib fallback
+- **MCP client** — `MCPClient` connects agents to any MCP server via stdio or SSE
+- **`kognios serve`** — FastAPI `POST /run` endpoint
+- 115 tests (up from 38)
+
+---
+
+## [0.2.0] — 2026-06-01 (initial public release)
+
+### Added
+- `Agent` with ReAct loop, `@tool` decorator, JSON schema auto-gen
+- `ShortTermMemory` (sliding-window RAM buffer)
+- `LongTermMemory` (SQLite key/value, auto-injected into system prompt)
+- `SQLiteKnowledge` — FTS5 BM25 full-text search
+- `Team` routing — router LLM picks named sub-agent
+- Streaming (`agent.stream()`) and async (`agent.arun()`, `agent.astream()`)
+- Structured output via Pydantic models
+- Providers: Anthropic, OpenAI, Groq, Gemini
+- Built-in tools: `calculator`, `python_eval`, `read_file`, `write_file`, `http_get`, `web_search`
+- CLI: `kognios chat`, `kognios ask`
+- PDF ingestion (`kognios[pdf]`)
+- 38 unit tests

kognios-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,230 @@
+# Contributing to Kogni·OS
+
+Thank you for considering a contribution! This document covers everything
+you need to go from idea → merged PR.
+
+---
+
+## Table of contents
+
+1. [Quick setup](#quick-setup)
+2. [Project structure](#project-structure)
+3. [Running tests](#running-tests)
+4. [Coding conventions](#coding-conventions)
+5. [Adding a new model provider](#adding-a-new-model-provider)
+6. [Adding a new built-in tool](#adding-a-new-built-in-tool)
+7. [Submitting a PR](#submitting-a-pr)
+8. [Reporting bugs](#reporting-bugs)
+
+---
+
+## Quick setup
+
+```bash
+# Windows (recommended local path)
+cd C:\Claude\Projects
+git clone https://github.com/lavkeshdwivedi/kogniOS
+cd kogniOS
+
+# macOS / Linux
+git clone https://github.com/lavkeshdwivedi/kogniOS
+cd kogniOS
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run the test suite (no API key needed — all mocked)
+pytest tests/ -v
+```
+
+Python **3.11 or newer** is required.
+
+---
+
+## Project structure
+
+```
+kognios/          ← the importable package
+  agent.py        ← Agent class + ReAct loop
+  team.py         ← Team router
+  cli.py          ← Click CLI (kognios chat / kognios ask)
+  models/         ← provider adapters
+  tools/          ← @tool decorator + built-in tools
+  memory/         ← short-term (RAM) + long-term (SQLite)
+  knowledge/      ← FTS5 RAG pipeline
+  storage/        ← shared SQLite connection + migrations
+examples/         ← runnable demos (require an API key)
+tests/            ← unit tests (mocked, no key needed)
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/ -v                # all tests
+pytest tests/test_agent.py -v  # single file
+pytest -k "memory" -v          # filter by name
+```
+
+Tests live in `tests/` and use `unittest.mock`. No external services are
+called — every LLM response is a `MagicMock`.
+
+To lint:
+
+```bash
+ruff check kognios tests
+ruff format --check kognios tests
+```
+
+---
+
+## Coding conventions
+
+- **Python 3.11+** syntax — use `X | Y` unions, `list[T]`, `dict[K, V]`.
+- **`from __future__ import annotations`** at the top of every module.
+- **No comments** unless the *why* is genuinely non-obvious. Good names are enough.
+- **No extra abstractions** — three similar lines beat a premature helper.
+- **No new dependencies** without a strong reason. SQLite + stdlib is the baseline.
+- Line length: **100** (enforced by `ruff`).
+- Format with `ruff format` before opening a PR.
+
+---
+
+## Adding a new model provider
+
+1. Create `kognios/models/<name>.py`.
+2. Subclass `BaseModel` from `kognios.models.base`.
+3. Implement `complete()` — required abstract method.
+4. Optionally override `stream()`, `acomplete()`, `astream()`, `structured_complete()`.
+5. Export from `kognios/__init__.py`.
+6. Add a row to the provider table in `README.md`.
+
+Minimal example (OpenAI-compatible endpoint):
+
+```python
+# kognios/models/cohere.py
+from __future__ import annotations
+import os
+from .openai import OpenAIModel
+
+class CohereModel(OpenAIModel):
+    def __init__(self, model: str = "command-r-plus", **kwargs):
+        super().__init__(
+            model=model,
+            api_key=os.environ.get("COHERE_API_KEY", ""),
+            base_url="https://api.cohere.com/compatibility/v1",
+            **kwargs,
+        )
+```
+
+If the provider uses a non-OpenAI wire format, subclass `BaseModel` directly
+and look at `kognios/models/anthropic.py` as a reference.
+
+Add a test in `tests/test_agent.py` or a new `tests/test_<name>_model.py` that
+mocks the underlying SDK call and asserts `ModelResponse` fields.
+
+---
+
+## Adding a new built-in tool
+
+1. Create `kognios/tools/builtins/<name>.py`.
+2. Decorate your function with `@tool` from `kognios.tools.registry`.
+3. Add a type-hinted docstring — the first line becomes the tool description.
+4. Export from `kognios/tools/builtins/__init__.py`.
+5. Add tests to `tests/test_builtins.py`.
+
+```python
+# kognios/tools/builtins/uuid_gen.py
+from __future__ import annotations
+import uuid
+from ..registry import tool
+
+@tool
+def generate_uuid() -> str:
+    """Generate a random UUID v4."""
+    return str(uuid.uuid4())
+```
+
+---
+
+## Submitting a PR
+
+1. **Fork** the repo and create a feature branch:
+   ```bash
+   git checkout -b feat/my-feature
+   ```
+2. Make your changes, write tests, run `pytest` and `ruff check`.
+3. Commit with a clear message:
+   ```
+   feat: add CohereModel provider
+   fix: handle empty tool_calls in OpenAI streaming
+   docs: add structured output example to README
+   ```
+4. Push and open a pull request against `main`.
+5. Fill in the PR template — describe *what* changed and *why*.
+
+PRs that pass CI and include tests will be reviewed promptly.
+
+---
+
+## Reporting bugs
+
+Open a [GitHub Issue](https://github.com/lavkeshdwivedi/kogniOS/issues/new/choose)
+using the **Bug report** template. Include:
+
+- Python version (`python --version`)
+- Kogni·OS version (`pip show kognios`)
+- Provider and model you were using
+- Minimal reproduction snippet
+- Full traceback
+
+---
+
+## Code of conduct
+
+Be kind and constructive. Disagreements about code are fine; personal attacks
+are not. We follow the [Contributor Covenant](https://www.contributor-covenant.org/).
+
+---
+
+## Publishing to PyPI
+
+Build and publish (maintainers only):
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build wheel + sdist
+python -m build
+
+# Upload to PyPI (requires PyPI API token)
+twine upload dist/*
+
+# Or upload to TestPyPI first:
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ kognios
+```
+
+Users can install directly from PyPI:
+```bash
+pip install kognios
+pip install 'kognios[all]'   # all optional deps
+```
+
+---
+
+## Running integration tests
+
+Unit tests (default, no API keys needed):
+```bash
+pytest tests/ -m "not integration"
+```
+
+Integration tests (require real API keys):
+```bash
+export ANTHROPIC_API_KEY=...
+export OPENAI_API_KEY=...
+pytest tests/ -m integration -v
+```

kognios-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lavkesh Dwivedi
+
+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.

kognios-1.1.0/Makefile

@@ -0,0 +1,19 @@
+.PHONY: test lint format build clean
+
+test:
+	python -m pytest tests/ -m "not integration" -v
+
+test-all:
+	python -m pytest tests/ -v
+
+lint:
+	python -m ruff check kognios/ tests/
+
+format:
+	python -m ruff format kognios/ tests/
+
+build:
+	python -m build
+
+clean:
+	rm -rf dist/ build/ *.egg-info/ __pycache__/