feat: auto-generate tool schemas from @register_tool functions

Author: SergiiShcherbak

.gitattributes

@@ -0,0 +1,2 @@
+# Enforce LF line endings for all text files
+* text=auto eol=lf

.gitignore

@@ -21,3 +21,5 @@ docs/build
 dist
 .DS_Store
 code_sample.py
+
+settings.local.json

AGENTS.md

@@ -0,0 +1,168 @@
+# AGENTS.md - AI Coding Assistant Guidelines
+
+Guidelines for AI coding assistants working with the ContextGem codebase.
+
+For detailed contribution procedures, see `CONTRIBUTING.md`, which covers:
+- Development environment setup
+- Project structure overview
+- VCR cassette recording scenarios
+- Documentation building
+
+## Project Overview
+
+**ContextGem** is a Python LLM framework for extracting structured data from documents using long context windows (not RAG-based).
+
+- **Python**: 3.10-3.13
+- **License**: Apache 2.0
+- **Package Manager**: `uv`
+
+## Architecture: Internal/Public Split
+
+The codebase uses a two-layer architecture. **Always implement in internal first, then expose via public.**
+
+```
+contextgem/
+├── internal/          # Core implementation (_underscore-prefixed classes)
+│   ├── base/          # Business logic (concepts, aspects, documents, llms)
+│   ├── prompts/       # Jinja2 prompt templates
+│   ├── typings/       # Type system & validators
+│   └── registry.py    # Internal-to-public type mapping
+└── public/            # Thin facades (inherit from internal, registered via decorator)
+```
+
+### Pattern Example
+
+```python
+# 1. Internal implementation (contextgem/internal/base/concepts.py)
+class _StringConcept(BaseModel):
+    name: str
+    # ... business logic ...
+
+# 2. Public facade (contextgem/public/concepts.py)
+@_expose_in_registry(additional_key=_StringConcept)
+class StringConcept(_StringConcept):
+    """Public API documentation."""
+    pass
+
+# 3. Export in contextgem/__init__.py
+```
+
+## Coding Conventions
+
+| Convention | Rule |
+|------------|------|
+| Internal classes | `_Aspect`, `_Document` (underscore prefix) |
+| Public classes | `Aspect`, `Document` (no prefix) |
+| Constants | `_MAX_NESTING_LEVEL` (ALL_CAPS) |
+| Required import | `from __future__ import annotations` (except `__init__.py`) |
+| Formatter | Ruff (line length: 88) |
+| Type checker | Pyright (basic mode) |
+| Docstrings | reStructuredText format for Sphinx (`:param:`, `:type:`, `:ivar:`, `:vartype:`, `:returns:`, `:rtype:`) |
+| Data models | Pydantic v2 (`BaseModel`, `field_validator`, `model_validator`) |
+
+## Auto-Generated Files - Do NOT Edit
+
+| File | Source | Regeneration |
+|------|--------|--------------|
+| `README.md` | `dev/readme.template.md` | Pre-commit hook runs `dev/populate_project_readme.py` |
+| `docs/source/llms.txt` | Documentation sources | Pre-commit hook |
+| `dev/notebooks/` | `dev/usage_examples/` | Pre-commit hook |
+| `uv.lock` | `pyproject.toml` | `uv sync` |
+
+**To update README**: Edit `dev/readme.template.md`, then run pre-commit or the generation script.
+
+## After Code Changes
+
+**Always run these steps after making changes:**
+
+```bash
+# 1. Run pre-commit hooks (formatting, linting, type checking)
+uv run pre-commit run --all-files
+
+# 2. Run targeted tests for the code you modified
+uv run pytest tests/test_all.py::TestAll::test_relevant_method
+
+# 3. Run full test suite to check for regressions
+uv run pytest
+```
+
+### Writing Tests for New Implementations
+
+When adding new functionality:
+
+1. **Add test methods** to `tests/test_all.py::TestAll` following existing patterns
+2. **For tests that do NOT call LLM APIs**: Run them to verify they pass
+3. **For tests that call LLM APIs**: Add `@pytest.mark.vcr` decorator, **do NOT run them**, and inform the user that cassettes need recording before these tests can be executed
+
+```python
+# Example: Adding a test in tests/test_all.py
+class TestAll:
+    def test_non_llm_feature(self):
+        # Safe to run - no LLM calls
+        pass
+
+    @pytest.mark.vcr  # Requires cassette - DO NOT RUN, inform user
+    def test_llm_feature(self):
+        # Calls LLM API - user must record cassette first
+        pass
+```
+
+### Updating Documentation
+
+When adding or modifying functionality:
+
+1. **Update docstrings** in the affected classes/methods (reStructuredText format)
+2. **Update RST files** in `docs/source/` if the feature has dedicated documentation
+3. **Update `dev/readme.template.md`** if README content is affected (not `README.md` directly)
+4. **Add usage examples** to `dev/usage_examples/` if demonstrating new features
+5. **Verify docs compile** by running from the `docs/` directory:
+
+   ```bash
+   uv run sphinx-build -b dirhtml source build/dirhtml -v -E -W
+   ```
+
+### VCR Cassette Rules
+
+- **Never run tests in "live" mode** without existing cassettes
+- Tests replay recorded LLM API responses from `tests/cassettes/`
+- If tests fail due to cassette mismatches, **inform the user** that cassettes need re-recording
+- The user will handle cassette re-recording themselves (requires API keys and may incur costs)
+- See [CONTRIBUTING.md - VCR Cassette Management](CONTRIBUTING.md#-vcr-cassette-management) for scenarios
+
+## Git Policy
+
+**Never stage or commit changes** - this is the developer's responsibility.
+
+The developer will review changes and handle git operations themselves.
+
+### File Operations During Refactoring
+
+When moving or renaming files, **always use `git mv`** to preserve git history:
+
+```bash
+# Moving a file
+git mv old/path/file.py new/path/file.py
+
+# Renaming a file
+git mv old_name.py new_name.py
+```
+
+**Never** use regular file system operations (copy + delete, or IDE rename) for moves/renames - this breaks git history tracking.
+
+## Quick Commands
+
+```bash
+uv sync --all-groups                    # Install dependencies
+uv run pre-commit run --all-files       # Run all linters/formatters
+uv run pytest                           # Run tests (uses recorded cassettes)
+uv run pytest --cov=contextgem          # Run tests with coverage
+uv run pytest tests/test_all.py::TestAll::test_specific  # Run specific test
+```
+
+## Key Gotchas
+
+1. **Never import public classes in internal modules** - use registry for type resolution
+2. **Prompt changes break VCR cassettes** - inform user if tests fail after prompt modifications
+3. **README.md is auto-generated** - edit `dev/readme.template.md` instead
+4. **Never stage or commit** - let the developer handle all git operations
+5. **Always run pre-commit** after code changes before considering work complete

CHANGELOG.md

@@ -5,6 +5,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - **Refactor**: Code reorganization that doesn't change functionality but improves structure or maintainability
 
+## [0.20.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.20.0) - 2026-02-22
+### Added
+- Auto-generate tool schemas from `@register_tool` decorated functions. Pass functions directly to `tools=[...]` — schemas are built automatically from type hints and docstrings. Explicit OpenAI-compatible schema dicts remain supported for full backward compatibility.
+- Added `docstring-parser` dependency for extracting tool parameter descriptions from Sphinx/reST, Google, and NumPy style docstrings.
+
+### Fixed
+- Deterministic tool schema generation: `required` field ordering in auto-generated schemas is now sorted, preventing non-deterministic output from `frozenset` iteration across Python process invocations.
+
+### Changed
+- Upgraded pinned dependency versions: `litellm==1.81.14`, `openai==2.21.0`, `genai-prices==0.0.54`. Versions remain pinned to maintain stability and avoid occasional breaking changes and API inconsistencies observed in previous unpinned releases.
+
+### Docs
+- Added dedicated "Chat with Tools" documentation page with examples for auto-schema generation, supported type hints, `TypedDict` usage, custom schema overrides, and tool configuration options.
+- Simplified quickstart tools example using the new `@register_tool` function-passing syntax.
+- Updated `CONTRIBUTING.md` with AI assistant guidance and Fabric commands.
+
 ## [0.19.4](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.19.4) - 2025-12-19
 ### Fixed
 - Applied fix for missing quote in JSON example format within prompt template. (PR [#86](https://github.com/shcherbak-ai/contextgem/pull/86))

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -18,6 +18,22 @@ To sign the agreement:
 3. Fill in all the requested information and include it in your first pull request
 
 
+## 🤖 Using AI Coding Assistants
+
+This repository is **AI agent-friendly** and includes configuration files to help AI coding assistants understand the codebase:
+
+- **[AGENTS.md](AGENTS.md)** - Project overview, architecture patterns, coding conventions, and workflow guidelines for AI assistants ([agents.md standard](https://agents.md))
+- **[CLAUDE.md](CLAUDE.md)** - Configuration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
+
+When using AI assistants (Claude Code, Cursor, etc.) to contribute:
+
+1. **Review AI-generated code** - Always verify changes follow project patterns and pass tests
+2. **Handle VCR cassettes yourself** - AI assistants should not run tests that call LLM APIs without existing cassettes
+3. **Manage git operations yourself** - Review and commit changes manually rather than letting AI handle git
+
+> **💡 Tip:** AI assistants work best when given specific, focused tasks. Break large contributions into smaller pieces for better results.
+
+
 ## 🚀 Getting Started
 
 ### 🛠️ Development Environment
@@ -44,18 +60,29 @@ To sign the agreement:
     # Install uv if you don't have it
     pip install uv
 
-    # Install dependencies and development extras
-    uv sync --all-groups
+    # Install dependencies and pre-commit hooks
+    uv run fab setup
+
+    # Or manually:
+    # uv sync --all-groups --upgrade
+    # uv run pre-commit install
+    # uv run pre-commit install --hook-type commit-msg
     ```
 
-3. **🔧 Install pre-commit hooks**:
-    ```bash
-    # Install pre-commit hooks
-    uv run pre-commit install
+### 🛠️ Available Fabric Commands
 
-    # Install commit-msg hooks (for commitizen)
-    uv run pre-commit install --hook-type commit-msg
-    ```
+The project includes a `fabfile.py` with common development tasks:
+
+```bash
+uv run fab --list          # List all available commands
+uv run fab setup           # Set up dev environment (deps + hooks)
+uv run fab sync            # Sync dependencies with upgrades
+uv run fab lint            # Run pre-commit checks on all files
+uv run fab docs            # Build documentation
+uv run fab docs-live       # Start live documentation server
+uv run fab readme          # Regenerate README.md from template
+uv run fab install-hooks   # Install pre-commit hooks
+```
 
 
 ### 📁 Project Structure
@@ -484,16 +511,13 @@ The log output will show detailed information about test execution.
 
 ### 🏗️ Building the Documentation
 
-Navigate to the `docs/` directory and choose your preferred build method:
+Use the fabric commands from the project root:
 
 #### For Live Development (Recommended)
 
-Use `sphinx-autobuild` for live reloading during development:
-
 ```bash
 # Live rebuild with auto-refresh on file changes
-make livehtml
-# Or on Windows: ./make.bat livehtml
+uv run fab docs-live
 ```
 
 This starts a development server on `http://localhost:9000` with:
@@ -503,23 +527,18 @@ This starts a development server on `http://localhost:9000` with:
 
 #### For Static Builds
 
-For one-time builds or CI-style building:
-
 ```bash
-# Build with verbose output, ignore cache, and treat warnings as errors 
-# (recommended for structural changes)
-uv run sphinx-build -b dirhtml source build/dirhtml -v -E -W
+# Build with verbose output, ignore cache, and treat warnings as errors
+uv run fab docs
 ```
 
-The `-E` flag ensures Sphinx completely rebuilds the environment, which is especially important after structural changes like modifying toctree directives or removing files. The `dirhtml` format creates pretty URLs without `.html` extensions, consistent with the live development server.
-
 ### 👀 Viewing the Documentation
 
 **With Live Development:**
-The documentation automatically opens at `http://localhost:9000` when using `make livehtml`.
+Open `http://localhost:9000` in your browser.
 
 **With Static Builds:**
-After building, open `build/dirhtml/index.html` in your web browser to view the documentation.
+After building, open `docs/build/dirhtml/index.html` in your web browser.
 
 ### 🌐 Live Documentation
 
@@ -545,8 +564,7 @@ Instead:
 If you need to test the README generation manually:
 
 ```bash
-# Populate README.md from template
-python dev/populate_project_readme.py
+uv run fab readme
 ```
 
 

NOTICE

@@ -26,6 +26,7 @@ This software includes the following third-party components:
 Core Dependencies:
 - aiolimiter: Rate limiting for asynchronous operations
 - colorlog: Colored logging formatter
+- docstring-parser: Docstring parsing for auto-generating tool schemas
 - fastjsonschema: Fast JSON schema validator
 - genai-prices: LLM pricing data and utilities (by Pydantic) to automatically estimate costs
 - Jinja2: Templating engine