Add initial implementation of Brainus AI Python SDK with core features and examples

- Create .gitignore to exclude build outputs, environment variables, and IDE files
- Add README.md with project description, features, installation instructions, and resources
- Implement basic usage example in examples/basic_usage.py
- Define project metadata in pyproject.toml including dependencies and classifiers
- Establish main client functionality in src/brainus_ai/client.py
- Create custom exceptions in src/brainus_ai/exceptions.py
- Define data models in src/brainus_ai/models.py for API interactions
- Add PEP 561 marker file for type information in src/brainus_ai/py.typed

Author: 0xneobyte

.gitignore

@@ -0,0 +1,53 @@
+# Build outputs
+dist/
+build/
+*.egg-info/
+*.egg
+*.whl
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Temporary files
+*.tmp
+*.temp

README.md

@@ -0,0 +1,44 @@
+# Brainus AI Python SDK
+
+Official Python SDK for the Brainus AI API - RAG-powered educational content queries with citations.
+
+[![PyPI version](https://badge.fury.io/py/brainus-ai.svg)](https://badge.fury.io/py/brainus-ai)
+[![Python Support](https://img.shields.io/pypi/pyversions/brainus-ai.svg)](https://pypi.org/project/brainus-ai/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- Async-first - Built with `httpx` for modern async/await patterns
+- Type-safe - Full type hints with Pydantic models
+- Automatic retries - Configurable retry logic for resilience
+- Error handling - Custom exceptions for different error cases
+- Citation support - Get source documents with page numbers
+- Usage tracking - Monitor your API usage and quotas
+
+## Installation
+
+```bash
+pip install brainus-ai
+```
+
+## Documentation
+
+Full documentation, quick start guide, API reference, and examples are available at:
+
+**https://developers.brainus.lk/docs/sdks/python**
+
+## Resources
+
+- [Documentation](https://developers.brainus.lk/docs/sdks/python)
+- [Get API Key](https://developer.brainus.lk/dashboard/keys)
+- [Support](https://github.com/brainus/brainus-ai-python/issues)
+- [Website](https://brainus.lk)
+- [Developer Portal](https://developer.brainus.lk)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+Made with ❤️ by the Brainus team

examples/basic_usage.py

@@ -0,0 +1,72 @@
+"""Basic usage example for the Brainus AI Python SDK."""
+
+import asyncio
+import os
+from brainus_ai import BrainusAI
+
+
+async def main():
+    # Get API key from environment variable
+    api_key = os.getenv("BRAINUS_API_KEY")
+    if not api_key:
+        print("Error: BRAINUS_API_KEY environment variable not set")
+        return
+
+    # Initialize the client
+    async with BrainusAI(api_key=api_key) as client:
+        # Example 1: Query with no filters
+        print("Example 1: Simple query")
+        print("-" * 50)
+        response = await client.query(
+            query="What is Object-Oriented Programming?",
+            # store_id is optional - uses default if not provided
+        )
+        print(f"Answer: {response.answer}\n")
+
+        if response.has_citations:
+            print("Citations:")
+            for citation in response.citations:
+                print(f"  - {citation.document_name} (Pages: {citation.pages})")
+        print()
+
+        # Example 2: Query with filters
+        print("Example 2: Query with filters")
+        print("-" * 50)
+        from brainus_ai import QueryFilters
+        
+        response = await client.query(
+            query="Explain inheritance in programming",
+            store_id="your_store_id",  # Optional
+            model="gemini-2.5-flash",  # Optional
+            filters=QueryFilters(subject="ICT", grade="12"),
+        )
+        print(f"Answer: {response.answer[:200]}...\n")
+
+        # Example 3: Get usage statistics
+        print("Example 3: Usage statistics")
+        print("-" * 50)
+        stats = await client.get_usage()
+        print(f"Total requests: {stats.total_requests}")
+        print(f"Quota used: {stats.quota_percentage}%")
+        if stats.quota_remaining:
+            print(f"Quota remaining: {stats.quota_remaining}")
+        print()
+
+        # Example 4: Get available plans
+        print("Example 4: Available plans")
+        print("-" * 50)
+        plans = await client.get_plans()
+        for plan in plans:
+            print(f"{plan.name}:")
+            print(f"  Rate limit: {plan.rate_limit_per_minute} req/min")
+            print(f"  Monthly quota: {plan.monthly_quota or 'Unlimited'}")
+            print(f"  Price: LKR {plan.price_lkr or 0}/month")
+            print(f"  Allowed models: {', '.join(plan.allowed_models)}")
+        print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+

pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "brainus-ai"
+version = "0.1.1"
+description = "Official Python SDK for Brainus AI - RAG-powered educational content API"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Brainus Team", email = "dev@brainus.lk"}
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
+]
+keywords = ["brainus", "ai", "rag", "education", "api", "sdk"]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.9.0",
+    "typing-extensions>=4.12.0; python_version<'3.13'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-httpx>=0.30.0",
+    "mypy>=1.11.0",
+    "ruff>=0.6.0",
+    "build>=1.2.0",
+    "twine>=5.1.0",
+]
+
+[project.urls]
+Homepage = "https://developer.brainus.lk"
+Documentation = "https://developer.brainus.lk/docs"
+Repository = "https://github.com/brainus/brainus-ai-python"
+Issues = "https://github.com/brainus/brainus-ai-python/issues"
+Changelog = "https://github.com/brainus/brainus-ai-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/brainus_ai"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "TCH"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+
+

src/brainus_ai/__init__.py

@@ -0,0 +1,36 @@
+"""
+Brainus AI Python SDK
+
+Official Python client for the Brainus AI API - RAG-powered educational content.
+"""
+
+from .client import BrainusAI
+from .exceptions import (
+    BrainusError,
+    AuthenticationError,
+    RateLimitError,
+    QuotaExceededError,
+    APIError,
+)
+from .models import QueryRequest, QueryResponse, Citation, UsageStats, Plan, QueryFilters, PlanInfo
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BrainusAI",
+    "BrainusError",
+    "AuthenticationError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "APIError",
+    "QueryRequest",
+    "QueryResponse",
+    "Citation",
+    "UsageStats",
+    "Plan",
+    "QueryFilters",
+    "PlanInfo",
+]
+
+
+