Phase 2 build initial
This commit is contained in:
Claude Code
100
hcfs-python/docs/Makefile
Normal file
100
hcfs-python/docs/Makefile
Normal file
@@ -0,0 +1,100 @@
|
||||
# Makefile for Sphinx documentation
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Install documentation dependencies
|
||||
install:
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Build HTML documentation
|
||||
html:
|
||||
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
# Build PDF documentation using rst2pdf
|
||||
pdf:
|
||||
@$(SPHINXBUILD) -b pdf "$(SOURCEDIR)" "$(BUILDDIR)/pdf" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Build finished. The PDF file is in $(BUILDDIR)/pdf."
|
||||
|
||||
# Build PDF documentation using LaTeX
|
||||
latexpdf:
|
||||
@$(SPHINXBUILD) -b latex "$(SOURCEDIR)" "$(BUILDDIR)/latex" $(SPHINXOPTS) $(O)
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C "$(BUILDDIR)/latex" all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
# Build EPUB documentation
|
||||
epub:
|
||||
@$(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)/epub" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
# Build all formats
|
||||
all: html pdf epub
|
||||
@echo "All documentation formats built successfully."
|
||||
|
||||
# Clean build directory
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
@echo "Build directory cleaned."
|
||||
|
||||
# Development server with auto-reload
|
||||
serve:
|
||||
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" --host 0.0.0.0 --port 8080 --open-browser
|
||||
|
||||
# Check for broken links
|
||||
linkcheck:
|
||||
@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
# Check for spelling errors (requires sphinxcontrib-spelling)
|
||||
spelling:
|
||||
@$(SPHINXBUILD) -b spelling "$(SOURCEDIR)" "$(BUILDDIR)/spelling" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Spell check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/spelling/."
|
||||
|
||||
# Build API documentation only
|
||||
api-docs:
|
||||
sphinx-apidoc -o api ../hcfs --force --separate
|
||||
@echo "API documentation generated."
|
||||
|
||||
# Full rebuild (clean + build)
|
||||
rebuild: clean html
|
||||
@echo "Full rebuild complete."
|
||||
|
||||
# Check documentation coverage
|
||||
coverage:
|
||||
@$(SPHINXBUILD) -b coverage "$(SOURCEDIR)" "$(BUILDDIR)/coverage" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Coverage check complete; look for any missing documentation " \
|
||||
"in $(BUILDDIR)/coverage/."
|
||||
|
||||
# Generate documentation statistics
|
||||
stats:
|
||||
@echo "Documentation Statistics:"
|
||||
@echo "========================="
|
||||
@find . -name "*.rst" -type f | wc -l | xargs echo "RST files:"
|
||||
@find . -name "*.md" -type f | wc -l | xargs echo "Markdown files:"
|
||||
@find . -name "*.py" -path "../hcfs/*" -type f | wc -l | xargs echo "Python files:"
|
||||
@wc -l `find . -name "*.rst" -type f` | tail -1 | xargs echo "Total RST lines:"
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
143
hcfs-python/docs/_static/custom.css
vendored
Normal file
143
hcfs-python/docs/_static/custom.css
vendored
Normal file
@@ -0,0 +1,143 @@
|
||||
/* Custom CSS for HCFS Documentation */
|
||||
|
||||
/* Brand colors */
|
||||
:root {
|
||||
--hcfs-primary: #2E86AB;
|
||||
--hcfs-secondary: #A23B72;
|
||||
--hcfs-accent: #F18F01;
|
||||
--hcfs-success: #C73E1D;
|
||||
--hcfs-dark: #1A1A1A;
|
||||
--hcfs-light: #F8F9FA;
|
||||
}
|
||||
|
||||
/* Header customization */
|
||||
.wy-nav-top {
|
||||
background-color: var(--hcfs-primary) !important;
|
||||
}
|
||||
|
||||
/* Sidebar customization */
|
||||
.wy-nav-side {
|
||||
background-color: var(--hcfs-dark);
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current > a {
|
||||
background-color: var(--hcfs-primary);
|
||||
border-right: 3px solid var(--hcfs-accent);
|
||||
}
|
||||
|
||||
.wy-menu-vertical li.current a:hover {
|
||||
background-color: var(--hcfs-secondary);
|
||||
}
|
||||
|
||||
/* Code blocks */
|
||||
.highlight {
|
||||
background-color: #f8f8f8;
|
||||
border: 1px solid #e1e4e5;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
/* API documentation styling */
|
||||
.openapi-spec {
|
||||
border: 1px solid #ddd;
|
||||
border-radius: 8px;
|
||||
margin: 20px 0;
|
||||
}
|
||||
|
||||
.http-method {
|
||||
font-weight: bold;
|
||||
padding: 2px 6px;
|
||||
border-radius: 3px;
|
||||
color: white;
|
||||
font-size: 0.9em;
|
||||
}
|
||||
|
||||
.http-method.get { background-color: #61affe; }
|
||||
.http-method.post { background-color: #49cc90; }
|
||||
.http-method.put { background-color: #fca130; }
|
||||
.http-method.patch { background-color: #50e3c2; }
|
||||
.http-method.delete { background-color: #f93e3e; }
|
||||
|
||||
/* SDK documentation styling */
|
||||
.sdk-example {
|
||||
background-color: #f8f9fa;
|
||||
border-left: 4px solid var(--hcfs-primary);
|
||||
padding: 15px;
|
||||
margin: 20px 0;
|
||||
}
|
||||
|
||||
.sdk-example .highlight {
|
||||
background-color: transparent;
|
||||
border: none;
|
||||
}
|
||||
|
||||
/* Badges */
|
||||
.badge {
|
||||
display: inline-block;
|
||||
padding: 0.25em 0.4em;
|
||||
font-size: 75%;
|
||||
font-weight: 700;
|
||||
line-height: 1;
|
||||
text-align: center;
|
||||
white-space: nowrap;
|
||||
vertical-align: baseline;
|
||||
border-radius: 0.25rem;
|
||||
margin: 2px;
|
||||
}
|
||||
|
||||
.badge-new { background-color: var(--hcfs-success); color: white; }
|
||||
.badge-deprecated { background-color: #6c757d; color: white; }
|
||||
.badge-async { background-color: var(--hcfs-accent); color: white; }
|
||||
.badge-sync { background-color: var(--hcfs-secondary); color: white; }
|
||||
|
||||
/* Version information */
|
||||
.version-info {
|
||||
background-color: #e7f3ff;
|
||||
border: 1px solid #b8daff;
|
||||
border-radius: 4px;
|
||||
padding: 10px;
|
||||
margin: 15px 0;
|
||||
}
|
||||
|
||||
/* Performance notes */
|
||||
.performance-note {
|
||||
background-color: #fff3cd;
|
||||
border: 1px solid #ffeaa7;
|
||||
border-radius: 4px;
|
||||
padding: 10px;
|
||||
margin: 15px 0;
|
||||
}
|
||||
|
||||
/* Security warnings */
|
||||
.security-warning {
|
||||
background-color: #f8d7da;
|
||||
border: 1px solid #f5c6cb;
|
||||
border-radius: 4px;
|
||||
padding: 10px;
|
||||
margin: 15px 0;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
.wy-table-responsive table td,
|
||||
.wy-table-responsive table th {
|
||||
white-space: normal;
|
||||
}
|
||||
|
||||
/* Mobile responsiveness */
|
||||
@media screen and (max-width: 768px) {
|
||||
.rst-content .sidebar {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
|
||||
/* Print styles */
|
||||
@media print {
|
||||
.wy-nav-side,
|
||||
.wy-nav-top,
|
||||
.rst-versions {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.wy-nav-content-wrap {
|
||||
margin-left: 0;
|
||||
}
|
||||
}
|
||||
263
hcfs-python/docs/api/reference.rst
Normal file
263
hcfs-python/docs/api/reference.rst
Normal file
@@ -0,0 +1,263 @@
|
||||
API Reference
|
||||
=============
|
||||
|
||||
Complete OpenAPI/Swagger documentation for the HCFS REST API.
|
||||
|
||||
Interactive Documentation
|
||||
--------------------------
|
||||
|
||||
The HCFS API provides interactive documentation through:
|
||||
|
||||
* **Swagger UI**: Available at ``/docs`` endpoint
|
||||
* **ReDoc**: Available at ``/redoc`` endpoint
|
||||
* **OpenAPI Spec**: Available at ``/openapi.json`` endpoint
|
||||
|
||||
Base URL
|
||||
--------
|
||||
|
||||
Production API:
|
||||
https://api.hcfs.dev/v1
|
||||
|
||||
Staging API:
|
||||
https://staging-api.hcfs.dev/v1
|
||||
|
||||
Local Development:
|
||||
http://localhost:8000
|
||||
|
||||
Authentication
|
||||
--------------
|
||||
|
||||
The API supports two authentication methods:
|
||||
|
||||
API Key Authentication
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Include your API key in the request header:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
X-API-Key: your-api-key-here
|
||||
|
||||
JWT Token Authentication
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Include a JWT bearer token in the authorization header:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
Authorization: Bearer your-jwt-token-here
|
||||
|
||||
Rate Limiting
|
||||
-------------
|
||||
|
||||
All API endpoints are rate limited to ensure fair usage:
|
||||
|
||||
* **Default Limit**: 100 requests per minute
|
||||
* **Burst Limit**: 20 requests per burst
|
||||
* **Rate Limit Headers**: Included in all responses
|
||||
|
||||
Rate limit headers:
|
||||
|
||||
* ``X-RateLimit-Limit``: Maximum requests per window
|
||||
* ``X-RateLimit-Remaining``: Remaining requests in current window
|
||||
* ``X-RateLimit-Reset``: Unix timestamp when window resets
|
||||
* ``Retry-After``: Seconds to wait when rate limited
|
||||
|
||||
Complete API Specification
|
||||
---------------------------
|
||||
|
||||
.. openapi:: ../../openapi.yaml
|
||||
:format: swagger
|
||||
:examples:
|
||||
|
||||
Error Handling
|
||||
--------------
|
||||
|
||||
The API uses standard HTTP status codes and returns consistent error responses:
|
||||
|
||||
Success Codes
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
* ``200 OK``: Request successful
|
||||
* ``201 Created``: Resource created successfully
|
||||
|
||||
Client Error Codes
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``400 Bad Request``: Invalid request data
|
||||
* ``401 Unauthorized``: Authentication required
|
||||
* ``403 Forbidden``: Insufficient permissions
|
||||
* ``404 Not Found``: Resource not found
|
||||
* ``422 Unprocessable Entity``: Validation error
|
||||
* ``429 Too Many Requests``: Rate limit exceeded
|
||||
|
||||
Server Error Codes
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``500 Internal Server Error``: Server error
|
||||
* ``502 Bad Gateway``: Upstream server error
|
||||
* ``503 Service Unavailable``: Service temporarily unavailable
|
||||
|
||||
Error Response Format
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
All error responses follow this structure:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"success": false,
|
||||
"error": "Brief error description",
|
||||
"error_details": [
|
||||
{
|
||||
"field": "field_name",
|
||||
"message": "Detailed error message",
|
||||
"code": "error_code"
|
||||
}
|
||||
],
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"request_id": "req_123456789",
|
||||
"api_version": "v1"
|
||||
}
|
||||
|
||||
Response Format
|
||||
---------------
|
||||
|
||||
All API responses follow a consistent structure:
|
||||
|
||||
Success Response
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"success": true,
|
||||
"data": { /* response data */ },
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"api_version": "v1"
|
||||
}
|
||||
|
||||
List Response with Pagination
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"success": true,
|
||||
"data": [ /* array of items */ ],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"page_size": 20,
|
||||
"total_items": 150,
|
||||
"total_pages": 8,
|
||||
"has_next": true,
|
||||
"has_previous": false
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"api_version": "v1"
|
||||
}
|
||||
|
||||
WebSocket API
|
||||
-------------
|
||||
|
||||
Real-time updates are available through WebSocket connections.
|
||||
|
||||
Connection
|
||||
~~~~~~~~~~
|
||||
|
||||
Connect to: ``wss://api.hcfs.dev/ws`` (or ``ws://localhost:8000/ws`` for local)
|
||||
|
||||
Authentication
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Include authentication in connection headers:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
const ws = new WebSocket('wss://api.hcfs.dev/ws', {
|
||||
headers: {
|
||||
'X-API-Key': 'your-api-key'
|
||||
}
|
||||
});
|
||||
|
||||
Subscription
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Subscribe to events by sending a subscription message:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"type": "subscribe",
|
||||
"data": {
|
||||
"path_prefix": "/docs",
|
||||
"event_types": ["created", "updated", "deleted"],
|
||||
"filters": {}
|
||||
}
|
||||
}
|
||||
|
||||
Event Messages
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
You'll receive event messages in this format:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"type": "context_created",
|
||||
"data": {
|
||||
"id": 123,
|
||||
"path": "/docs/new-guide",
|
||||
"content": "...",
|
||||
/* full context object */
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
|
||||
Monitoring
|
||||
----------
|
||||
|
||||
Health Check
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Monitor API health:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
GET /health
|
||||
|
||||
Returns component health status and response times.
|
||||
|
||||
Metrics
|
||||
~~~~~~~
|
||||
|
||||
Prometheus metrics available at:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
GET /metrics
|
||||
|
||||
Includes request counts, response times, and system metrics.
|
||||
|
||||
SDK Integration
|
||||
---------------
|
||||
|
||||
For easier API integration, use the official Python SDK:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install hcfs-sdk
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import HCFSClient
|
||||
|
||||
client = HCFSClient(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key"
|
||||
)
|
||||
|
||||
# The SDK handles authentication, retries, and error handling automatically
|
||||
contexts = client.list_contexts()
|
||||
|
||||
See the :doc:`../sdk/overview` for complete SDK documentation.
|
||||
243
hcfs-python/docs/conf.py
Normal file
243
hcfs-python/docs/conf.py
Normal file
@@ -0,0 +1,243 @@
|
||||
"""
|
||||
Configuration file for Sphinx documentation builder.
|
||||
|
||||
This file only contains a selection of the most common options. For a full
|
||||
list see the documentation:
|
||||
https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
from datetime import datetime
|
||||
|
||||
# Add the project root and source directories to the path
|
||||
sys.path.insert(0, os.path.abspath('../'))
|
||||
sys.path.insert(0, os.path.abspath('../hcfs'))
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'HCFS'
|
||||
copyright = f'{datetime.now().year}, HCFS Development Team'
|
||||
author = 'HCFS Development Team'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '2.0.0'
|
||||
version = '2.0.0'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# extensions.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.autosummary',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinx.ext.napoleon',
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.coverage',
|
||||
'sphinx.ext.doctest',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx.ext.mathjax',
|
||||
'sphinx_autodoc_typehints',
|
||||
'sphinx_copybutton',
|
||||
'myst_parser',
|
||||
'sphinxcontrib.openapi',
|
||||
'sphinxcontrib.httpdomain',
|
||||
'sphinx_design',
|
||||
'autoapi.extension',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
source_suffix = {
|
||||
'.rst': None,
|
||||
'.md': 'myst_parser',
|
||||
}
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages.
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
html_theme_options = {
|
||||
'collapse_navigation': False,
|
||||
'sticky_navigation': True,
|
||||
'navigation_depth': 4,
|
||||
'includehidden': True,
|
||||
'titles_only': False,
|
||||
'logo_only': False,
|
||||
'display_version': True,
|
||||
'prev_next_buttons_location': 'bottom',
|
||||
'style_external_links': True,
|
||||
}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom CSS files
|
||||
html_css_files = [
|
||||
'custom.css',
|
||||
]
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
html_pygments_style = 'sphinx'
|
||||
|
||||
# Logo and favicon
|
||||
html_logo = '_static/logo.png'
|
||||
html_favicon = '_static/favicon.ico'
|
||||
|
||||
# -- Extension configuration -------------------------------------------------
|
||||
|
||||
# Napoleon settings for Google/NumPy style docstrings
|
||||
napoleon_google_docstring = True
|
||||
napoleon_numpy_docstring = True
|
||||
napoleon_include_init_with_doc = False
|
||||
napoleon_include_private_with_doc = False
|
||||
napoleon_include_special_with_doc = True
|
||||
napoleon_use_admonition_for_examples = False
|
||||
napoleon_use_admonition_for_notes = False
|
||||
napoleon_use_admonition_for_references = False
|
||||
napoleon_use_ivar = False
|
||||
napoleon_use_param = True
|
||||
napoleon_use_rtype = True
|
||||
napoleon_preprocess_types = False
|
||||
napoleon_type_aliases = None
|
||||
napoleon_attr_annotations = True
|
||||
|
||||
# Autodoc settings
|
||||
autodoc_default_options = {
|
||||
'members': True,
|
||||
'member-order': 'bysource',
|
||||
'special-members': '__init__',
|
||||
'undoc-members': True,
|
||||
'exclude-members': '__weakref__'
|
||||
}
|
||||
|
||||
autodoc_typehints = 'description'
|
||||
autodoc_typehints_description_target = 'documented'
|
||||
|
||||
# AutoAPI settings for automatic API documentation
|
||||
autoapi_type = 'python'
|
||||
autoapi_dirs = ['../hcfs']
|
||||
autoapi_root = 'api'
|
||||
autoapi_add_toctree_entry = False
|
||||
autoapi_generate_api_docs = True
|
||||
autoapi_python_class_content = 'both'
|
||||
autoapi_member_order = 'bysource'
|
||||
autoapi_options = [
|
||||
'members',
|
||||
'undoc-members',
|
||||
'show-inheritance',
|
||||
'show-module-summary',
|
||||
'special-members',
|
||||
'imported-members',
|
||||
]
|
||||
|
||||
# Intersphinx mapping for cross-references
|
||||
intersphinx_mapping = {
|
||||
'python': ('https://docs.python.org/3/', None),
|
||||
'numpy': ('https://numpy.org/doc/stable/', None),
|
||||
'scipy': ('https://docs.scipy.org/doc/scipy/', None),
|
||||
'scikit-learn': ('https://scikit-learn.org/stable/', None),
|
||||
'pandas': ('https://pandas.pydata.org/docs/', None),
|
||||
'fastapi': ('https://fastapi.tiangolo.com/', None),
|
||||
'pydantic': ('https://docs.pydantic.dev/latest/', None),
|
||||
'httpx': ('https://www.python-httpx.org/', None),
|
||||
}
|
||||
|
||||
# TODO extension
|
||||
todo_include_todos = True
|
||||
|
||||
# MyST parser settings
|
||||
myst_enable_extensions = [
|
||||
"colon_fence",
|
||||
"deflist",
|
||||
"dollarmath",
|
||||
"fieldlist",
|
||||
"html_admonition",
|
||||
"html_image",
|
||||
"linkify",
|
||||
"replacements",
|
||||
"smartquotes",
|
||||
"strikethrough",
|
||||
"substitution",
|
||||
"tasklist",
|
||||
]
|
||||
|
||||
# Copy button settings
|
||||
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
|
||||
copybutton_prompt_is_regexp = True
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------
|
||||
|
||||
latex_engine = 'pdflatex'
|
||||
latex_elements = {
|
||||
'papersize': 'letterpaper',
|
||||
'pointsize': '10pt',
|
||||
'preamble': r'''
|
||||
\usepackage{charter}
|
||||
\usepackage[defaultsans]{lato}
|
||||
\usepackage{inconsolata}
|
||||
''',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'HCFS.tex', 'HCFS Documentation',
|
||||
'HCFS Development Team', 'manual'),
|
||||
]
|
||||
|
||||
# -- Options for manual page output ------------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'hcfs', 'HCFS Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
# -- Options for Texinfo output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'HCFS', 'HCFS Documentation',
|
||||
author, 'HCFS', 'Context-Aware Hierarchical Context File System.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
# -- Options for Epub output -------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
epub_author = author
|
||||
epub_publisher = author
|
||||
epub_copyright = copyright
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ['search.html']
|
||||
|
||||
# -- Custom configuration ----------------------------------------------------
|
||||
|
||||
def setup(app):
|
||||
"""Custom setup function."""
|
||||
app.add_css_file('custom.css')
|
||||
|
||||
# Add custom directives or configurations here
|
||||
pass
|
||||
|
||||
# API Documentation settings
|
||||
openapi_spec_path = '../openapi.yaml'
|
||||
154
hcfs-python/docs/index.rst
Normal file
154
hcfs-python/docs/index.rst
Normal file
@@ -0,0 +1,154 @@
|
||||
HCFS Documentation
|
||||
==================
|
||||
|
||||
Welcome to the **Context-Aware Hierarchical Context File System (HCFS)** documentation!
|
||||
|
||||
HCFS is a production-grade system for managing, searching, and analyzing hierarchical context data with advanced AI capabilities. It provides both a powerful REST API and comprehensive Python SDK for seamless integration.
|
||||
|
||||
.. image:: https://img.shields.io/badge/version-2.0.0-blue.svg
|
||||
:target: https://github.com/hcfs/hcfs
|
||||
:alt: Version
|
||||
|
||||
.. image:: https://img.shields.io/badge/python-3.8%2B-blue.svg
|
||||
:target: https://python.org
|
||||
:alt: Python Version
|
||||
|
||||
.. image:: https://img.shields.io/badge/license-MIT-green.svg
|
||||
:target: https://opensource.org/licenses/MIT
|
||||
:alt: License
|
||||
|
||||
Quick Start
|
||||
-----------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import HCFSAsyncClient, Context
|
||||
|
||||
async def main():
|
||||
async with HCFSAsyncClient(
|
||||
base_url="https://api.hcfs.example.com",
|
||||
api_key="your-api-key"
|
||||
) as client:
|
||||
# Create a context
|
||||
context = Context(
|
||||
path="/docs/getting-started",
|
||||
content="This is your first HCFS context!",
|
||||
summary="Getting started guide"
|
||||
)
|
||||
|
||||
created = await client.create_context(context)
|
||||
print(f"Created context: {created.id}")
|
||||
|
||||
# Search contexts
|
||||
results = await client.search_contexts("getting started")
|
||||
for result in results:
|
||||
print(f"Found: {result.context.path} (score: {result.score:.3f})")
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
🚀 **Production-Ready API**
|
||||
- RESTful API with OpenAPI/Swagger documentation
|
||||
- WebSocket support for real-time updates
|
||||
- Advanced authentication and authorization
|
||||
- Rate limiting and monitoring
|
||||
|
||||
🔍 **Intelligent Search**
|
||||
- Semantic search using state-of-the-art embeddings
|
||||
- Hybrid search combining semantic and keyword matching
|
||||
- Fuzzy search with typo tolerance
|
||||
- Advanced filtering and sorting
|
||||
|
||||
📦 **Comprehensive SDK**
|
||||
- Synchronous and asynchronous Python clients
|
||||
- Built-in caching and retry mechanisms
|
||||
- Batch operations for high throughput
|
||||
- Streaming capabilities with WebSocket
|
||||
|
||||
⚡ **High Performance**
|
||||
- Optimized vector search with FAISS
|
||||
- Intelligent caching strategies
|
||||
- Connection pooling and async operations
|
||||
- Horizontal scaling support
|
||||
|
||||
🔒 **Enterprise Security**
|
||||
- JWT and API key authentication
|
||||
- Role-based access control
|
||||
- Rate limiting and DDoS protection
|
||||
- Audit logging and monitoring
|
||||
|
||||
Table of Contents
|
||||
-----------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Getting Started
|
||||
|
||||
installation
|
||||
quickstart
|
||||
configuration
|
||||
examples
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: API Documentation
|
||||
|
||||
api/overview
|
||||
api/authentication
|
||||
api/contexts
|
||||
api/search
|
||||
api/batch
|
||||
api/websocket
|
||||
api/reference
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: SDK Documentation
|
||||
|
||||
sdk/overview
|
||||
sdk/clients
|
||||
sdk/models
|
||||
sdk/utilities
|
||||
sdk/decorators
|
||||
sdk/examples
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Advanced Topics
|
||||
|
||||
advanced/deployment
|
||||
advanced/monitoring
|
||||
advanced/performance
|
||||
advanced/clustering
|
||||
advanced/customization
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Reference
|
||||
|
||||
changelog
|
||||
contributing
|
||||
license
|
||||
api/api
|
||||
|
||||
Support and Community
|
||||
---------------------
|
||||
|
||||
Need help? Here's how to get support:
|
||||
|
||||
* 📚 **Documentation**: You're reading it! Check the sections above.
|
||||
* 🐛 **Bug Reports**: `GitHub Issues <https://github.com/hcfs/hcfs/issues>`_
|
||||
* 💬 **Discussions**: `GitHub Discussions <https://github.com/hcfs/hcfs/discussions>`_
|
||||
* 📧 **Email**: support@hcfs.dev
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
HCFS is released under the MIT License. See the `LICENSE <https://github.com/hcfs/hcfs/blob/main/LICENSE>`_ file for details.
|
||||
|
||||
Indices and Tables
|
||||
------------------
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
368
hcfs-python/docs/installation.rst
Normal file
368
hcfs-python/docs/installation.rst
Normal file
@@ -0,0 +1,368 @@
|
||||
Installation
|
||||
============
|
||||
|
||||
This guide covers installing HCFS and its SDK in various environments.
|
||||
|
||||
Quick Installation
|
||||
------------------
|
||||
|
||||
The fastest way to get started is to install the HCFS SDK from PyPI:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install hcfs-sdk
|
||||
|
||||
This installs the core SDK with basic dependencies.
|
||||
|
||||
Full Installation
|
||||
-----------------
|
||||
|
||||
For all features including WebSocket support, monitoring, and development tools:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install hcfs-sdk[all]
|
||||
|
||||
This includes optional dependencies for:
|
||||
|
||||
* WebSocket streaming (``websockets``)
|
||||
* Advanced monitoring (``prometheus-client``, ``structlog``)
|
||||
* Development tools (``pytest``, ``black``, ``mypy``)
|
||||
|
||||
Selective Installation
|
||||
----------------------
|
||||
|
||||
You can install specific feature sets:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# WebSocket streaming support
|
||||
pip install hcfs-sdk[websocket]
|
||||
|
||||
# Monitoring and observability
|
||||
pip install hcfs-sdk[monitoring]
|
||||
|
||||
# Development and testing
|
||||
pip install hcfs-sdk[dev]
|
||||
|
||||
# Production deployment
|
||||
pip install hcfs-sdk[production]
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
System Requirements
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* **Python**: 3.8 or higher
|
||||
* **Operating System**: Linux, macOS, or Windows
|
||||
* **Memory**: Minimum 512MB RAM, 2GB+ recommended for production
|
||||
* **Storage**: 100MB for installation, varies by usage
|
||||
|
||||
Python Dependencies
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Core dependencies (installed automatically):
|
||||
|
||||
* ``httpx >= 0.25.0`` - HTTP client
|
||||
* ``pydantic >= 2.5.0`` - Data validation
|
||||
* ``requests >= 2.31.0`` - HTTP library
|
||||
|
||||
Optional dependencies by feature:
|
||||
|
||||
**WebSocket Support**:
|
||||
* ``websockets >= 12.0``
|
||||
|
||||
**Monitoring**:
|
||||
* ``prometheus-client >= 0.19.0``
|
||||
* ``structlog >= 23.2.0``
|
||||
|
||||
**Development**:
|
||||
* ``pytest >= 7.4.0``
|
||||
* ``pytest-asyncio >= 0.21.0``
|
||||
* ``black >= 23.9.0``
|
||||
* ``mypy >= 1.6.0``
|
||||
|
||||
Virtual Environment Setup
|
||||
--------------------------
|
||||
|
||||
We strongly recommend using a virtual environment:
|
||||
|
||||
Using venv
|
||||
~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv hcfs-env
|
||||
|
||||
# Activate (Linux/macOS)
|
||||
source hcfs-env/bin/activate
|
||||
|
||||
# Activate (Windows)
|
||||
hcfs-env\\Scripts\\activate
|
||||
|
||||
# Install HCFS
|
||||
pip install hcfs-sdk[all]
|
||||
|
||||
Using conda
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Create conda environment
|
||||
conda create -n hcfs-env python=3.9
|
||||
|
||||
# Activate environment
|
||||
conda activate hcfs-env
|
||||
|
||||
# Install HCFS
|
||||
pip install hcfs-sdk[all]
|
||||
|
||||
Using Poetry
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Initialize project
|
||||
poetry init
|
||||
|
||||
# Add HCFS dependency
|
||||
poetry add hcfs-sdk[all]
|
||||
|
||||
# Install dependencies
|
||||
poetry install
|
||||
|
||||
Development Installation
|
||||
------------------------
|
||||
|
||||
For development work on HCFS itself:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/hcfs/hcfs.git
|
||||
cd hcfs
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # or venv\\Scripts\\activate on Windows
|
||||
|
||||
# Install in development mode
|
||||
pip install -e .[dev]
|
||||
|
||||
# Install pre-commit hooks
|
||||
pre-commit install
|
||||
|
||||
This installs HCFS in "editable" mode, so changes to the source code are immediately available.
|
||||
|
||||
Docker Installation
|
||||
-------------------
|
||||
|
||||
Run HCFS API server using Docker:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Run with default settings
|
||||
docker run -p 8000:8000 hcfs/hcfs-api:latest
|
||||
|
||||
# Run with custom configuration
|
||||
docker run -p 8000:8000 \
|
||||
-e HCFS_API_KEY=your-api-key \
|
||||
-e HCFS_DB_PATH=/data/hcfs.db \
|
||||
-v /host/data:/data \
|
||||
hcfs/hcfs-api:latest
|
||||
|
||||
Docker Compose
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
For a complete setup with database and monitoring:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
version: '3.8'
|
||||
services:
|
||||
hcfs-api:
|
||||
image: hcfs/hcfs-api:latest
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- HCFS_DB_PATH=/data/hcfs.db
|
||||
- HCFS_API_ENABLE_METRICS=true
|
||||
volumes:
|
||||
- hcfs_data:/data
|
||||
depends_on:
|
||||
- redis
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
ports:
|
||||
- "6379:6379"
|
||||
|
||||
volumes:
|
||||
hcfs_data:
|
||||
|
||||
Verification
|
||||
------------
|
||||
|
||||
Verify your installation:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import hcfs.sdk
|
||||
print(f"HCFS SDK version: {hcfs.sdk.__version__}")
|
||||
|
||||
# Test basic functionality
|
||||
from hcfs.sdk import HCFSClient, Context
|
||||
|
||||
# This will fail without a running server, but validates imports
|
||||
try:
|
||||
client = HCFSClient(base_url="http://localhost:8000", api_key="test")
|
||||
print("SDK imported successfully!")
|
||||
except Exception as e:
|
||||
print(f"SDK imported (server not running): {e}")
|
||||
|
||||
Command Line Interface
|
||||
----------------------
|
||||
|
||||
HCFS includes a CLI for common operations:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Check version
|
||||
hcfs --version
|
||||
|
||||
# Test API connection
|
||||
hcfs health --url http://localhost:8000 --api-key your-key
|
||||
|
||||
# Run API server
|
||||
hcfs serve --port 8000 --workers 4
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The SDK can be configured through:
|
||||
|
||||
1. **Environment Variables**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export HCFS_BASE_URL=https://api.hcfs.dev/v1
|
||||
export HCFS_API_KEY=your-api-key
|
||||
export HCFS_TIMEOUT=30.0
|
||||
|
||||
2. **Configuration File** (``~/.hcfs/config.yaml``):
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
base_url: https://api.hcfs.dev/v1
|
||||
api_key: your-api-key
|
||||
timeout: 30.0
|
||||
cache:
|
||||
enabled: true
|
||||
max_size: 1000
|
||||
ttl_seconds: 3600
|
||||
|
||||
3. **Programmatic Configuration**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import HCFSClient, ClientConfig
|
||||
|
||||
config = ClientConfig(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key",
|
||||
timeout=30.0
|
||||
)
|
||||
|
||||
client = HCFSClient(config=config)
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
Common Issues
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
**ImportError: No module named 'hcfs'**
|
||||
Ensure you've activated your virtual environment and installed the package:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip list | grep hcfs
|
||||
|
||||
**Connection errors**
|
||||
Verify the API server is running and accessible:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -I http://localhost:8000/health
|
||||
|
||||
**Permission errors on Windows**
|
||||
Run command prompt as administrator or use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install --user hcfs-sdk
|
||||
|
||||
**SSL certificate errors**
|
||||
For development, you can disable SSL verification:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import httpx
|
||||
client = HCFSClient(
|
||||
base_url="https://localhost:8000",
|
||||
api_key="test",
|
||||
verify=False
|
||||
)
|
||||
|
||||
Getting Help
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Check this documentation
|
||||
2. Search `GitHub Issues <https://github.com/hcfs/hcfs/issues>`_
|
||||
3. Create a new issue with:
|
||||
|
||||
* Python version (``python --version``)
|
||||
* HCFS version (``pip show hcfs-sdk``)
|
||||
* Operating system
|
||||
* Full error message and traceback
|
||||
* Minimal code example that reproduces the issue
|
||||
|
||||
Updating
|
||||
--------
|
||||
|
||||
Keep your installation up to date:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Update to latest version
|
||||
pip install --upgrade hcfs-sdk
|
||||
|
||||
# Update with all dependencies
|
||||
pip install --upgrade hcfs-sdk[all]
|
||||
|
||||
# Check current version
|
||||
pip show hcfs-sdk
|
||||
|
||||
For development installations:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# Update dependencies
|
||||
pip install -e .[dev] --upgrade
|
||||
|
||||
Next Steps
|
||||
----------
|
||||
|
||||
After installation:
|
||||
|
||||
1. Read the :doc:`quickstart` guide
|
||||
2. Configure your :doc:`configuration`
|
||||
3. Explore the :doc:`examples`
|
||||
4. Review the :doc:`sdk/overview` for advanced usage
|
||||
28
hcfs-python/docs/requirements.txt
Normal file
28
hcfs-python/docs/requirements.txt
Normal file
@@ -0,0 +1,28 @@
|
||||
# Documentation requirements
|
||||
|
||||
# Sphinx and extensions
|
||||
sphinx>=7.1.0
|
||||
sphinx-rtd-theme>=1.3.0
|
||||
sphinx-autodoc-typehints>=1.24.0
|
||||
sphinx-copybutton>=0.5.2
|
||||
myst-parser>=2.0.0
|
||||
|
||||
# API documentation
|
||||
sphinxcontrib-openapi>=0.8.0
|
||||
sphinxcontrib-httpdomain>=1.8.1
|
||||
|
||||
# PDF generation
|
||||
rst2pdf>=0.101
|
||||
rinohtype>=0.5.4
|
||||
|
||||
# Code documentation
|
||||
sphinx-autoapi>=3.0.0
|
||||
sphinx-code-include>=1.1.1
|
||||
|
||||
# Additional utilities
|
||||
sphinx-sitemap>=2.5.1
|
||||
sphinx-design>=0.5.0
|
||||
nbsphinx>=0.9.1
|
||||
|
||||
# Development
|
||||
sphinx-autobuild>=2021.3.14
|
||||
445
hcfs-python/docs/sdk/overview.rst
Normal file
445
hcfs-python/docs/sdk/overview.rst
Normal file
@@ -0,0 +1,445 @@
|
||||
SDK Overview
|
||||
============
|
||||
|
||||
The HCFS Python SDK provides a comprehensive, production-ready interface for interacting with the HCFS API. It offers both synchronous and asynchronous clients with built-in caching, retry mechanisms, and advanced features.
|
||||
|
||||
.. currentmodule:: hcfs.sdk
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
🚀 **Dual Client Support**
|
||||
- Synchronous client for traditional applications
|
||||
- Asynchronous client with full async/await support
|
||||
- WebSocket streaming capabilities
|
||||
|
||||
⚡ **Performance Optimized**
|
||||
- Built-in caching with configurable strategies
|
||||
- Connection pooling and keep-alive
|
||||
- Batch operations for high throughput
|
||||
- Smart retry mechanisms with backoff
|
||||
|
||||
🛡️ **Production Ready**
|
||||
- Comprehensive error handling
|
||||
- Rate limiting and timeout management
|
||||
- Request/response validation
|
||||
- Analytics and monitoring
|
||||
|
||||
🔧 **Developer Friendly**
|
||||
- Type hints throughout
|
||||
- Rich configuration options
|
||||
- Extensive examples and documentation
|
||||
- Decorator-based utilities
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
Install from PyPI:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install hcfs-sdk
|
||||
|
||||
Or install with all optional dependencies:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install hcfs-sdk[all]
|
||||
|
||||
Quick Start
|
||||
-----------
|
||||
|
||||
Synchronous Client
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import HCFSClient, Context
|
||||
|
||||
# Initialize client
|
||||
client = HCFSClient(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key"
|
||||
)
|
||||
|
||||
# Create a context
|
||||
context = Context(
|
||||
path="/docs/quickstart",
|
||||
content="This is a quick start guide",
|
||||
summary="Getting started with HCFS"
|
||||
)
|
||||
|
||||
created_context = client.create_context(context)
|
||||
print(f"Created context: {created_context.id}")
|
||||
|
||||
# Search contexts
|
||||
results = client.search_contexts("quick start guide")
|
||||
for result in results:
|
||||
print(f"Found: {result.context.path} (score: {result.score:.3f})")
|
||||
|
||||
# Clean up
|
||||
client.close()
|
||||
|
||||
Asynchronous Client
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from hcfs.sdk import HCFSAsyncClient, Context
|
||||
|
||||
async def main():
|
||||
async with HCFSAsyncClient(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key"
|
||||
) as client:
|
||||
# Create multiple contexts concurrently
|
||||
contexts = [
|
||||
Context(path=f"/docs/guide-{i}", content=f"Guide {i}")
|
||||
for i in range(5)
|
||||
]
|
||||
|
||||
# Batch create
|
||||
result = await client.batch_create_contexts(contexts)
|
||||
print(f"Created {result.success_count} contexts")
|
||||
|
||||
# Async iteration
|
||||
async for context in client.iterate_contexts():
|
||||
print(f"Context: {context.path}")
|
||||
if context.id > 100: # Stop after some point
|
||||
break
|
||||
|
||||
asyncio.run(main())
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The SDK is highly configurable through the :class:`ClientConfig` class:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import HCFSClient, ClientConfig, CacheConfig, RetryConfig
|
||||
|
||||
config = ClientConfig(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key",
|
||||
timeout=30.0,
|
||||
|
||||
# Cache configuration
|
||||
cache=CacheConfig(
|
||||
enabled=True,
|
||||
max_size=2000,
|
||||
ttl_seconds=3600,
|
||||
strategy="lru"
|
||||
),
|
||||
|
||||
# Retry configuration
|
||||
retry=RetryConfig(
|
||||
enabled=True,
|
||||
max_attempts=3,
|
||||
base_delay=1.0,
|
||||
strategy="exponential_backoff"
|
||||
),
|
||||
|
||||
# Connection settings
|
||||
max_connections=100,
|
||||
max_keepalive_connections=20
|
||||
)
|
||||
|
||||
client = HCFSClient(config=config)
|
||||
|
||||
Core Classes
|
||||
------------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: generated/
|
||||
|
||||
HCFSClient
|
||||
HCFSAsyncClient
|
||||
Context
|
||||
SearchResult
|
||||
ContextFilter
|
||||
PaginationOptions
|
||||
SearchOptions
|
||||
ClientConfig
|
||||
|
||||
Client Classes
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
:class:`HCFSClient`
|
||||
Synchronous client for HCFS API operations. Best for traditional applications
|
||||
and when you don't need async/await support.
|
||||
|
||||
:class:`HCFSAsyncClient`
|
||||
Asynchronous client with full async/await support. Includes WebSocket
|
||||
streaming capabilities and is ideal for high-performance applications.
|
||||
|
||||
Data Models
|
||||
~~~~~~~~~~~
|
||||
|
||||
:class:`Context`
|
||||
Represents a context object with path, content, metadata, and other properties.
|
||||
Includes validation and conversion methods.
|
||||
|
||||
:class:`SearchResult`
|
||||
Contains a context and its relevance score from search operations.
|
||||
Supports sorting and comparison operations.
|
||||
|
||||
:class:`ContextFilter`
|
||||
Defines filtering criteria for listing contexts. Supports path prefixes,
|
||||
authors, status, date ranges, and custom filters.
|
||||
|
||||
Configuration Models
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:class:`ClientConfig`
|
||||
Main configuration class that combines all subsystem configurations.
|
||||
Supports environment variables and YAML configuration files.
|
||||
|
||||
:class:`CacheConfig`
|
||||
Cache configuration with support for multiple eviction strategies.
|
||||
|
||||
:class:`RetryConfig`
|
||||
Retry configuration with multiple backoff strategies and error handling.
|
||||
|
||||
Advanced Features
|
||||
-----------------
|
||||
|
||||
Caching
|
||||
~~~~~~~
|
||||
|
||||
The SDK includes intelligent caching with configurable strategies:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import HCFSClient, CacheConfig
|
||||
from hcfs.sdk.decorators import cached_context
|
||||
|
||||
# Configure caching
|
||||
cache_config = CacheConfig(
|
||||
enabled=True,
|
||||
strategy="lru", # LRU, LFU, TTL, FIFO
|
||||
max_size=1000,
|
||||
ttl_seconds=3600
|
||||
)
|
||||
|
||||
client = HCFSClient(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key",
|
||||
cache=cache_config
|
||||
)
|
||||
|
||||
# Cache statistics
|
||||
stats = client.get_cache_stats()
|
||||
print(f"Cache hit rate: {stats.get('hit_rate', 0):.2%}")
|
||||
|
||||
Retry Logic
|
||||
~~~~~~~~~~~
|
||||
|
||||
Automatic retry with configurable strategies:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk import RetryConfig, RetryStrategy
|
||||
|
||||
retry_config = RetryConfig(
|
||||
enabled=True,
|
||||
max_attempts=5,
|
||||
strategy=RetryStrategy.EXPONENTIAL_BACKOFF,
|
||||
base_delay=1.0,
|
||||
max_delay=60.0,
|
||||
jitter=True,
|
||||
retry_on_status=[429, 500, 502, 503, 504]
|
||||
)
|
||||
|
||||
client = HCFSClient(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key",
|
||||
retry=retry_config
|
||||
)
|
||||
|
||||
Batch Operations
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Efficient batch processing with error handling:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
contexts = [
|
||||
Context(path=f"/batch/item-{i}", content=f"Content {i}")
|
||||
for i in range(100)
|
||||
]
|
||||
|
||||
# Batch create with automatic error handling
|
||||
result = client.batch_create_contexts(contexts)
|
||||
|
||||
print(f"Success: {result.success_count}")
|
||||
print(f"Errors: {result.error_count}")
|
||||
print(f"Success rate: {result.success_rate:.2%}")
|
||||
|
||||
# Handle failures
|
||||
for error in result.failed_items:
|
||||
print(f"Failed item {error['index']}: {error['error']}")
|
||||
|
||||
WebSocket Streaming
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Real-time updates with the async client:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from hcfs.sdk import HCFSAsyncClient
|
||||
|
||||
async def handle_event(event):
|
||||
print(f"Received {event.event_type}: {event.data}")
|
||||
|
||||
async def main():
|
||||
async with HCFSAsyncClient(
|
||||
base_url="https://api.hcfs.dev/v1",
|
||||
api_key="your-api-key"
|
||||
) as client:
|
||||
# Connect to WebSocket
|
||||
await client.connect_websocket(
|
||||
path_prefix="/docs",
|
||||
event_types=["created", "updated", "deleted"]
|
||||
)
|
||||
|
||||
# Add event listener
|
||||
client.add_event_listener(handle_event)
|
||||
|
||||
# Keep connection alive
|
||||
await asyncio.sleep(60)
|
||||
|
||||
asyncio.run(main())
|
||||
|
||||
Analytics and Monitoring
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Built-in analytics for monitoring SDK usage:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get usage analytics
|
||||
analytics = client.get_analytics()
|
||||
|
||||
print("Operation counts:")
|
||||
for operation, count in analytics.operation_count.items():
|
||||
print(f" {operation}: {count}")
|
||||
|
||||
print(f"Cache hit rate: {analytics.get_cache_hit_rate():.2%}")
|
||||
print(f"Error rate: {analytics.get_error_rate():.2%}")
|
||||
|
||||
Decorators
|
||||
~~~~~~~~~~
|
||||
|
||||
Utility decorators for common patterns:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk.decorators import cached_context, retry_on_failure, rate_limited
|
||||
|
||||
@cached_context()
|
||||
@retry_on_failure()
|
||||
@rate_limited(requests_per_second=5.0)
|
||||
def expensive_operation(client, query):
|
||||
return client.search_contexts(query)
|
||||
|
||||
Error Handling
|
||||
--------------
|
||||
|
||||
The SDK provides comprehensive error handling with specific exception types:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from hcfs.sdk.exceptions import (
|
||||
HCFSError, HCFSConnectionError, HCFSAuthenticationError,
|
||||
HCFSNotFoundError, HCFSValidationError, HCFSRateLimitError
|
||||
)
|
||||
|
||||
try:
|
||||
context = client.get_context(999999)
|
||||
except HCFSNotFoundError:
|
||||
print("Context not found")
|
||||
except HCFSAuthenticationError:
|
||||
print("Authentication failed")
|
||||
except HCFSRateLimitError as e:
|
||||
print(f"Rate limited. Retry after {e.retry_after} seconds")
|
||||
except HCFSConnectionError:
|
||||
print("Connection failed")
|
||||
except HCFSError as e:
|
||||
print(f"HCFS error: {e.message}")
|
||||
|
||||
Best Practices
|
||||
--------------
|
||||
|
||||
1. **Use Context Managers**
|
||||
Always use context managers (``with`` or ``async with``) to ensure proper cleanup:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with HCFSClient(...) as client:
|
||||
# Use client
|
||||
pass
|
||||
|
||||
async with HCFSAsyncClient(...) as client:
|
||||
# Use async client
|
||||
pass
|
||||
|
||||
2. **Configure Timeouts**
|
||||
Set appropriate timeouts for your use case:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client = HCFSClient(
|
||||
base_url="...",
|
||||
api_key="...",
|
||||
timeout=30.0 # 30 second timeout
|
||||
)
|
||||
|
||||
3. **Enable Caching**
|
||||
Use caching for read-heavy workloads:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
cache_config = CacheConfig(
|
||||
enabled=True,
|
||||
max_size=2000,
|
||||
ttl_seconds=3600
|
||||
)
|
||||
|
||||
4. **Handle Errors Gracefully**
|
||||
Always handle potential errors:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
try:
|
||||
result = client.search_contexts(query)
|
||||
except HCFSError as e:
|
||||
logger.error(f"Search failed: {e}")
|
||||
result = []
|
||||
|
||||
5. **Use Batch Operations**
|
||||
For multiple operations, use batch methods:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Better than multiple individual creates
|
||||
result = client.batch_create_contexts(contexts)
|
||||
|
||||
6. **Monitor Performance**
|
||||
Regularly check analytics:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
analytics = client.get_analytics()
|
||||
if analytics.get_error_rate() > 0.05: # 5% error rate
|
||||
logger.warning("High error rate detected")
|
||||
|
||||
Next Steps
|
||||
----------
|
||||
|
||||
- Read the :doc:`clients` documentation for detailed client usage
|
||||
- Explore :doc:`models` for data structure details
|
||||
- Check out :doc:`examples` for real-world usage patterns
|
||||
- See :doc:`utilities` for helper functions and decorators
|
||||
Reference in New Issue
Block a user