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`