llmrivotril 0.1.0__tar.gz

llmrivotril-0.1.0/.github/constraints-ci.txt

@@ -0,0 +1,10 @@
+# Reproducible versions for the CI toolchain.
+# Runtime/provider dependencies remain version ranges in pyproject.toml so
+# downstream applications can resolve them with their own dependency set.
+build==1.6.1
+httpx==0.28.1
+mypy==2.3.1
+pytest==9.1.1
+pytest-asyncio==1.4.0
+ruff==0.16.8
+twine==7.0.0

llmrivotril-0.1.0/.github/constraints-runtime.txt

@@ -0,0 +1,25 @@
+# Runtime/provider versions validated together in the Python 3.13 integration
+# venv. Use this file as a reproducible baseline; downstream applications may
+# maintain a narrower set for the providers they actually enable.
+anthropic==1.9.0
+boto3==1.43.105
+botocore==1.43.105
+cohere==7.2.0
+crewai==1.15.23
+fastapi==0.141.1
+google-adk==2.10.0
+google-genai==2.25.0
+httpx==0.28.1
+instructor==1.15.4
+langchain-core==1.6.6
+openai==2.54.0
+pydantic==2.12.5
+qdrant-client==1.19.1
+scikit-learn==1.9.1
+scipy==1.18.1
+s3transfer==0.19.2
+sentence-transformers==6.1.0
+tiktoken==0.14.0
+torch==2.14.0
+transformers==5.17.0
+uvicorn==0.54.0

llmrivotril-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c .github/constraints-ci.txt -e ".[ci]"
+
+      - name: Lint with ruff
+        run: ruff check src tests examples scripts
+
+      - name: Check formatting with ruff
+        run: ruff format --check src tests examples scripts
+
+      - name: Type check with mypy
+        run: mypy src
+
+      - name: Test with pytest
+        run: pytest -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c .github/constraints-ci.txt -e ".[ci]"
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: twine check dist/*
+
+  extras:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install with all extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c .github/constraints-ci.txt -e ".[dev]"
+
+      - name: Run tests with extras installed
+        run: pytest -v

llmrivotril-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  publish:
+    name: Build and publish distributions
+    runs-on: ubuntu-latest
+    # Configure this environment's protection rules (required reviewers,
+    # wait timer) in Settings -> Environments to gate the actual upload step
+    # behind manual approval -- switching from Trusted Publishing to a
+    # static API token removed OIDC's per-run, unexfiltratable credential;
+    # an approval gate is the mitigation for that trade-off.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/llmrivotril
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out the release tag
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -c .github/constraints-ci.txt build twine
+          python -m build
+          twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload --skip-existing dist/*

llmrivotril-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Environment variables
+.env
+.env.local
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

llmrivotril-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-python-dateutil]
+        args: [src]

llmrivotril-0.1.0/CHANGELOG.md

@@ -0,0 +1,327 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-29
+
+### Added
+
+- First release candidate for PyPI distribution.
+- Framework-integration adapters for CrewAI (`BaseLLM`), AG2/pyautogen
+  (`ModelClient` protocol, no extra dependency), LangChain/LangGraph
+  (`BaseChatModel`), and Google ADK (`BaseLlm`) under
+  `llmrivotril.integrations`. Each is optional (`llmrivotril[crewai]`,
+  `llmrivotril[langchain]`, `llmrivotril[adk]`, or `llmrivotril[integrations]`
+  for all three) and documented in `docs/integrations.md`, including
+  multi-agent/crew setup notes.
+- Three independent, opt-in token-saving controls, all off by default and
+  documented in `docs/reliability.md`:
+  - `SemanticCache` (`llmrivotril.semantic_cache`) -- wraps any `BaseCache`
+    backend with an embedding-similarity lookup, so paraphrased repeat
+    prompts hit the cache too, not just byte-identical ones. Requires
+    `llmrivotril[semantic]`.
+  - `MemoryStore(max_tokens=..., count_tokens=...)` -- trims the oldest
+    memory turns by actual token count, layered on top of the existing
+    turn-count `retention_window` cap. `RivotrilAgent(memory_max_tokens=...)`
+    wires this in automatically for its default memory store.
+  - `MemoryStore(summarize=..., summarize_trigger_turns=...)` -- compacts
+    turns that would otherwise be dropped into a short summary instead.
+    `RivotrilAgent(memory_summarize=True, memory_summarize_trigger_turns=...)`
+    wires in a summarizer backed by the agent's own provider.
+  - `BaseCache.get`/`set` gained an optional `prompt=` parameter (ignored by
+    the existing exact-match backends) so a fuzzy-matching cache can see the
+    raw prompt text; this is a backward-compatible addition, not a breaking
+    change to the interface.
+- Brazilian Portuguese translations (`*.pt-BR.md`) of the README and every
+  public doc, each cross-linked with its English original.
+- RAG context injection, deterministic vector-store identifiers, protected
+  memory persistence, cache namespacing, and expanded telemetry.
+- Explicit grounding failure policies and provider-specific retry handling.
+- Gemini adapter migration to the `google-genai` SDK.
+- `RAGPipeline.retrieve()`/`aretrieve()` for accessing ranked documents with
+  IDs and metadata before formatting context for an LLM.
+- Public top-level exports for `BaseLoader`, `BaseChunker` and `BaseRetriever`
+  so custom RAG components do not depend on internal module paths.
+- Async RAG methods now execute synchronous loading, chunking and retrieval in
+  a short-lived worker without blocking the event loop.
+- RAG queries support exact metadata filters, source labels and maximum context
+  size limits.
+- PostgreSQL, Qdrant and Pinecone use native metadata filters when available;
+  Weaviate now supports native filters for explicitly configured flattened
+  metadata fields and keeps a client-side fallback for other fields.
+
+### Changed
+
+- CI and release workflows now use `.github/constraints-ci.txt` to keep lint,
+  type-check, test, and packaging tool versions reproducible without pinning
+  runtime/provider dependencies for downstream applications.
+- LangChain, CrewAI and Google ADK integrations now support streaming through
+  their native adapter protocols; LangChain also supports `bind_tools()`.
+- Prompt content can contain text, image, audio and document parts. OpenAI,
+  Azure, Anthropic, Gemini and Bedrock preserve supported rich content while
+  guardrails, PII redaction, token accounting and memory use a safe text view.
+- Bedrock Converse streaming now accumulates `toolUse` deltas and executes the
+  generic agent tool loop.
+
+### Fixed
+
+- RAG retrievers now reject negative `top_k` values instead of relying on
+  Python slicing semantics.
+- Three `WeaviateRetriever` tests only passed when `weaviate-client` happened
+  to be installed locally, because `_collection_properties()`/
+  `_native_metadata_filter()` do a real (unmocked) `from weaviate.classes...
+  import ...` that a mocked `client=` object can't stand in for. This wasn't
+  caught by the "326 tests passed" gate recorded earlier in
+  `docs/technical-review.md`, because that run had `weaviate-client`
+  installed -- CI's `lint-and-test` job (`pip install -e ".[ci]"`, no
+  optional extras) would have failed on these 3. Fixed by mocking
+  `weaviate.classes.config`/`.query` the same way the other optional
+  vector-store dependencies already are; verified clean with zero optional
+  packages installed, matching real CI exactly.
+
+### Security
+
+- Dashboard log rendering no longer interpolates untrusted content as HTML.
+- SQL table identifiers are validated before being used by the pgvector
+  adapter.
+
+## [0.0.9] - 2026-09-28
+
+### Added
+
+- `AnthropicProvider`/`CohereProvider`/`GeminiProvider` now implement
+  `stream()`/`astream()` (previously unimplemented, raised
+  `NotImplementedError`), each using that provider's native streaming API
+  and yielding plain text chunks. Not verified against a live account --
+  same caveat as the Azure/Bedrock adapters.
+- `run_stream()`/`run_stream_async()` now accept `response_model=`. Returns
+  a `StreamedStructuredResult`/`AsyncStreamedStructuredResult` instead of a
+  plain iterator: iterate it for the raw JSON text as it streams, and read
+  `.result` after the loop ends for the validated `response_model`
+  instance (partial JSON isn't a valid model, so there's nothing to
+  validate until the stream is done). Can't be combined with `tools=`
+  (raises `ValueError`).
+
+## [0.0.8] - 2026-09-28
+
+### Added
+
+- `ModerationGuardrail`: flags input/output via OpenAI's moderation
+  endpoint, for adversarial/unsafe content the local keyword/regex/topic
+  guardrails aren't meant to catch. Fails closed by default (`fail_open=`
+  to opt out).
+- `RIVOTRIL_DASHBOARD_TOKENS`: multiple named bearer tokens for the
+  dashboard (`"label1:token1,label2:token2"`) instead of one shared secret;
+  each valid token's label is logged on access. `RIVOTRIL_DASHBOARD_TOKEN`
+  (singular) still works as a single unlabeled token.
+- `AzureOpenAIProvider` and `BedrockProvider`: new provider adapters.
+  Azure OpenAI uses the `openai` SDK's dedicated `AzureOpenAI`/
+  `AsyncAzureOpenAI` clients (no extra install). Bedrock uses the Bedrock
+  Runtime Converse API for one request shape across model families
+  (requires `llmrivotril[bedrock]`); `tools=` isn't translated to Converse's
+  tool-call format yet, and `acomplete`/`astream` run the synchronous boto3
+  call in a worker thread since boto3 has no official async client. Neither
+  adapter has been verified against a live Azure/AWS account -- built from
+  documented API shapes and covered by mocked unit tests only.
+- `PgVectorRetriever`, `QdrantRetriever`, `WeaviateRetriever`,
+  `PineconeRetriever`: external vector-store retrievers for RAG beyond
+  in-memory scale, behind `llmrivotril[pgvector|qdrant|weaviate|pinecone]`
+  (or `llmrivotril[vector-stores]` for all four). Also not verified against
+  a live service -- same caveat as the two new providers.
+
+### Fixed
+
+- The non-streaming multi-round tool-calling loop
+  (`_handle_tool_calls`/`_handle_tool_calls_async`) passed `tools=None` on
+  every follow-up call after the first, so a conversation needing a second
+  tool call in the same turn could never request one -- the model was never
+  offered any tool schemas past round one.
+
+## [0.0.7] - 2026-09-28
+
+### Added
+
+- `InMemoryEmbeddingRetriever(cache_path=...)`: content-hash-keyed embedding
+  cache persisted to JSON, so re-ingesting unchanged document content across
+  process restarts skips recomputing its embedding.
+- `run_stream()`/`run_stream_async()` accept `tools=`; a turn where the model
+  answers directly still streams token by token, and a turn where it calls a
+  tool falls back to a single blocking round-trip for that turn.
+- `MemoryStore(auto_save_path=...)` / `RIVOTRIL_MEMORY_PATH`: persist
+  conversation history to a JSON file automatically, mirroring
+  `RIVOTRIL_METRICS_PATH`/`RIVOTRIL_CACHE_PATH`.
+- `RAGPipeline.aingest()`/`RAGPipeline.aquery()`: async wrappers (via a
+  worker thread) so ingestion/retrieval don't block the event loop inside
+  `run_async()`.
+- `py.typed` marker (PEP 561) so downstream type checkers pick up this
+  package's types.
+- Dashboard endpoints are now rate-limited per client IP
+  (`RIVOTRIL_DASHBOARD_RATE_LIMIT_MAX_CALLS`/`_PER_SECONDS`).
+
+### Fixed
+
+- `InMemoryEmbeddingRetriever.retrieve()` scored documents with a pure-Python
+  cosine-similarity loop; switched to a cached numpy matrix (~5x faster at a
+  few thousand documents), with the pure-Python path kept as a fallback when
+  numpy isn't installed.
+- `InMemoryEmbeddingRetriever._load_model()` had the same unlocked
+  lazy-model-load race already fixed in `semantic.py`; added the same
+  double-checked lock.
+- Deleted `InMemoryKeywordRetriever`'s duplicated `[a-z0-9]+` tokenizer/
+  stopword list (same accent-splitting bug as `verifier.py`); it now reuses
+  the shared, fixed `_tokenize`.
+- Test isolation: `tests/test_config.py` set `os.environ[...]` directly and
+  only had a before-test cleanup fixture, so a var left set by its last test
+  leaked into whatever test module pytest ran next. Also fixed a subtler
+  variant of the same bug in the fix itself: calling `monkeypatch.delenv()`
+  from *inside* another fixture's post-`yield` teardown gets undone by
+  monkeypatch's own finalizer (which runs afterwards, in reverse dependency
+  order) -- switched to plain `os.environ.pop()` for this cleanup.
+
+### Documentation
+
+- Documented that `plugins="auto"` executes code from any installed
+  package's entry points, with no sandboxing.
+- Documented that Azure OpenAI and AWS Bedrock are not supported via
+  `base_url` (they need a different client/auth/request shape, not just a
+  different endpoint).
+- Documented the local dashboard's trust model (single shared token, no
+  per-user accounts -- not for multi-tenant or public exposure).
+
+## [0.0.6] - 2026-09-27
+
+### Added
+
+- Response caching:
+  - `cache=` argument on `RivotrilAgent` (`InMemoryCache`, `DiskCache`, `RedisCache`, or custom `BaseCache`).
+  - `RIVOTRIL_CACHE_PATH` environment variable to activate disk-based caching.
+  - Deterministic cache keys based on model, messages, tools, and response model.
+  - `RedisCache` for multi-process/distributed deployments (optional `llmrivotril[redis]` dependency).
+- Schema-repair fallback for structured outputs:
+  - `schema_repair_attempts=` argument on `RivotrilAgent`.
+  - `RIVOTRIL_SCHEMA_REPAIR_ATTEMPTS` environment variable.
+  - Re-prompts the model with validation errors when Pydantic schema validation fails.
+- Cost tracking:
+  - `track_costs=` argument on `RivotrilAgent`.
+  - `RIVOTRIL_TRACK_COSTS` environment variable.
+  - Built-in pricing table for OpenAI, Anthropic, Cohere, and Gemini models.
+  - `estimate_cost()`, `register_pricing()`, and `list_supported_models()` helpers.
+- PII detection and redaction:
+  - `redact_pii=` argument on `RivotrilAgent`.
+  - `RIVOTRIL_REDACT_PII` environment variable.
+  - `PIIRedactor` with regex scanners for email, CPF, CNPJ, phone, and credit card.
+- Token budget controls on `RivotrilAgent`:
+  - `max_prompt_tokens` and `max_session_tokens` constructor arguments.
+  - `RIVOTRIL_MAX_PROMPT_TOKENS` and `RIVOTRIL_MAX_SESSION_TOKENS` environment variables.
+  - `TokenBudgetExceededError` raised when a run would exceed the configured budget.
+- Plugin system via Python entry points:
+  - Groups `llmrivotril.guardrails` and `llmrivotril.verifiers`.
+  - `plugins="auto"` or `plugins=[...]` on `RivotrilAgent`.
+  - `discover_plugins()` and `load_plugins()` helpers exported from the top-level package.
+- Automatic metrics persistence:
+  - `RIVOTRIL_METRICS_PATH` environment variable and `metrics_path=` argument on `RivotrilAgent`.
+  - `MetricsCollector.load_metrics()` alias for `load_from_json()`.
+- Function calling / tools support:
+  - `tools=` argument on `agent.run()` and `agent.run_async()`.
+  - `ToolRegistry` and `ToolCall` exported from the top-level package.
+  - Accepts OpenAI-style tool dicts or plain Python callables (auto-introspected into schemas).
+  - Built-in tool-call loop with follow-up completion.
+- Offline dashboard: Tailwind CSS is now bundled and served locally instead of loaded from CDN.
+- File-based configuration via `llmrivotril.toml`, `llmrivotril.yaml`, or `[tool.llmrivotril]` in `pyproject.toml`.
+  - Precedence: file defaults < environment variables < constructor arguments.
+- `RIVOTRIL_PROVIDER` environment variable and `provider=` argument on `RivotrilAgent`.
+- Multi-provider support with adapters for OpenAI, Anthropic, Cohere, and Gemini in `llmrivotril.providers`.
+- `ModelBasedFaithfulnessVerifier` for LLM-as-a-judge grounding checks.
+
+### Fixed
+
+- PII redaction now applies to structured (`response_model=`) results and runs
+  before a response is written to `cache=`; previously `redact_pii=True` left
+  structured outputs unredacted and could persist raw PII at rest in the cache.
+- `DiskCache` no longer uses `pickle` (arbitrary code execution risk if the
+  cache file is ever tampered with); it now stores JSON in a local SQLite
+  file, with indexed per-key reads/writes instead of rewriting the whole
+  store on every `get`/`set`.
+- `PIIRedactor.redact()` no longer corrupts text when two pattern matches
+  overlap; overlapping spans are merged before replacement.
+- The local dashboard's token check now uses a constant-time comparison
+  (`secrets.compare_digest`) instead of `!=`, closing a timing side-channel.
+- `_load_dotenv()` no longer silently swallows a missing `python-dotenv`
+  install; it's a core dependency and is now imported unconditionally.
+- Fixed a duplicated `_ENV_INTS` definition in `config.py` that silently
+  discarded the first set of keys.
+- Corrected the configuration-precedence docstring in `config.py` to match
+  the actual lookup order.
+- `CircuitBreaker` no longer lets multiple threads dispatch a HALF_OPEN probe
+  concurrently; checking and transitioning state is now a single atomic
+  operation instead of two separately-locked steps.
+- `KeywordOverlapVerifier`'s tokenizer used `[a-z0-9]+`, which split accented
+  words (e.g. "informação" -> "informa" + "o"), corrupting grounding checks
+  for Portuguese and other accented-language text. Switched to a
+  Unicode-aware pattern and added Portuguese stopwords alongside the
+  existing English list.
+
+## [0.0.5] - 2026-09-25
+
+### Added
+
+- Local RAG module (`llmrivotril.rag`) with:
+  - `Document` model
+  - `TextLoader` and `MarkdownLoader`
+  - `SimpleChunker` with configurable size and overlap
+  - `InMemoryKeywordRetriever` (no external dependencies)
+  - `InMemoryEmbeddingRetriever` (optional `sentence-transformers`)
+  - `RAGPipeline` to ingest sources and feed context into `RivotrilAgent`
+- Re-exported RAG primitives from the top-level `llmrivotril` package.
+
+## [0.0.4] - 2026-09-25
+
+### Added
+
+- `llmrivotril init [PATH]` CLI command to scaffold a new project with:
+  - `pyproject.toml`, `.gitignore`, `.env.example`, `README.md`
+  - package directory with `agent.py` and `guardrails.py`
+  - starter `tests/test_agent.py`
+
+## [0.0.3] - 2026-09-25
+
+### Added
+
+- Environment-variable configuration via `llmrivotril.config.load_env_config()`.
+  - `RIVOTRIL_MODEL`, `RIVOTRIL_API_KEY`, `RIVOTRIL_BASE_URL`, `RIVOTRIL_SYSTEM_PROMPT`
+  - `RIVOTRIL_REQUEST_TIMEOUT`
+  - `RIVOTRIL_RATE_LIMIT_MAX_CALLS`, `RIVOTRIL_RATE_LIMIT_PER_SECONDS`
+  - `RIVOTRIL_RETRY_MAX_ATTEMPTS`, `RIVOTRIL_RETRY_MIN_WAIT`, `RIVOTRIL_RETRY_MAX_WAIT`
+  - `RIVOTRIL_CIRCUIT_FAILURE_THRESHOLD`, `RIVOTRIL_CIRCUIT_RECOVERY_TIMEOUT`
+  - Explicit constructor arguments always override environment values.
+- `/api/health` endpoint on the dashboard returning status, version, and UTC timestamp.
+- Async-safe `AsyncRateLimiter` used by `RivotrilAgent.run_async()`.
+- `system_prompt` support injected as a `system` message.
+- `context_sources` accepts `str | list[str] | None` and joins multiple sources.
+- Structured logging through the `llmrivotril` logger.
+- CLI commands: `benchmark`, `doctor`, `version`.
+- `request_timeout` forwarded to OpenAI/instructor calls.
+- Per-agent `metrics` injection and `MetricsCollector.reset()`.
+- `disallowed_patterns` regex guardrails on input and output.
+
+### Changed
+
+- `tiktoken` encoding now falls back to `cl100k_base` for unknown model names, improving compatibility with local/Ollama models.
+- `Guardrail` output validation also checks `disallowed_keywords`.
+
+## [0.0.2] - 2026-09-24
+
+### Added
+
+- First packaged release of LLM-Rivotril.
+
+## [0.0.1] - 2026-09-20
+
+### Added
+
+- Proof-of-concept agent with basic guardrails.

llmrivotril-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to LLM-Rivotril
+
+Thank you for your interest in improving LLM-Rivotril!
+
+## Getting Started
+
+1. Fork the repository.
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/your-username/llmrivotril.git
+   cd llmrivotril
+   ```
+3. Create a virtual environment and install in editable mode:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate
+   pip install -e ".[dev]"
+   ```
+   For a lighter install that skips optional provider SDKs and semantic dependencies,
+   use `pip install -e ".[ci]"`.
+
+## Development Workflow
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. Make your changes, adding tests for new behavior.
+3. Run the test suite:
+   ```bash
+   pytest
+   ```
+4. Run linting and type checks:
+   ```bash
+   ruff check src tests examples scripts
+   ruff format --check src tests examples scripts
+   mypy src
+   ```
+5. Commit your changes and open a pull request.
+
+## Code Style
+
+- Follow PEP 8.
+- Use type hints for public functions and classes.
+- Keep functions focused and small.
+- Write docstrings for modules, classes, and public methods.
+
+## Testing
+
+- Place unit tests in `tests/`.
+- Use `pytest` fixtures to isolate stateful components such as `MemoryStore` and `MetricsCollector`.
+- Mock external API calls (OpenAI / Instructor) in agent tests.
+
+## Reporting Issues
+
+When reporting bugs, include:
+
+- Python version
+- Package version (`pip show llmrivotril`)
+- Minimal reproducible example
+- Expected vs actual behavior
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

llmrivotril-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLM-Rivotril Contributors
+
+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.