# Familiar v1.3.9 - Enterprise LLM Agent Framework

## Overview

Familiar is a production-ready LLM agent framework with enterprise-grade features for reliability, observability, and safety.

## Version 1.4.0 - Phase 3 Complete

This package includes:
- **Phase 1** (Foundation): Token counting, retry policies, PII detection, audit logging
- **Phase 2** (Advanced): Semantic retrieval, LLM-as-Judge, experiments, saga patterns, OpenTelemetry
- **Phase 3** (Production): SQLite persistence, tool registry, CI/CD integration

## Installation

```bash
# Extract the zip
unzip familiar-v1_0_3.zip

# Install dependencies
pip install tiktoken numpy aiosqlite

# Optional for full features
pip install opentelemetry-api opentelemetry-sdk chromadb sentence-transformers
```

## Package Structure

```
familiar/
├── core/
│   ├── __init__.py          # Main exports
│   ├── bus.py                # SkillBus with persistent state
│   ├── context.py            # Context compilation & semantic retrieval
│   ├── evaluation.py         # Evaluation framework & LLM-as-Judge
│   ├── experiments.py        # A/B testing & feature flags
│   ├── guardrails.py         # Safety, PII detection, audit logging
│   ├── observability.py      # OpenTelemetry integration
│   ├── saga.py               # Saga pattern for workflows
│   ├── persistence.py        # SQLite state persistence
│   ├── tool_registry.py      # Tool management & versioning
│   ├── ci_eval.py            # CI/CD evaluation integration
│   ├── enhancements.py       # Core enhancement classes
│   └── integration_patches.py # Integration helpers
├── tests/
│   ├── test_*.py             # Comprehensive test suites
└── examples/
    └── advanced_integration.py
```

## Quick Start

### Persistent State

```python
from familiar.core import SkillBus, SQLiteStateBackend

# Create bus with persistent state
backend = SQLiteStateBackend("app_state.db")
bus = SkillBus(state_backend=backend)

bus.state.set("key", "value")  # Persisted to SQLite
# State survives process restarts
```

### Tool Registry with Safety Levels

```python
from familiar.core import ToolRegistry, SafetyLevel, Guardrails

registry = ToolRegistry()

@registry.tool(safety_level=SafetyLevel.DANGEROUS)
def delete_file(path: str) -> bool:
    """Delete a file."""
    return os.remove(path)

# Guardrails check safety levels
guardrails = Guardrails()
allowed, reason, needs_approval = guardrails.check_tool_call(
    "delete_file", {"path": "/tmp/test"}, tool_registry=registry
)
# needs_approval == True for DANGEROUS tools
```

### CI/CD Evaluation

```python
from familiar.core import create_ci_eval_runner

runner = create_ci_eval_runner(
    suite_path="tests/eval_suite.json",
    min_pass_rate=0.9
)
result = runner.run()
sys.exit(result.exit_code)  # 0=pass, 1=fail
```

```bash
# Generate GitHub Actions workflow
python -m familiar.eval generate --provider github --suite tests/eval.json
```

## Phase 3 Enhancements

### #10: SQLite State Persistence (~1,100 lines)
- Pluggable StateBackend interface
- SQLite with WAL mode for performance
- TTL-based expiration
- Namespace isolation
- Checkpointing for workflow recovery

### #11: Tool Registry (~1,400 lines)
- Schema-based tool registration
- Semantic versioning
- Safety level classification
- Deprecation tracking
- Usage analytics
- OpenAI/Anthropic schema export

### #12: CI/CD Eval Integration (~1,100 lines)
- GitHub Actions workflow generator
- GitLab CI generator
- JUnit XML output
- Markdown reports
- Threshold-based pass/fail
- Environment variable configuration

### #13: Streaming Context Assembly (~460 lines)
- Async streaming context compilation
- Early LLM warm-up capability
- Real-time progress monitoring
- Incremental token counting
- Batched or individual item yielding
- Integration with existing ContextCompiler

### #13: Streaming Context Assembly (~400 lines added to context.py)
- Async streaming of context compilation
- Individual system sections, messages, and tools yielded progressively
- Cumulative token counting during streaming
- Elapsed time tracking
- Faster time-to-first-token for LLM calls
- Integration with original ContextCompiler

### #14: Distributed Bus with Redis (~700 lines)
- Redis pub/sub for cross-process messaging
- Distributed shared state
- Node discovery and coordination
- Remote skill invocation
- Distributed locking
- Automatic heartbeat and health monitoring

## Integration Points

| Module | Integrates With | Parameter |
|--------|-----------------|-----------|
| Persistence | SharedState, SkillBus | `state_backend` |
| Tool Registry | Guardrails | `tool_registry` in check_tool_call |
| CI/CD Eval | Evaluator | Calls run_suite() internally |
| Streaming Context | ContextCompiler | `compile_streaming()` method |
| Distributed Bus | SkillBus | `create_distributed_bus()` |

## Running Tests

```bash
cd familiar
python -m pytest tests/ -v
```

## Documentation

- `ENHANCEMENT_PACKAGE.md` - Phase 1-2 documentation
- `ENTERPRISE_ASSESSMENT.md` - Architecture analysis
- Individual enhancement docs in package

## License

MIT License - See LICENSE file for details.
