contex-python 0.1.0__tar.gz

contex_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Contex Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contex_python-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: contex-python
+Version: 0.1.0
+Summary: Official Python SDK for Contex - Semantic context routing for AI agents
+Author-email: Cahoots <admin@cahoots.cc>
+License: MIT
+Project-URL: Homepage, https://github.com/cahoots-org/contex
+Project-URL: Repository, https://github.com/cahoots-org/contex
+Project-URL: Issues, https://github.com/cahoots-org/contex/issues
+Keywords: ai,agents,context,semantic-search,machine-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Contex Python SDK
+
+Official Python client for [Contex](https://github.com/cahoots-org/contex) - Semantic context routing for AI agents.
+
+## Installation
+
+```bash
+pip install contex-python
+```
+
+## Quick Start
+
+### Async Client (Recommended)
+
+```python
+from contex import ContexAsyncClient
+
+async def main():
+    async with ContexAsyncClient(
+        url="http://localhost:8001",
+        api_key="ck_your_api_key_here"
+    ) as client:
+        # Publish data
+        await client.publish(
+            project_id="my-app",
+            data_key="coding_standards",
+            data={
+                "style": "PEP 8",
+                "max_line_length": 100,
+                "quotes": "double"
+            }
+        )
+        
+        # Register agent
+        response = await client.register_agent(
+            agent_id="code-reviewer",
+            project_id="my-app",
+            data_needs=[
+                "coding standards and style guidelines",
+                "testing requirements and coverage goals"
+            ]
+        )
+        
+        print(f"Matched {len(response.matched_data)} items")
+        for match in response.matched_data:
+            print(f"  {match.data_key}: {match.similarity_score:.2f}")
+        
+        # Query for data
+        results = await client.query(
+            project_id="my-app",
+            query="authentication configuration"
+        )
+        
+        for result in results.results:
+            print(f"{result.data_key}: {result.data}")
+
+import asyncio
+asyncio.run(main())
+```
+
+### Sync Client
+
+```python
+from contex import ContexClient
+
+client = ContexClient(
+    url="http://localhost:8001",
+    api_key="ck_your_api_key_here"
+)
+
+# Publish data
+client.publish(
+    project_id="my-app",
+    data_key="config",
+    data={"env": "prod", "debug": False}
+)
+
+# Register agent
+response = client.register_agent(
+    agent_id="my-agent",
+    project_id="my-app",
+    data_needs=["configuration", "secrets"]
+)
+```
+
+## Features
+
+- ✅ **Async & Sync**: Both async and synchronous interfaces
+- ✅ **Type Hints**: Full type annotations with Pydantic models
+- ✅ **Error Handling**: Comprehensive exception hierarchy
+- ✅ **Retry Logic**: Automatic retries with exponential backoff
+- ✅ **Rate Limiting**: Built-in rate limit handling
+- ✅ **Authentication**: API key authentication support
+
+## API Reference
+
+### Client Initialization
+
+```python
+client = ContexAsyncClient(
+    url="http://localhost:8001",  # Contex server URL
+    api_key="ck_...",              # API key for authentication
+    timeout=30.0,                  # Request timeout in seconds
+    max_retries=3,                 # Maximum number of retries
+)
+```
+
+### Publishing Data
+
+```python
+await client.publish(
+    project_id="my-app",           # Project identifier
+    data_key="unique-key",         # Unique key for this data
+    data={"any": "json"},          # Data payload
+    data_format="json",            # Format: json, yaml, toml, text
+    metadata={"tags": ["prod"]},   # Optional metadata
+)
+```
+
+### Registering Agents
+
+```python
+response = await client.register_agent(
+    agent_id="agent-1",                    # Unique agent ID
+    project_id="my-app",                   # Project ID
+    data_needs=["config", "secrets"],      # Data needs (natural language)
+    notification_method="redis",           # redis or webhook
+    webhook_url="https://...",             # Optional webhook URL
+    webhook_secret="secret",               # Optional webhook secret
+    last_seen_sequence="0",                # Last seen sequence
+)
+```
+
+### Querying Data
+
+```python
+results = await client.query(
+    project_id="my-app",
+    query="authentication settings",
+    max_results=10,
+)
+
+for result in results.results:
+    print(f"{result.data_key}: {result.similarity_score}")
+```
+
+### API Key Management
+
+```python
+# Create API key
+key_response = await client.create_api_key(name="production-key")
+print(f"API Key: {key_response.key}")  # Store this securely!
+
+# List keys
+keys = await client.list_api_keys()
+
+# Revoke key
+await client.revoke_api_key(key_id="key-123")
+```
+
+### Health Checks
+
+```python
+# Comprehensive health
+health = await client.health()
+
+# Readiness check
+ready = await client.ready()
+
+# Rate limit status
+rate_limit = await client.rate_limit_status()
+print(f"Remaining: {rate_limit.remaining}/{rate_limit.limit}")
+```
+
+## Exception Handling
+
+```python
+from contex import (
+    ContexError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NotFoundError,
+    ServerError,
+)
+
+try:
+    await client.publish(...)
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+except NotFoundError:
+    print("Resource not found")
+except ServerError:
+    print("Server error")
+except ContexError as e:
+    print(f"Contex error: {e}")
+```
+
+## Development
+
+### Setup
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+black contex/
+ruff check contex/
+mypy contex/
+```
+
+## Examples
+
+See the [examples](examples/) directory for more usage examples:
+
+- `basic_usage.py` - Basic publish and query
+- `agent_registration.py` - Agent registration and updates
+- `webhook_agent.py` - Webhook-based agent
+- `error_handling.py` - Error handling patterns
+- `batch_operations.py` - Batch publishing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Documentation](https://contex.readthedocs.io)
+- [GitHub](https://github.com/cahoots-org/contex)
+- [PyPI](https://pypi.org/project/contex-python/)
+- [Issues](https://github.com/cahoots-org/contex/issues)

contex_python-0.1.0/README.md

@@ -0,0 +1,245 @@
+# Contex Python SDK
+
+Official Python client for [Contex](https://github.com/cahoots-org/contex) - Semantic context routing for AI agents.
+
+## Installation
+
+```bash
+pip install contex-python
+```
+
+## Quick Start
+
+### Async Client (Recommended)
+
+```python
+from contex import ContexAsyncClient
+
+async def main():
+    async with ContexAsyncClient(
+        url="http://localhost:8001",
+        api_key="ck_your_api_key_here"
+    ) as client:
+        # Publish data
+        await client.publish(
+            project_id="my-app",
+            data_key="coding_standards",
+            data={
+                "style": "PEP 8",
+                "max_line_length": 100,
+                "quotes": "double"
+            }
+        )
+        
+        # Register agent
+        response = await client.register_agent(
+            agent_id="code-reviewer",
+            project_id="my-app",
+            data_needs=[
+                "coding standards and style guidelines",
+                "testing requirements and coverage goals"
+            ]
+        )
+        
+        print(f"Matched {len(response.matched_data)} items")
+        for match in response.matched_data:
+            print(f"  {match.data_key}: {match.similarity_score:.2f}")
+        
+        # Query for data
+        results = await client.query(
+            project_id="my-app",
+            query="authentication configuration"
+        )
+        
+        for result in results.results:
+            print(f"{result.data_key}: {result.data}")
+
+import asyncio
+asyncio.run(main())
+```
+
+### Sync Client
+
+```python
+from contex import ContexClient
+
+client = ContexClient(
+    url="http://localhost:8001",
+    api_key="ck_your_api_key_here"
+)
+
+# Publish data
+client.publish(
+    project_id="my-app",
+    data_key="config",
+    data={"env": "prod", "debug": False}
+)
+
+# Register agent
+response = client.register_agent(
+    agent_id="my-agent",
+    project_id="my-app",
+    data_needs=["configuration", "secrets"]
+)
+```
+
+## Features
+
+- ✅ **Async & Sync**: Both async and synchronous interfaces
+- ✅ **Type Hints**: Full type annotations with Pydantic models
+- ✅ **Error Handling**: Comprehensive exception hierarchy
+- ✅ **Retry Logic**: Automatic retries with exponential backoff
+- ✅ **Rate Limiting**: Built-in rate limit handling
+- ✅ **Authentication**: API key authentication support
+
+## API Reference
+
+### Client Initialization
+
+```python
+client = ContexAsyncClient(
+    url="http://localhost:8001",  # Contex server URL
+    api_key="ck_...",              # API key for authentication
+    timeout=30.0,                  # Request timeout in seconds
+    max_retries=3,                 # Maximum number of retries
+)
+```
+
+### Publishing Data
+
+```python
+await client.publish(
+    project_id="my-app",           # Project identifier
+    data_key="unique-key",         # Unique key for this data
+    data={"any": "json"},          # Data payload
+    data_format="json",            # Format: json, yaml, toml, text
+    metadata={"tags": ["prod"]},   # Optional metadata
+)
+```
+
+### Registering Agents
+
+```python
+response = await client.register_agent(
+    agent_id="agent-1",                    # Unique agent ID
+    project_id="my-app",                   # Project ID
+    data_needs=["config", "secrets"],      # Data needs (natural language)
+    notification_method="redis",           # redis or webhook
+    webhook_url="https://...",             # Optional webhook URL
+    webhook_secret="secret",               # Optional webhook secret
+    last_seen_sequence="0",                # Last seen sequence
+)
+```
+
+### Querying Data
+
+```python
+results = await client.query(
+    project_id="my-app",
+    query="authentication settings",
+    max_results=10,
+)
+
+for result in results.results:
+    print(f"{result.data_key}: {result.similarity_score}")
+```
+
+### API Key Management
+
+```python
+# Create API key
+key_response = await client.create_api_key(name="production-key")
+print(f"API Key: {key_response.key}")  # Store this securely!
+
+# List keys
+keys = await client.list_api_keys()
+
+# Revoke key
+await client.revoke_api_key(key_id="key-123")
+```
+
+### Health Checks
+
+```python
+# Comprehensive health
+health = await client.health()
+
+# Readiness check
+ready = await client.ready()
+
+# Rate limit status
+rate_limit = await client.rate_limit_status()
+print(f"Remaining: {rate_limit.remaining}/{rate_limit.limit}")
+```
+
+## Exception Handling
+
+```python
+from contex import (
+    ContexError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NotFoundError,
+    ServerError,
+)
+
+try:
+    await client.publish(...)
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+except NotFoundError:
+    print("Resource not found")
+except ServerError:
+    print("Server error")
+except ContexError as e:
+    print(f"Contex error: {e}")
+```
+
+## Development
+
+### Setup
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+black contex/
+ruff check contex/
+mypy contex/
+```
+
+## Examples
+
+See the [examples](examples/) directory for more usage examples:
+
+- `basic_usage.py` - Basic publish and query
+- `agent_registration.py` - Agent registration and updates
+- `webhook_agent.py` - Webhook-based agent
+- `error_handling.py` - Error handling patterns
+- `batch_operations.py` - Batch publishing
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Documentation](https://contex.readthedocs.io)
+- [GitHub](https://github.com/cahoots-org/contex)
+- [PyPI](https://pypi.org/project/contex-python/)
+- [Issues](https://github.com/cahoots-org/contex/issues)

contex_python-0.1.0/contex/__init__.py

@@ -0,0 +1,49 @@
+"""
+Contex Python SDK
+~~~~~~~~~~~~~~~~~
+
+Official Python client for Contex - Semantic context routing for AI agents.
+
+Basic usage:
+
+    >>> from contex import ContexClient
+    >>> client = ContexClient(url="http://localhost:8001", api_key="ck_...")
+    >>> await client.publish(project_id="my-app", data_key="config", data={"env": "prod"})
+
+Full documentation: https://github.com/cahoots-org/contex
+"""
+
+__version__ = "0.2.0"
+__author__ = "Contex Team"
+__license__ = "MIT"
+
+from .client import ContexClient, ContexAsyncClient
+from .models import (
+    DataEvent,
+    AgentRegistration,
+    RegistrationResponse,
+    MatchedData,
+)
+from .exceptions import (
+    ContexError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NotFoundError,
+    ServerError,
+)
+
+__all__ = [
+    "ContexClient",
+    "ContexAsyncClient",
+    "DataEvent",
+    "AgentRegistration",
+    "RegistrationResponse",
+    "MatchedData",
+    "ContexError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "ServerError",
+]