cognitia 0.3.0b1__tar.gz

cognitia-0.3.0b1/.git

@@ -0,0 +1 @@
+gitdir: ../../.git/modules/packages/cognitia

cognitia-0.3.0b1/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material mkdocs-minify-plugin
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

cognitia-0.3.0b1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+.coverage
+htmlcov/
+
+dist/
+build/
+*.egg-info/
+
+site/

cognitia-0.3.0b1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be 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.3.0b1] - 2026-03-13
+
+### Added
+- **Agent Facade API** (`cognitia.agent`) — high-level 3-line API for AI agents
+  - `Agent` class with `query()`, `stream()`, `conversation()` methods
+  - `@tool` decorator for defining tools with auto-inferred JSON Schema
+  - `Middleware` protocol with built-in `CostTracker` and `SecurityGuard`
+  - `Conversation` for explicit multi-turn dialog management
+- **Import isolation** — `import cognitia` works without any optional dependencies
+- **Test markers** — `requires_claude_sdk`, `requires_anthropic`, `requires_langchain`, `live`
+- LICENSE (MIT), CHANGELOG, CONTRIBUTING, comprehensive documentation
+
+### Fixed
+- `@tool` handler contract mismatch with Claude Agent SDK MCP format
+- `hooks/__init__.py` crash when `claude_agent_sdk` not installed
+- Optional dependency boundaries fully verified with smoke tests
+
+## [0.2.0] - 2026-02-11
+
+### Added
+- **Multi-runtime support** — 3 pluggable runtimes:
+  - `claude_sdk` — Claude Agent SDK (subprocess, built-in MCP)
+  - `thin` — lightweight built-in loop (react/planner/conversational modes)
+  - `deepagents` — LangChain Deep Agents integration
+- **RuntimeFactory** — create runtime by config/env/override
+- **Runtime Ports** — `BaseRuntimePort`, `ThinRuntimePort`, `DeepAgentsRuntimePort`
+- **Model Registry** — multi-provider (Anthropic, OpenAI, Google, DeepSeek) with aliases
+- **CognitiaStack** — bootstrap facade factory for quick setup
+- **Memory providers** — InMemory, PostgreSQL, SQLite
+- **Web tools** — pluggable search (DuckDuckGo, Tavily, SearXNG, Brave) and fetch providers
+- **Orchestration** — plan manager, subagent spawning, team coordination
+- **SDK 0.1.48 integration** — `one_shot_query`, `sdk_tools`, hooks bridge
+- **LLM Summarizer** — automatic conversation summarization with history cap
+- **Circuit Breaker** — resilience pattern for external calls
+- 14 ISP-compliant protocols (each <=5 methods)
+
+### Changed
+- Domain-agnostic: removed all finance-specific defaults from library code
+- `RoleSkillsLoader` moved to `cognitia.config.role_skills`
+- `RoleRouterConfig` is now a typed dataclass (was dict)
+
+## [0.1.0] - 2026-02-10
+
+### Added
+- **Core protocols** — `FactStore`, `GoalStore`, `MessageStore`, `SummaryStore`, `UserStore`, `SessionStateStore`, `PhaseStore`, `ToolEventStore`
+- **Behavior protocols** — `RoleRouter`, `ModelSelector`, `ToolIdCodec`, `ContextBuilder`, `SessionRehydrator`, `RuntimePort`
+- **Session management** — `InMemorySessionManager`, `DefaultSessionRehydrator`
+- **Context builder** — `DefaultContextBuilder` with token budget and priority-based overflow
+- **Tool policy** — `DefaultToolPolicy` with default-deny and always-denied tools list
+- **Skills** — `YamlSkillLoader`, `SkillRegistry` for declarative MCP skill management
+- **Routing** — `KeywordRoleRouter` for keyword-based role resolution
+- **Observability** — `AgentLogger` with structured JSON logging
+- **Memory** — `InMemoryMemoryProvider`, `PostgresMemoryProvider`
+- **Commands** — `CommandRegistry` with aliases
+
+[0.3.0b1]: https://github.com/fockus/cognitia/compare/v0.2.0...v0.3.0b1
+[0.2.0]: https://github.com/fockus/cognitia/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/fockus/cognitia/releases/tag/v0.1.0

cognitia-0.3.0b1/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to Cognitia
+
+Thank you for your interest in contributing to Cognitia!
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/fockus/cognitia.git
+cd cognitia
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+
+# Install with dev dependencies and all extras
+pip install -e ".[dev,all]"
+
+# Verify installation
+python -c "import cognitia; print(cognitia.__version__)"
+```
+
+## Running Tests
+
+```bash
+# All offline tests (default)
+pytest
+
+# Include tests that require Claude Agent SDK
+pytest -m "requires_claude_sdk or not requires_claude_sdk"
+
+# Include live/network tests
+pytest -m live
+
+# With coverage
+pytest --cov=cognitia --cov-report=term-missing
+
+# Specific test file
+pytest tests/unit/test_agent_tool.py -v
+```
+
+## Code Style
+
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+# Check
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Auto-fix
+ruff check --fix src/ tests/
+ruff format src/ tests/
+```
+
+Type checking with [mypy](https://mypy-lang.org/):
+
+```bash
+mypy src/cognitia/
+```
+
+## Architecture Principles
+
+- **Clean Architecture** — dependencies point inward: Infrastructure -> Application -> Domain
+- **Protocol-first** — define `Protocol` interfaces before implementations
+- **TDD** — write tests before implementation (Red -> Green -> Refactor)
+- **SOLID** — SRP (<300 lines per module), ISP (<=5 methods per protocol), DIP (depend on abstractions)
+- **Domain-agnostic** — cognitia must not contain any domain-specific logic (finance, medical, etc.)
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Write tests first (TDD)
+4. Implement the feature
+5. Ensure all tests pass: `pytest`
+6. Ensure code style: `ruff check && ruff format --check`
+7. Submit a pull request with a clear description
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new middleware for rate limiting
+fix: handle empty tool parameters in @tool decorator
+docs: update runtime switching guide
+test: add integration tests for SQLite provider
+refactor: extract common logic from runtime ports
+```
+
+## Optional Dependencies
+
+Cognitia uses optional dependency groups. When adding features that require new packages:
+
+1. Add the dependency to the appropriate extra in `pyproject.toml`
+2. Use lazy imports (inside functions/methods) for optional packages
+3. Never import optional packages at module top-level
+4. Add a smoke test in `tests/unit/test_import_isolation.py`
+5. Mark tests that require the extra with the appropriate marker:
+   - `@pytest.mark.requires_claude_sdk`
+   - `@pytest.mark.requires_anthropic`
+   - `@pytest.mark.requires_langchain`
+   - `@pytest.mark.live` (for network-dependent tests)
+
+## Questions?
+
+Open an issue on GitHub for questions, bug reports, or feature requests.

cognitia-0.3.0b1/LICENSE

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