kagi-cli 0.1.0__tar.gz

kagi_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  github-release:
+    name: Attach packages to GitHub Release
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create or update release and upload assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  pypi-publish:
+    name: Publish to PyPI (Trusted Publishing)
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+
+    # Configure this environment in GitHub settings and connect it in PyPI
+    # as a Trusted Publisher for this repository/workflow.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/kagi-cli/
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

kagi_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

kagi_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

kagi_cli-0.1.0/CONVENTIONS.md

@@ -0,0 +1,120 @@
+# Coding Conventions
+
+## 1. Guiding Principles
+
+Our primary goal is to build a robust, maintainable, code base.
+
+Key principles:
+
+* **Clarity over Cleverness:** Code should be easy to read and understand
+* **Explicit over Implicit:** Be clear about intentions and dependencies
+* **Consistency:** Follow established patterns within the project
+* **Single Responsibility Principle:** Each module, class, or function should have one clear purpose
+* **Loose Coupling, High Cohesion:** Modules should be independent but related components within a module should be grouped
+* **Testability:** Write code that is inherently easy to unit and integration test
+* **Pythonic:** Embrace PEP 8 and the Zen of Python (`import this`)
+
+## 2. General Python Conventions
+
+* **PEP 8 Compliance:** Adhere strictly to PEP 8
+  * Use `ruff format` for auto-formatting to ensure consistent style
+  * Line length limit is **88 characters** (ruff's default)
+* **Python Version:** Target **Python 3.11+**. Utilize modern features like union types (`X | Y`)
+* **No Mutable Default Arguments:** Avoid using mutable objects as default arguments
+  * **Bad:** `def foo(items=[])`
+  * **Good:** `def foo(items: list | None = None): if items is None: items = []`
+
+## 3. Naming Conventions
+
+* **Packages/Directories:** `snake_case` (e.g., `api`, `claude_sdk`, `auth`)
+* **Modules:** `snake_case` (e.g., `manager.py`, `client.py`)
+* **Classes:** `CamelCase` (e.g., `OpenAIAdapter`, `ServiceContainer`)
+  * **Abstract Base Classes:** Suffix with `ABC` or `Protocol`
+  * **Pydantic Models:** `CamelCase` (e.g., `MessageCreateParams`)
+* **Functions/Methods/Variables:** `snake_case` (e.g., `handle_request`, `get_access_token`)
+* **Constants:** `UPPER_SNAKE_CASE` (e.g., `DEFAULT_PORT`, `API_VERSION`)
+* **Private Members:** `_single_leading_underscore` for internal use
+
+## 4. Imports
+
+* **Ordering:** Standard library → Third-party → First-party → Relative
+* **Absolute Imports Preferred:** Use absolute imports for modules within the project
+* **`__all__` in `__init__.py`:** Define to explicitly expose public API
+
+## 5. Typing
+
+Type hints are mandatory for clarity and maintainability:
+
+* **All Function Signatures:** Type-hint all parameters and return values, avoid `Any`
+* **Class Attributes:** Use type hints, especially for Pydantic models
+* **Union Types:** Use `Type | None` for optional values (Python 3.11+)
+* **Type Aliases:** Define in `core/types.py` for complex types
+* **Generics:** Use `Generic[T]` for classes/functions that operate on multiple types
+
+## 7. Error Handling
+
+* **Custom Exceptions:** Inherit from `kagicli.errors.BaseError`
+* **Catch Specific Exceptions:** Never use bare `except:`
+* **Chain Exceptions:** Use `raise NewError(...) from original`
+
+## 8. Asynchronous Programming
+
+* **`async`/`await`:** Use consistently for all I/O operations
+* **Libraries:** Prefer `httpx` for HTTP, `asyncio` for concurrency
+* **No Blocking Code:** Never use blocking I/O in async functions
+
+## 9. Testing
+
+* **Framework:** `pytest` with `pytest-asyncio`
+* **Architecture:** Streamlined after aggressive refactoring (606 tests, was 786)
+* **Structure:** Clean separation with proper boundaries:
+  * `tests/unit/` - Fast, isolated unit tests (mock at service boundaries only)
+  * `tests/integration/` - Cross-component interaction tests (core)
+* **Markers:** Use `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.network`,  `@pytest.mark.slow`
+* **Fixtures:** Essential fixtures only in `conftest.py` (515 lines, was 1117)
+* **Mocking:** External services only - no internal component mocking
+* **Type Safety:** All test functions must have `-> None` return type
+* **Coverage:** High coverage on critical paths with real component testing
+
+## 10. Configuration
+
+* **Pydantic Settings:** All config in `config/settings.py`
+* **Environment Variables:** Use `__` for nesting 
+* **Priority:** CLI args → Environment → TOML files → Defaults
+
+## 11. Security
+
+* **Input Validation:** All API inputs validated with Pydantic
+* **No Secrets in Code:** Use environment variables
+
+## 12. Tooling
+
+Core tools enforced via pre-commit and CI:
+
+* **Package Manager:** `uv` (via Makefile only)
+* **Formatter:** `ruff format`
+* **Linter:** `ruff check`
+* **Type Checker:** `mypy`
+* **Test Runner:** `pytest`
+* **Dev Scripts:** helper scripts under `scripts/` for local testing and debugging
+
+## 13. Development Workflow
+
+### Required Before Commits
+```bash
+make pre-commit  # Comprehensive checks + auto-fixes
+make test        # Run tests with coverage
+```
+
+## 14. Documentation
+
+* **Docstrings:** Required for all public APIs (Google style)
+* **Comments:** Explain *why*, not *what*
+* **TODO/FIXME:** Use consistently with explanations
+
+## 15. Git Workflow
+
+* **Commits:** Follow Conventional Commits (feat:, fix:, docs:, etc.)
+* **Branches:** Use feature branches (`feature/`, `fix/`, `docs/`)
+* **No `git add .`:** Only stage specific files
+

kagi_cli-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: kagi-cli
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pygments>=2.19.2
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# kagi-cli-py
+
+Python CLI and client for Kagi services.
+
+PyPI package name: `kagi-cli`
+
+## Features
+
+- `proofread`: improve text quality
+- `summarize`: summarize URLs
+- `ask`: query Kagi Assistant
+- `search`: run Kagi search queries
+
+## Requirements
+
+- Python 3.12+
+- A valid `KAGI_SESSION` value from your Kagi session link
+
+## Install
+
+```bash
+uv sync
+```
+
+## Install and run from PyPI
+
+```bash
+# Run without installing globally
+uvx --from kagi-cli kagi --help
+pipx run --spec kagi-cli kagi --help
+
+# Install globally with pipx
+pipx install kagi-cli
+kagi --help
+```
+
+## Authentication
+
+Set `KAGI_SESSION` from your Kagi session link before using the CLI:
+
+```bash
+export KAGI_SESSION="your_session_value_from_link"
+```
+
+## CLI usage
+
+```bash
+# Show help
+uv run kagi --help
+
+# Show version (git tag when available)
+uv run kagi --version
+
+# Proofread text
+uv run kagi proofread "Ths is a tset."
+
+# Summarize a URL
+uv run kagi summarize "https://example.com"
+
+# Ask assistant
+uv run kagi ask "What is 2+2?"
+
+# Search
+uv run kagi search "python async"
+```
+
+## Output formats
+
+Commands support:
+
+- `--format console` (default)
+- `--format json`
+- `--format md`
+- `--format csv`
+
+## Run tests
+
+```bash
+uv run pytest -q
+```

kagi_cli-0.1.0/README.md

@@ -0,0 +1,80 @@
+# kagi-cli-py
+
+Python CLI and client for Kagi services.
+
+PyPI package name: `kagi-cli`
+
+## Features
+
+- `proofread`: improve text quality
+- `summarize`: summarize URLs
+- `ask`: query Kagi Assistant
+- `search`: run Kagi search queries
+
+## Requirements
+
+- Python 3.12+
+- A valid `KAGI_SESSION` value from your Kagi session link
+
+## Install
+
+```bash
+uv sync
+```
+
+## Install and run from PyPI
+
+```bash
+# Run without installing globally
+uvx --from kagi-cli kagi --help
+pipx run --spec kagi-cli kagi --help
+
+# Install globally with pipx
+pipx install kagi-cli
+kagi --help
+```
+
+## Authentication
+
+Set `KAGI_SESSION` from your Kagi session link before using the CLI:
+
+```bash
+export KAGI_SESSION="your_session_value_from_link"
+```
+
+## CLI usage
+
+```bash
+# Show help
+uv run kagi --help
+
+# Show version (git tag when available)
+uv run kagi --version
+
+# Proofread text
+uv run kagi proofread "Ths is a tset."
+
+# Summarize a URL
+uv run kagi summarize "https://example.com"
+
+# Ask assistant
+uv run kagi ask "What is 2+2?"
+
+# Search
+uv run kagi search "python async"
+```
+
+## Output formats
+
+Commands support:
+
+- `--format console` (default)
+- `--format json`
+- `--format md`
+- `--format csv`
+
+## Run tests
+
+```bash
+uv run pytest -q
+```

kagi_cli-0.1.0/TESTING.md

@@ -0,0 +1,139 @@
+# Streamlined Testing Guide
+
+## Philosophy
+
+After aggressive refactoring and architecture realignment, our testing philosophy is:
+- **Clean boundaries**: Unit tests for isolated components, integration tests for cross-component behavior
+- **Fast execution**: Unit tests run in milliseconds, mypy completes in seconds  
+- **Modern patterns**: Type-safe fixtures, clear separation of concerns
+- **Minimal mocking**: Only mock external services, test real internal behavior
+
+## Quick Start
+
+```bash
+# Run all tests
+make test
+
+# Run specific test categories
+pytest tests/unit/auth/          # Authentication tests
+pytest tests/unit/config/      # Config tests
+pytest tests/integration/        # Cross-component integration tests (core)
+
+# Run with coverage
+make test-coverage
+
+# Type checking and quality (now sub-second)
+make typecheck
+make pre-commit
+```
+
+
+## Writing Tests
+
+### Clean Architecture Principles
+
+**Unit Tests** (tests/unit/):
+- Mock at **service boundaries only** - never mock internal components
+- Test **pure functions and single components** in isolation
+- **No timing dependencies** - all asyncio.sleep() removed
+- **No database operations** - moved to integration tests
+
+**Integration Tests** (tests/integration/):
+- Test **cross-component interactions** with minimal mocking
+- Include **HTTP client testing **
+- Test **async coordination when needed**
+- Validate configuration end-to-end
+
+### Mocking Strategy (Simplified)
+
+- **External APIs only** 
+- **Internal services**: Use real implementations with dependency injection
+- **Configuration**: Use test settings objects, not mocks
+- **No mock explosion**
+
+## Type Safety and Code Quality
+
+**REQUIREMENT**: All test files MUST pass type checking and linting. This is not optional.
+
+### Type Safety Requirements
+
+1. **All test files MUST pass mypy type checking** - No `Any` types unless absolutely necessary
+2. **All test files MUST pass ruff formatting and linting** - Code must be properly formatted
+3. **Add proper type hints to all test functions and fixtures** - Include return types and parameter types
+4. **Import necessary types** - Use `from typing import` for type annotations
+
+### Required Type Annotations
+
+- **Test functions**: Must have `-> None` return type annotation
+- **Fixtures**: Must have proper return type hints
+- **Parameters**: Must have type hints where not inferred from fixtures
+- **Variables**: Add type hints for complex objects when not obvious
+
+## Architecture Overview 
+
+### Essential Fixtures 
+
+
+## Test Markers
+
+- `@pytest.mark.unit` - Fast unit tests (default)
+- `@pytest.mark.integration` - Cross-component integration tests
+- `@pytest.mark.network` - Tests requiring network access (external APIs) 
+- `@pytest.mark.slow` - Tests that take longer than 1 second (avoid if possible) 
+
+## Best Practices
+
+1. **Clean boundaries** - Unit tests mock at service boundaries only
+2. **Fast execution** - Unit tests run in milliseconds, no timing dependencies
+3. **Type safety** - All fixtures properly typed, mypy compliant
+4. **Real components** - Test actual internal behavior, not mocked responses
+5. **Performance-optimized patterns** - Use session-scoped fixtures for expensive operations
+6. **Modern async patterns** - `@pytest.mark.asyncio(loop_scope="session")` for integration tests
+7. **No overengineering** - Removed 180+ tests, 3000+ lines of complexity
+
+### Performance Guidelines
+
+#### When to Use Session-Scoped Fixtures
+- **Plugin integration tests** - Plugin initialization is expensive
+- **Database/external service tests** - Connection setup overhead
+- **Complex app configuration** - Multiple services, middleware stacks
+- **Consistent test state needed** - Tests require same app configuration
+
+#### When to Use Factory Patterns  
+- **Dynamic configurations** - Each test needs different plugin settings
+- **Isolation required** - Tests might interfere with shared state
+- **Simple setup** - Minimal overhead for app creation
+
+#### Logging Performance Tips
+- **Use `ERROR` level** - Minimal logging for faster test execution
+- **Disable JSON logs** - `json_logs=False` for better performance
+- **Manual setup required** - Call `setup_logging()` explicitly in test environment
+
+
+## Running Tests
+
+### Make Commands
+
+```bash
+make test                 # Run all tests with coverage except network, slow
+make test-coverage        # With coverage report
+```
+
+### Direct pytest
+
+```bash
+pytest -v                          # Verbose output
+pytest -k "test_auth"              # Run matching tests
+pytest --lf                        # Run last failed
+pytest -x                          # Stop on first failure
+pytest -s -v                       # No capture, verbose 
+pytest --pdb                       # Debug on failure
+pytest -m unit                     # Unit tests only
+pytest -m integration              # Integration tests only
+pytest -m slow                     # Slow tests only 
+```
+
+## Migration from Old Architecture
+
+**All existing test patterns still work** - but new tests should use the performance-optimized patterns:
+

kagi_cli-0.1.0/flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1735563628,
+        "narHash": "sha256-OnSAY7XDSx7CtDoqNh8jwVwh4xNL/2HaJxGjryLWzX8=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b134951a4c9f3c995fd7be05f3243f8ecd65d798",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-24.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

kagi_cli-0.1.0/flake.nix

@@ -0,0 +1,37 @@
+{
+  description = "Kagi development flake";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forEachSystem = nixpkgs.lib.genAttrs systems;
+    in {
+      devShells = forEachSystem (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+        in {
+          default = pkgs.mkShell {
+            packages = with pkgs; [
+              python312
+              uv
+              zsh
+            ];
+
+            shellHook = ''
+              # Keep uv-managed virtual environments local to this repo and align with nix python.
+              export UV_PROJECT_ENV=".venv"
+              export UV_PYTHON="${pkgs.python312}/bin/python3"
+            '';
+          };
+        });
+    };
+}

kagi_cli-0.1.0/kagi_client/__init__.py

@@ -0,0 +1,67 @@
+from kagi_client.assistant import AssistantClient
+from kagi_client.auth import KagiAuth
+from kagi_client.client import KagiClient
+from kagi_client.errors import (
+    APIError,
+    AuthError,
+    KagiError,
+    StreamParseError,
+    TokenExpiredError,
+)
+from kagi_client.formatters import OutputFormat
+from kagi_client.models import (
+    AssistantMessage,
+    AssistantResult,
+    AssistantThread,
+    AuthResponse,
+    DetectedLanguage,
+    DomainInfo,
+    ProofreadAnalysis,
+    ProofreadResult,
+    ResponseMetadata,
+    SearchInfo,
+    SearchItem,
+    SearchResult,
+    SummaryResult,
+    SummaryUpdate,
+    TokenPayload,
+    ToneAnalysis,
+    WordStats,
+    WritingStatistics,
+)
+from kagi_client.proofread import ProofreadClient
+from kagi_client.search import SearchClient
+from kagi_client.summarizer import SummarizerClient
+
+__all__ = [
+    "APIError",
+    "AssistantClient",
+    "AssistantMessage",
+    "AssistantResult",
+    "AssistantThread",
+    "AuthError",
+    "AuthResponse",
+    "DetectedLanguage",
+    "DomainInfo",
+    "KagiAuth",
+    "KagiClient",
+    "KagiError",
+    "OutputFormat",
+    "ProofreadAnalysis",
+    "ProofreadClient",
+    "ProofreadResult",
+    "ResponseMetadata",
+    "SearchClient",
+    "SearchInfo",
+    "SearchItem",
+    "SearchResult",
+    "StreamParseError",
+    "SummarizerClient",
+    "SummaryResult",
+    "SummaryUpdate",
+    "TokenExpiredError",
+    "TokenPayload",
+    "ToneAnalysis",
+    "WordStats",
+    "WritingStatistics",
+]