openqueryagent 1.0.0__tar.gz

openqueryagent-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for reporting a bug. Please fill out the details below.
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Configure adapter with...
+        2. Call agent.ask("...")
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Version info
+      placeholder: |
+        - Python version: 3.12
+        - openqueryagent version: 0.3.0
+        - OS: Ubuntu 24.04
+        - Adapter: qdrant
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: Paste any relevant log output (use code block).
+      render: shell

openqueryagent-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How should this work?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative approaches you've thought about.

openqueryagent-1.0.0/.github/ISSUE_TEMPLATE/new_adapter.yml

@@ -0,0 +1,28 @@
+name: New Adapter Proposal
+description: Propose a new database adapter
+labels: [adapter, enhancement]
+body:
+  - type: textarea
+    id: database
+    attributes:
+      label: Database
+      description: Name and link to the database.
+      placeholder: "e.g. Redis Vector Search — https://redis.io/docs/stack/search/"
+    validations:
+      required: true
+  - type: textarea
+    id: justification
+    attributes:
+      label: Justification
+      description: Why should this adapter be added?
+    validations:
+      required: true
+  - type: dropdown
+    id: contributor
+    attributes:
+      label: Will you implement this?
+      options:
+        - "Yes, I'll submit a PR"
+        - "No, requesting someone else implement it"
+    validations:
+      required: true

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

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check openqueryagent/ tests/
+      - name: Ruff format check
+        run: ruff format --check openqueryagent/ tests/
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Mypy
+        run: mypy openqueryagent/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v -m "not integration" --tb=short

openqueryagent-1.0.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+Design/
+roadmap.md
+ROADMAP.md

openqueryagent-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    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:
+          - pydantic>=2.0
+        args: [--strict]
+        pass_filenames: false
+        entry: mypy openqueryagent/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files

openqueryagent-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to OpenQueryAgent
+
+Thank you for your interest in contributing! This guide covers how to add new components, code style, and the PR process.
+
+## Development Setup
+
+```bash
+git clone https://github.com/thirukguru/openqueryagent.git
+cd openqueryagent
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,server,observability]"
+pytest tests/ -v
+```
+
+## Adding a New Adapter
+
+1. **Create** `openqueryagent/adapters/my_db.py` inheriting from `BaseAdapter`
+2. **Implement** all abstract methods: `connect()`, `disconnect()`, `health_check()`, `search()`, `aggregate()`, `list_collections()`, `get_schema()`
+3. **Create** `openqueryagent/adapters/my_db_filters.py` with a `FilterCompiler` subclass
+4. **Add** an optional dependency group in `pyproject.toml`
+5. **Register** via entry point (optional, for plugin-based discovery):
+   ```toml
+   [project.entry-points."openqueryagent.adapters"]
+   my_db = "openqueryagent.adapters.my_db:MyDbAdapter"
+   ```
+6. **Write tests** in `tests/test_my_db_adapter.py`
+
+## Adding a New Reranker
+
+1. **Create** `openqueryagent/core/rerankers/my_reranker.py` implementing the `Reranker` protocol
+2. **Register** via entry point:
+   ```toml
+   [project.entry-points."openqueryagent.rerankers"]
+   my_reranker = "openqueryagent.core.rerankers.my_reranker:MyReranker"
+   ```
+
+## Adding a New LLM Provider
+
+1. **Create** `openqueryagent/llm/my_provider.py` inheriting from `BaseLLMProvider`
+2. **Add** optional dependency in `pyproject.toml`
+3. **Write tests** with mocked API responses
+
+## Code Style
+
+- **Formatter & linter**: [Ruff](https://docs.astral.sh/ruff/) (`ruff check --fix . && ruff format .`)
+- **Type checking**: [mypy](http://mypy-lang.org/) (`mypy openqueryagent/`)
+- **Line length**: 100 characters
+- **Docstrings**: Google style
+- **Imports**: `from __future__ import annotations` at top of every module
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_my_adapter.py -v
+
+# Run with coverage
+pytest tests/ --cov=openqueryagent --cov-report=term-missing
+```
+
+## Pull Request Process
+
+1. Fork the repo and create a feature branch from `main`
+2. Keep commits focused and atomic
+3. Add tests for any new functionality
+4. Ensure all tests pass and linting is clean
+5. Update documentation if needed
+6. Submit PR with a clear description of what and why
+
+## Reporting Issues
+
+Use the GitHub issue templates:
+- **Bug Report** — reproducible bugs with environment details
+- **Feature Request** — new feature proposals
+- **New Adapter** — proposals for new database adapters

openqueryagent-1.0.0/Dockerfile

@@ -0,0 +1,35 @@
+# ---- Build stage ----
+FROM python:3.12-slim AS builder
+
+WORKDIR /build
+
+COPY pyproject.toml README.md ./
+COPY openqueryagent/ ./openqueryagent/
+
+RUN pip install --no-cache-dir build \
+    && python -m build --wheel --outdir /build/dist
+
+# ---- Runtime stage ----
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.source="https://github.com/thirukguru/openqueryagent"
+LABEL org.opencontainers.image.description="OpenQueryAgent — database-agnostic query agent for vector databases"
+
+WORKDIR /app
+
+# Install the wheel with server extras
+COPY --from=builder /build/dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl[server,openai,anthropic,qdrant,pgvector,milvus] \
+    && rm -rf /tmp/*.whl
+
+# Non-root user
+RUN useradd --create-home --shell /bin/bash oqa
+USER oqa
+
+EXPOSE 8000 50051
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://localhost:8000/v1/health').raise_for_status()"
+
+ENTRYPOINT ["python", "-m", "openqueryagent.server"]
+CMD ["--host", "0.0.0.0", "--port", "8000"]