chore: setup repository infrastructure

[Kamilbenkirane]

Overview

Initial setup of repository infrastructure for Celeste Python SDK. This establishes the foundation for code quality, testing, and development workflows.

Files Added

Infrastructure Files

• .gitignore - Git ignore patterns for Python projects, excluding build artifacts, cache files, and environment files
• .pre-commit-config.yaml - Pre-commit hooks configuration for automated code quality checks
• Makefile - Development workflow commands for common tasks
• README.md - Project documentation with quick start guide and examples
• logo.svg - Celeste AI logo
• pyproject.toml - Project configuration including:
  • Package metadata and dependencies
  • Tool configurations (Ruff, MyPy, Bandit, Pytest, Coverage)
  • Build system configuration

Code Quality Fixes

• Applied pre-commit hook fixes across all Python files (trailing whitespace, end-of-file fixes)
• Ensured consistent formatting and code style compliance

Features

• Code Quality: Automated linting, formatting, and type checking via Ruff and MyPy
• Security: Security scanning with Bandit
• Testing: Test coverage reporting with 90% threshold requirement
• Development Workflow: Makefile provides convenient commands for common tasks
• Pre-commit Hooks: Automated checks prevent common issues before commit

Configuration Highlights

• Pre-commit hooks prevent direct commits to protected branches
• DRY principle: tool configurations centralized in pyproject.toml
• Strict type checking enabled for production code
• Comprehensive test coverage requirements

Next Steps

After merging, developers should run:

make sync          # Install dependencies
pre-commit install # Install git hooks

[claude]

Pull Request Review: Repository Infrastructure Setup

Overview

This PR establishes a solid foundation for the Celeste Python SDK with comprehensive infrastructure for code quality, testing, and development workflows. The implementation demonstrates strong engineering practices and attention to detail.

---

✅ Strengths

1. Excellent Code Architecture

• Strong type safety: Uses Python 3.12+ features (generics, union types) and strict mypy configuration
• Plugin architecture: Entry point system allows modular capability additions via pyproject.toml
• Separation of concerns: Clean abstractions (Client, Model, Parameters, Constraints)
• Registry pattern: Well-implemented for models, clients, and HTTP connections

2. Security Best Practices

• ✅ Uses SecretStr from Pydantic for API keys (prevents logging)
• ✅ Bandit security scanning configured
• ✅ Credentials loaded from environment variables with proper isolation
• ✅ HTTP client uses # nosec B113 with justification (line 42 in http.py)

3. Performance Considerations

• ✅ HTTP connection pooling per provider/capability
• ✅ Persistent connections with configurable limits
• ✅ Async/await throughout for I/O efficiency
• ✅ Streaming support with proper resource cleanup

4. Development Workflow

• ✅ Comprehensive Makefile with clear targets
• ✅ Pre-commit hooks prevent common issues
• ✅ 90% coverage requirement enforced
• ✅ Prevents commits to protected branches

---

⚠️ Issues & Recommendations

CRITICAL: Missing Tests

Severity: High
Location: Entire codebase

The PR introduces ~1700 lines of production code but includes zero test files. This violates the stated 90% coverage requirement.

Required Actions:

1. Add unit tests for all modules before merging
2. Test coverage should include:
   • Constraint validation edge cases (Range step validation, Pattern matching)
   • Model/client registration conflicts
   • Credential loading and fallback behavior
   • HTTP connection pooling and cleanup
   • Error handling paths
   • Stream exhaustion and cleanup

Example missing test cases:

# constraints.py line 52-63: Complex step validation logic
# Should test: exact step matches, off-by-epsilon, close-but-invalid values

# credentials.py line 106: Type ignore comment
credentials = Credentials()  # type: ignore[call-arg]
# This suppresses errors - tests should verify proper initialization

# streaming.py line 66-67: Runtime error on empty chunks
if not self._chunks:
    msg = "Stream completed but no chunks were produced"
    raise RuntimeError(msg)

---

Code Quality Issues

1. Type Safety Concerns

Location: src/celeste/credentials.py:106

credentials = Credentials()  # type: ignore[call-arg]

Issue: Type checking disabled without clear justification
Recommendation: Document why this is necessary or refactor to avoid type ignore

---

Location: src/celeste/parameters.py:17

name: StrEnum
"""Parameter name matching capability TypedDict key. Must be StrEnum for type safety."""

Issue: Uses bare attribute without initialization (not compatible with @abstractmethod)
Recommendation: Use ABC or define as abstract property:

@property
@abstractmethod
def name(self) -> StrEnum:
    """Parameter name matching capability TypedDict key."""
    ...

---

2. Error Handling Issues

Location: src/celeste/http.py:132-135

try:
    yield json.loads(sse.data)
except json.JSONDecodeError:
    continue  # Skip non-JSON control messages (provider-agnostic)

Issue: Silently swallows all JSON decode errors, including malformed data
Recommendation: Add logging for debugging:

except json.JSONDecodeError:
    logger.debug(f"Skipping non-JSON SSE event: {sse.data[:100]}")
    continue

---

Location: src/celeste/__init__.py:93-101

except (ImportError, AttributeError, ValueError) as e:
    import sys
    print(f"Warning: Failed to load package '{ep.name}': {e}", file=sys.stderr)
    logger.debug(f"Full traceback for package '{ep.name}'", exc_info=True)

Issue: Imports sys inside except block (anti-pattern)
Recommendation: Move import to module level

---

3. Resource Management Concerns

Location: src/celeste/http.py:174-187

async def close_all_http_clients() -> None:
    """Close all HTTP clients gracefully and clear registry."""
    import logging  # ⚠️ Imported inside function
    
    logger = logging.getLogger(__name__)
    
    for key, client in list(_http_clients.items()):
        try:
            await client.aclose()
        except Exception as e:
            logger.warning(f"Failed to close HTTP client for {key}: {e}")
    
    _http_clients.clear()

Issues:

• Import inside function (should be module-level)
• No mechanism to call this on application shutdown
• Users may leak connections without documentation

Recommendation:

1. Add to __all__ exports and document usage
2. Consider atexit registration or context manager pattern
3. Add documentation to README about proper cleanup

---

4. Documentation Gaps

Location: README.md

# Missing critical information:
- No mention of connection cleanup (close_all_http_clients)
- No error handling examples
- No async context manager usage examples

Recommendation: Add sections:

## Resource Management
Always close HTTP clients when done:
```python
from celeste import close_all_http_clients

# At application shutdown
await close_all_http_clients()

Error Handling

Handle credential and network errors:

try:
    client = create_client(...)
    response = await client.generate(...)
except ValueError as e:
    # Handle missing credentials or invalid config
except httpx.HTTPError as e:
    # Handle network/API errors

---

#### 5. **Potential Bugs**

**Location:** `src/celeste/constraints.py:52-63`
```python
if self.step is not None:
    remainder = (value - self.min) % self.step
    epsilon = 1e-9
    if remainder > epsilon and abs(remainder - self.step) > epsilon:
        # ...error...

Issue: Floating-point arithmetic may fail for very small or very large steps
Recommendation: Use math.isclose() or allow configurable epsilon:

import math
# ...
if not math.isclose(remainder, 0, abs_tol=epsilon) and \
   not math.isclose(remainder, self.step, abs_tol=epsilon):

---

Location: src/celeste/client.py:84-98

def stream(self, *args: Any, **parameters: Unpack[Parameters]) -> Stream[Out]:
    """Stream content - signature varies by capability."""
    msg = f"{self.capability.value} or {self.provider.value} does not support streaming"
    raise NotImplementedError(msg)

Issue: Error message says "or" but should be "and" (both are specified)
Recommendation:

msg = f"Streaming not supported for {self.capability.value} with provider {self.provider.value}"

---

Configuration Issues

1. Pre-commit Hook Conflicts

Location: .pre-commit-config.yaml:61

- id: pytest
  name: "🧪 Run tests with coverage"
  entry: uv run pytest tests/ --cov=celeste --cov-report=term-missing
  language: system
  types: [python]
  pass_filenames: false
  always_run: true
  stages: [pre-push]  # Run on push, not commit (keeps commits fast)

Issue: Comment says "pre-push" but always_run: true may cause issues
Recommendation: Verify this works as intended with actual tests

---

2. Overly Strict Mypy Configuration

Location: pyproject.toml:124

disallow_any_unimported = true

Issue: This will flag third-party libraries without stubs, causing friction
Recommendation: Consider relaxing to disallow_any_explicit = true instead

---

Performance Considerations

1. HTTP Client Pooling Granularity

Location: src/celeste/http.py:156-171

def get_http_client(provider: Provider, capability: Capability) -> HTTPClient:
    key = (provider, capability)
    if key not in _http_clients:
        _http_clients[key] = HTTPClient()
    return _http_clients[key]

Observation: Creates separate pools per provider+capability combination
Question: Is this necessary? Most providers use the same base URL for all capabilities.
Recommendation: Consider pooling by provider only unless there's a documented reason for capability separation

---

2. Entry Point Loading on Import

Location: src/celeste/__init__.py:105

# Load from entry points on import
_load_from_entry_points()

Issue: Module import triggers I/O and potential errors
Impact: Import-time side effects slow down CLI tools and testing
Recommendation: Consider lazy loading or explicit initialization:

def initialize() -> None:
    """Explicitly initialize plugins. Call once at application startup."""
    _load_from_entry_points()

---

Minor Issues

1. Empty src/__init__.py - Consider removing if not needed for namespace packages
2. src/celeste/py.typed - File exists but is empty (correct for PEP 561)
3. Missing CONTRIBUTING.md - README references it but file not in PR
4. Missing LICENSE - Referenced in README but not included

---

🧪 Test Coverage Requirements

Before merging, add tests for:

Critical Paths

• Model registration and lookup
• Client creation and initialization
• Credential resolution (env vars, overrides)
• HTTP client pooling and reuse
• Parameter validation (all constraint types)

Error Handling

• Missing credentials
• Unsupported provider/capability combinations
• Invalid parameter values
• Network failures
• Stream errors and cleanup

Edge Cases

• Duplicate model registration
• Empty model list with auto-selection
• Range constraint with step validation
• Stream exhaustion without chunks
• Concurrent access to shared HTTP clients

---

📊 Summary

Category	Rating	Notes
Architecture	⭐⭐⭐⭐⭐	Excellent design patterns
Type Safety	⭐⭐⭐⭐	Strong but has type ignores
Security	⭐⭐⭐⭐⭐	SecretStr, Bandit, good practices
Performance	⭐⭐⭐⭐	Connection pooling, async
Test Coverage	⭐	CRITICAL: Zero tests
Documentation	⭐⭐⭐	Good README, missing details

---

🎯 Recommendations for Merge

Must Fix Before Merge

1. Add comprehensive test suite (aim for 90% coverage as configured)
2. Fix type ignore in credentials.py or document justification
3. Add missing files (LICENSE, CONTRIBUTING.md)

Should Fix Before Merge

4. Fix error message in Client.stream()
5. Move imports to module level
6. Add resource cleanup documentation

Consider for Follow-up

7. Lazy-load entry points
8. Review HTTP client pooling granularity
9. Add error handling examples to README
10. Consider relaxing disallow_any_unimported in mypy config

---

🔒 Security Review: PASSED ✅

No security vulnerabilities identified. Good use of:

• SecretStr for credentials
• Bandit scanning
• Environment variable isolation
• Proper exception handling

---

Overall Assessment: Strong foundation with excellent architecture, but cannot merge without tests. The code quality is high, but the complete absence of tests is a significant risk. Once tests are added and the critical issues are addressed, this will be an excellent base for the SDK.

Great work on the architecture and tooling setup! 🎉

[claude]

Pull Request Review: Repository Infrastructure Setup

Overview

This PR establishes a solid foundation for the Celeste Python SDK with comprehensive repository infrastructure. The implementation demonstrates good architecture decisions and follows Python best practices.

✅ Strengths

Architecture & Design

• Excellent abstraction layer: The use of Client, Model, ParameterMapper, and registry patterns creates a clean, extensible architecture
• Type safety: Strong use of Pydantic models, SecretStr for credentials, and type hints throughout
• Plugin architecture: Entry point system for packages (celeste.packages) enables modular extension
• Connection pooling: Shared HTTP client instances per provider/capability combination is efficient
• Generic programming: Good use of Python 3.12+ generics (Client[In: Input, Out: Output])

Code Quality

• Comprehensive tooling: Ruff, MyPy, Bandit, pytest with coverage threshold (90%)
• Pre-commit hooks: Well-configured with appropriate checks
• Documentation: Clear docstrings and README with good examples
• DRY principle: Centralized configuration in pyproject.toml

Security

• Credentials management: Proper use of SecretStr and Field(exclude=True) prevents leakage
• Bandit integration: Security scanning is automated
• HTTP client: Uses httpx with proper async patterns
• nosec B113: Appropriately applied to httpx.AsyncClient (async client doesn't need verify parameter)

⚠️ Issues & Recommendations

Critical Issues

1. Missing Tests (Critical)

File: None exist
Issue: No tests directory or test files found, yet pyproject.toml requires 90% coverage and pre-commit runs tests

Impact: Pre-commit hooks will fail, blocking all commits

Recommendation:

# Create tests/ directory with at least smoke tests
tests/
  __init__.py
  test_client.py
  test_models.py
  test_credentials.py
  test_constraints.py

Consider starting with basic unit tests for:

• Model registration and retrieval
• Constraint validation (Range, Choice, Pattern, etc.)
• Credentials loading from environment
• HTTP client initialization

2. No Actual Provider Implementations

File: src/celeste/__init__.py:90-91
Issue: Entry point loading is implemented but no actual providers exist

def _load_from_entry_points() -> None:
    """Load models and clients from installed packages via entry points."""
    entry_points = importlib.metadata.entry_points(group="celeste.packages")
    
    for ep in entry_points:
        register_func = ep.load()
        register_func()  # Will fail if no packages registered

Recommendation: Add example provider or mark as future work in README

3. HTTP Client Resource Leak Risk

File: src/celeste/http.py:156-171
Issue: HTTP clients are cached but never closed automatically

_http_clients: dict[tuple[Provider, Capability], HTTPClient] = {}

def get_http_client(provider: Provider, capability: Capability) -> HTTPClient:
    key = (provider, capability)
    if key not in _http_clients:
        _http_clients[key] = HTTPClient()
    return _http_clients[key]

Impact: Long-running applications may accumulate unclosed connections

Recommendation:

• Document that users should call close_all_http_clients() at shutdown
• Consider implementing atexit handler for cleanup
• Add example in README showing proper cleanup

Medium Priority Issues

4. Range Constraint Float Comparison

File: src/celeste/constraints.py:52-63
Issue: Epsilon-based comparison may be insufficient for all float ranges

epsilon = 1e-9
if remainder > epsilon and abs(remainder - self.step) > epsilon:

Recommendation: Use math.isclose() with relative tolerance:

import math
if not math.isclose(remainder, 0, abs_tol=epsilon) and \
   not math.isclose(remainder, self.step, abs_tol=epsilon):

5. Stream Error Handling

File: src/celeste/streaming.py:70-72
Issue: Generic exception catch without logging

except Exception:
    await self.aclose()
    raise

Recommendation: Add logging for debugging:

except Exception as e:
    logger.exception("Stream error during chunk parsing")
    await self.aclose()
    raise

6. Credentials Case Sensitivity

File: src/celeste/credentials.py:42-46
Issue: case_sensitive=False may cause issues on case-sensitive systems

model_config = {
    "env_file": find_dotenv(),
    "case_sensitive": False,  # May match unwanted vars
}

Recommendation: Use case_sensitive=True and document exact env var names

7. Missing Type Annotations

File: Multiple locations
Issue: Some Any types could be more specific

Examples:

• src/celeste/streaming.py:87: exc_tb: Any could be TracebackType | None
• src/celeste/io.py:31: metadata: dict[str, Any] - consider defining MetadataDict type alias

Low Priority / Style

8. Empty Input/FinishReason/Usage Classes

File: src/celeste/io.py:8-23

class Input(BaseModel):
    """Base class for capability-specific input types."""
    pass  # Just inherits from BaseModel

Recommendation: These are fine as marker classes, but consider adding model_config for future consistency

9. Makefile Help Command Spacing

File: Makefile:7-12
Recommendation: Consider adding blank lines between command groups for readability

10. README Provider Favicons

File: README.md:68-82
Issue: Using Google favicon service may fail for some providers

Recommendation: Either:

• Host favicons locally
• Add error handling documentation
• Use GitHub shields.io badges instead

🔒 Security Review

Positive Security Practices

✅ SecretStr for all credentials
✅ Bandit security scanning
✅ No hardcoded secrets
✅ Field(exclude=True) on sensitive fields
✅ Pre-commit hook prevents debug statements

Security Recommendations

11. Add Security Policy

Create SECURITY.md:

# Security Policy

## Supported Versions
Currently supporting version 0.0.2

## Reporting a Vulnerability
Please report security vulnerabilities to security@withceleste.ai

12. Add Dependabot

Create .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"

📊 Test Coverage Assessment

Current State: No tests exist

Required Tests (to achieve 90% coverage):

1. Unit Tests (~60-70% coverage)

   • test_constraints.py: All constraint types with edge cases
   • test_models.py: Registration, retrieval, listing
   • test_credentials.py: Loading, validation, override
   • test_parameters.py: Mapper validation
   • test_client.py: Registry, base client methods

2. Integration Tests (~20-25% coverage)

   • HTTP client connection pooling
   • Stream lifecycle (iteration, cleanup)
   • End-to-end client creation

3. Mock Tests (remaining coverage)

   • External API calls
   • Entry point loading

🎯 Recommendations Summary

Before Merging (Blockers)

1. ❗ Add minimal test suite to satisfy pre-commit hooks
2. ❗ Document HTTP client cleanup in README
3. ❗ Either remove or mock entry point loading in tests

After Merging (High Priority)

4. Add comprehensive test coverage
5. Implement example provider
6. Fix float comparison in Range constraint
7. Add security policy and dependabot

Future Improvements

8. Consider atexit handler for HTTP cleanup
9. Add logging throughout
10. Create more specific type aliases

📝 Additional Notes

Positive Development Experience

• Makefile is excellent: make ci provides full local testing
• Pre-commit config is thorough: Will catch most issues
• Type checking is strict: Good for library code
• README examples are clear: Easy to understand API

Package Structure

The workspace setup with packages/* is well-designed for future modularity. Consider documenting the pattern for contributing new providers.

Conclusion

This is a well-architected foundation for a multi-modal AI SDK. The main blocker is the missing test suite - once that's added, this will be ready to merge. The codebase demonstrates good Python practices, proper security handling, and a clean abstraction layer that should scale well.

Recommendation: Address the critical test issue, then merge and iterate on the other improvements.

---

Review generated with attention to Python best practices, security, and SDK design patterns

[claude]

PR Review: Repository Infrastructure Setup

Overview

This PR establishes a solid foundation for the Celeste Python SDK with comprehensive infrastructure and well-architected core modules. The code quality is high, with strong type safety, proper documentation, and good engineering practices.

✅ Strengths

Code Quality & Architecture

1. Excellent Type Safety: Extensive use of Python 3.12+ generics, type hints, and strict mypy configuration
2. Clean Architecture: Clear separation of concerns with modular design (client, credentials, models, parameters, constraints)
3. Registry Pattern: Well-implemented registry patterns for models, clients, and HTTP clients with proper encapsulation
4. Pydantic Integration: Excellent use of Pydantic for validation, settings management, and SecretStr for credentials
5. Async-First Design: Proper async/await patterns with AsyncIterator and async context managers

Infrastructure

1. Comprehensive Tooling: Well-configured pre-commit hooks, Ruff, mypy, Bandit, pytest with coverage
2. DRY Configuration: All tool configs centralized in pyproject.toml - excellent practice
3. Developer Experience: Clear Makefile with helpful commands and good documentation
4. Security Focus: Bandit integration, SecretStr usage, proper credential handling

Documentation

1. Clear Docstrings: Comprehensive docstrings with Args, Returns, Raises sections
2. Good README: Clear examples and well-structured documentation
3. Type Hints: Functions are fully typed, making IDE autocomplete excellent

🔍 Issues & Recommendations

Critical Issues

1. Missing Tests ⚠️ HIGH PRIORITY

Location: Repository-wide
Issue: No test files exist despite pytest configuration requiring 90% coverage. The pre-commit hooks will fail on commit/push since pytest is configured to run.

Recommendation: Add basic test structure before merge, OR adjust pre-commit config to skip tests until implementation packages are added, OR lower coverage threshold temporarily.

2. Entry Point Loading May Fail Silently

Location: src/celeste/init.py:86-90
Issue: If a package register_func() raises an exception, it will crash the entire import.
Recommendation: Add try-except with logging for graceful degradation.

Security Concerns

3. HTTP Client Missing Timeout Documentation

Location: src/celeste/http.py:106-138
Severity: Low-Medium
Recommendation: Document timeout behavior for streaming connections.

4. Bandit Scanning Limited Scope

Location: .pre-commit-config.yaml:49
Recommendation: Consider scanning broader scope as project grows.

5. HTTPClient nosec Comment

Location: src/celeste/http.py:45
Recommendation: Expand comment to explain timeout is handled per-request.

Code Quality & Best Practices

6. Module-Level Singleton Credentials

Location: src/celeste/credentials.py:106
Severity: Low
Issue: Credentials loaded at import time, making testing harder.
Recommendation: Consider function-based approach or document immutability.

7. HTTP Client Registry Never Closes Automatically

Location: src/celeste/http.py:156-191
Recommendation: Add documentation about cleanup requirements and consider atexit.register for automatic cleanup.

8. Error Messages Could Include More Context

Location: src/celeste/credentials.py:69-70
Recommendation: Include expected environment variable name in error messages.

9. Constraint Validation Doesn't Check for NaN/Inf

Location: src/celeste/constraints.py:43-68
Recommendation: Add math.isfinite() check.

10. Stream Class Missing Documentation

Location: src/celeste/streaming.py:11-114
Recommendation: Add comprehensive docstring with usage examples.

Minor Issues

11. README logo path only renders on GitHub, not PyPI
12. Pre-commit config comment could be clearer
13. Makefile clean command could be more robust

🎯 Performance Considerations

Positive

1. Connection Pooling: Excellent use of httpx connection pooling
2. Async Throughout: Proper async patterns without blocking calls
3. Lazy Client Creation: HTTP clients created on-demand

Potential Improvements

1. Consider caching model lookups if list_models() becomes hot path
2. Parameter mapper list could be cached

📋 Test Coverage Recommendations

Priority tests to add:

1. Constraints validation
2. Model registry operations
3. Credentials loading
4. HTTP client lifecycle
5. Stream behavior
6. Parameter mapping

🎉 Summary

Rating: ⭐⭐⭐⭐ (4/5 stars)

This is excellent infrastructure work with strong engineering practices. The main blocking issue is missing tests that will cause pre-commit hooks to fail. Once tests are added or pre-commit config is adjusted, this is ready to merge.

Strengths: Strong architecture, type safety, excellent tooling and developer experience
Gap: Missing test coverage
Minor issues: Non-blocking and can be addressed in follow-ups

Recommendation: Approve with expectation that test infrastructure is added before actual usage, or adjust pre-commit hooks for this infrastructure-only PR.

---

Generated with Claude Code

[claude]

Pull Request Review: Repository Infrastructure Setup

Overview

This PR establishes a solid foundation for the Celeste Python SDK with comprehensive infrastructure for code quality, testing, and development workflows. The code demonstrates strong architectural design with type safety, abstraction, and extensibility as core principles.

---

Strengths

Architecture & Design

• Excellent separation of concerns: Clear module boundaries with well-defined responsibilities
• Type safety throughout: Strong use of generics, type hints, and Pydantic models. The Client[In: Input, Out: Output] generic design is particularly well-crafted
• Extensible plugin system: Entry points mechanism allows for modular capability additions without core changes
• Abstract base classes: Proper use of ABC for Client, Constraint, ParameterMapper, and Stream ensures consistent implementations

Code Quality

• Comprehensive docstrings: All public APIs have clear, informative docstrings with Args/Returns/Raises sections
• DRY principle: Configuration centralized in pyproject.toml, avoiding scattered tool configs
• Strict linting/typing: Ruff and MyPy configured with strict rules
• Modern Python features: Excellent use of Python 3.12+ features (PEP 695 generics, StrEnum)

Infrastructure

• Pre-commit hooks: Comprehensive suite including trailing whitespace, YAML/TOML validation, and branch protection
• Makefile workflow: Clean, intuitive commands for common tasks with a full ci target that mirrors expected CI/CD pipeline
• Security scanning: Bandit integration with appropriate test file exemptions

---

Issues & Concerns

Critical - Test Coverage

Priority: HIGH

The PR sets fail_under = 90 for test coverage but includes zero test files. This creates an immediate blocker: make test and make ci will fail, pre-commit push hooks will fail, coverage requirement cannot be met without tests.

Impact: Without tests, developers cannot commit/push changes, breaking the development workflow entirely.

---

Security Concerns

1. Insecure HTTP Client Configuration - src/celeste/http.py:45 - nosec B113 suppresses Bandit warning about SSL verification. Recommendation: Be explicit about SSL verification requirements.

2. Silent JSON Decode Failures - src/celeste/http.py:136-138 - Silently swallowing JSON decode errors could hide malformed responses. Recommendation: Add debug logging for skipped SSE events.

3. Credential Exposure Risk - src/celeste/credentials.py:72 - If SecretStr is accidentally logged in error messages, credentials could leak. Recommendation: Add explicit warning in docstring about secret handling.

---

Potential Bugs

4. Race Condition in HTTP Client Singleton - src/celeste/http.py:159-174 - Multiple concurrent calls to get_http_client() could create duplicate HTTPClient instances. Recommendation: Use asyncio.Lock or document synchronization requirements.

5. Missing Validation in Range Constraint - src/celeste/constraints.py:43-68 - No validation that min <= max during Range construction. Invalid ranges could cause confusing errors. Recommendation: Add @model_validator to check min <= max and step > 0.

6. Stream Cleanup Edge Case - src/celeste/streaming.py:53-77 - If _parse_output() raises an exception, aclose() is called in the except block, then called again in the success path. While protected by if self._closed, this is inefficient. Recommendation: Restructure to only call aclose() once per code path.

---

Performance Considerations

7. HTTP Connection Pooling Limits - src/celeste/http.py:15-16 - MAX_CONNECTIONS = 20 may bottleneck high-throughput applications making concurrent requests to multiple providers. Recommendation: Consider making these configurable via environment variables.

8. Model Registry Linear Search - src/celeste/models.py:62-83 - O(n) filtering on every call. With hundreds of models across providers, this could become noticeable. Recommendation: Add indexed lookups for common queries (future PR).

---

Documentation Gaps

9. README Examples Don't Match Code Structure - README examples reference generate() and capabilities like IMAGE_GENERATION but no implementations are included. Users following the README will hit NotImplementedError immediately. Recommendation: Add prominent note that capability implementations will be added in separate packages.

---

Security Summary

Severity	Issue	Location	Action Required
Medium	Insecure HTTP client config	http.py:45	Make SSL explicit
Low	Silent JSON decode failures	http.py:136	Add debug logging
Low	Credential exposure risk	credentials.py:72	Add docstring warning

---

Checklist for Merge

Must fix before merge:

• Add test files (even minimal smoke tests) to satisfy coverage requirement
• Fix HTTP client SSL verification (remove nosec or document reasoning)
• Add validation to Range constraint (min <= max, step > 0)
• Update README with note about missing capability implementations

Should fix before merge:

• Add logging for JSON decode failures in SSE streaming
• Document HTTP client singleton thread-safety expectations
• Fix stream cleanup double-call in anext

Nice to have (future PRs):

• Make HTTP connection limits configurable
• Add indexed lookups for model registry
• Add credential exposure warnings in docstrings

---

Final Verdict

Status: Approve with required changes

This is an excellent foundation for the Celeste SDK with strong architectural decisions and impressive code quality. The type-safe, extensible design will serve the project well as capabilities are added.

However, the missing tests are a blocker - the PR cannot be merged as-is because:

1. make test will fail (0% coverage vs. 90% requirement)
2. Pre-commit push hooks will fail
3. Developers cannot contribute without breaking their workflow

Once tests are added and the security concerns addressed, this PR will be in great shape to merge.

Estimated effort to fix blockers: 2-3 hours (add smoke tests, fix security issues, update README)

Great work overall! The attention to type safety and extensibility is particularly impressive.