arandu 0.1.0__tar.gz

arandu-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,44 @@
+name: Bug Report
+description: Report a bug in arandu
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Initialize MemoryClient with ...
+        2. Call memory.write(...)
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Your environment details.
+      placeholder: |
+        - Python version: 3.11
+        - arandu version: 0.1.0
+        - OS: Ubuntu 22.04
+        - PostgreSQL version: 16
+    validations:
+      required: false

arandu-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature Request
+description: Suggest a new feature for arandu
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve?
+      placeholder: I'm always frustrated when ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or workarounds you've considered.
+    validations:
+      required: false

arandu-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Description
+
+<!-- What does this PR do? Why is this change needed? -->
+
+## Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Lint passes (`ruff check .` and `ruff format --check .`)
+- [ ] Type check passes (`mypy src/`)
+- [ ] No breaking changes (or documented below)
+
+## Breaking Changes
+
+<!-- If this PR introduces breaking changes, describe them here. Otherwise, delete this section. -->

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

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python-version }}-
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Type check
+        run: mypy src/
+
+      - name: Tests
+        run: pytest

arandu-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'src/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-docs-${{ hashFiles('mkdocs.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-docs-
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material mkdocstrings[python] pymdown-extensions mkdocs-static-i18n
+          pip install -e ".[openai]"
+
+      - name: Check docs coverage
+        run: python scripts/check_docs_coverage.py
+
+      - name: Generate llms.txt
+        run: python scripts/generate_llms_txt.py
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

arandu-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

arandu-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+site/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.env

arandu-0.1.0/.vibeflow/prds/oss-ready.md

@@ -0,0 +1,77 @@
+# PRD: Preparar o repositório arandu para open-source
+
+> Generated via /vibeflow:discover on 2026-03-18
+
+## Problem
+
+O arandu (long-term memory para AI agents) é um projeto funcional com ~40 arquivos de código, 23 suítes de teste e documentação bilíngue (EN/PT-BR), mas o repositório não tem a infraestrutura que desenvolvedores open-source sérios esperam. Faltam sinais básicos de maturidade: CI rodando testes, arquivo de licença, guia de contribuição, templates de issues/PRs, e o README contém links quebrados referenciando um nome antigo ("personal-genius") e paths que não existem ("packages/memory-sdk"). Além disso, o pacote ainda não foi publicado no PyPI.
+
+Quem chega no GitHub hoje vê um projeto sem CI, sem licença-arquivo, com links 404 no README — e descarta. O objetivo é que um dev experiente bata o olho e pense "projeto bem mantido, posso confiar e contribuir".
+
+## Target Audience
+
+Desenvolvedores Python que trabalham com AI/LLM agents e buscam uma solução de memória de longo prazo. Perfil: engenheiros de software que avaliam qualidade de OSS antes de adotar — olham CI, licença, contribuição, e atividade do projeto.
+
+## Proposed Solution
+
+Adicionar toda a infraestrutura padrão de um projeto open-source profissional e publicar o pacote no PyPI:
+
+- **README corrigido** — links reais, URLs corretas, path de setup correto
+- **Arquivo LICENSE** (MIT)
+- **CONTRIBUTING.md** — setup de dev, como rodar testes, padrão de PRs
+- **CODE_OF_CONDUCT.md** — Contributor Covenant
+- **SECURITY.md** — política de reporte de vulnerabilidades
+- **CI completo** — GitHub Actions com pytest + ruff + mypy
+- **Issue templates e PR template** — bug report, feature request, PR checklist
+- **pyproject.toml completo** — URLs (homepage, repo, issues), email do autor
+- **Publicação no PyPI** — workflow de CD com Trusted Publishers (OIDC)
+
+## Success Criteria
+
+1. Um dev clona o repo, roda `pip install -e ".[dev]"` e `pytest` — funciona sem fricção
+2. O README não tem nenhum link quebrado e mostra badges reais (CI, PyPI, license)
+3. CI roda em todo push/PR: testes passam, lint passa, type check passa
+4. `pip install arandu` funciona via PyPI
+5. Existe guia claro de como contribuir (CONTRIBUTING.md)
+6. Issue templates aparecem ao criar nova issue no GitHub
+
+## Scope v0
+
+- [ ] Corrigir README.md (links, badges, paths, URL real do GitHub Pages)
+- [ ] Criar arquivo `LICENSE` (MIT, autor Pedro Menezes)
+- [ ] Criar `CONTRIBUTING.md` (setup, testes, lint, PR guidelines)
+- [ ] Criar `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1)
+- [ ] Criar `SECURITY.md` (política de vulnerabilidades)
+- [ ] Criar `.github/workflows/ci.yml` (pytest + ruff + mypy)
+- [ ] Criar `.github/workflows/publish.yml` (PyPI via Trusted Publishers)
+- [ ] Criar `.github/ISSUE_TEMPLATE/bug_report.yml`
+- [ ] Criar `.github/ISSUE_TEMPLATE/feature_request.yml`
+- [ ] Criar `.github/PULL_REQUEST_TEMPLATE.md`
+- [ ] Atualizar `pyproject.toml` (urls, email, classifiers)
+
+## Anti-scope
+
+- **CHANGELOG.md** — usar GitHub Releases por agora
+- **Bot de stale issues** — overhead desnecessário pra v0.1.0
+- **GitHub Discussions** — pode ativar depois se houver comunidade
+- **Pre-commit hooks** — CI já cobre lint/format
+- **Docker / docker-compose** — testes rodam com mock, não precisa de Postgres no CI
+- **Badges de cobertura (codecov)** — pode adicionar depois
+- **Configuração de branch protection rules** — é manual no GitHub, fora do repo
+- **Tradução dos arquivos de OSS** — CONTRIBUTING/CODE_OF_CONDUCT ficam em inglês (padrão)
+- **Reestruturação de código** — foco é infraestrutura, não refactoring
+
+## Technical Context
+
+- **Stack:** Python 3.11+, hatchling (build), SQLAlchemy, pgvector, pydantic
+- **Testes:** Todos com mock (FakeLLMProvider, FakeEmbeddingProvider) — não precisam de Postgres no CI
+- **Lint/format:** ruff já configurado no pyproject.toml
+- **Type check:** mypy strict já configurado no pyproject.toml
+- **Docs:** MkDocs Material, bilíngue, deploy via GitHub Actions (já funciona)
+- **GitHub:** repo `pe-menezes/arandu`, Pages em `pe-menezes.github.io/arandu/`
+- **PyPI:** conta `pe-menezes`, Trusted Publisher configurado (arandu → pe-menezes/arandu, workflow publish.yml, environment pypi)
+- **Email do autor:** pedromenezesrs@gmail.com
+
+## Open Questions
+
+Nenhuma questão aberta. Todas as dependências externas foram resolvidas.

arandu-0.1.0/.vibeflow/specs/oss-ready-part-1.md

@@ -0,0 +1,69 @@
+# Spec: OSS-Ready — Part 1: Core Files
+
+> Source PRD: `.vibeflow/prds/oss-ready.md`
+
+## Objective
+
+Tornar o repositório arandu reconhecível como projeto open-source profissional adicionando os arquivos-base que devs experientes esperam (LICENSE, CONTRIBUTING, README correto, pyproject.toml completo).
+
+## Context
+
+O README atual tem 6 links apontando para `your-org.github.io/personal-genius/` (URL errada — o correto é `pe-menezes.github.io/arandu/`), referencia um path `packages/memory-sdk` que não existe, e não tem badges funcionais. O `pyproject.toml` não tem `[project.urls]` nem email do autor. Não existe arquivo LICENSE (apesar de declarar MIT), nem CONTRIBUTING, CODE_OF_CONDUCT ou SECURITY.
+
+## Definition of Done
+
+1. **LICENSE existe** — Arquivo `LICENSE` na raiz com texto completo da MIT, copyright "Pedro Menezes".
+2. **README sem links quebrados** — Todos os links no README.md apontam para URLs reais (`pe-menezes.github.io/arandu/`, `github.com/pe-menezes/arandu`, `pypi.org/project/arandu/`). Nenhuma ocorrência de `your-org` ou `personal-genius`.
+3. **README com badges reais** — Badges de CI (workflow `ci.yml`), PyPI, License, e Docs apontam para URLs corretas.
+4. **CONTRIBUTING.md existe** — Com seções: Prerequisites, Development Setup, Running Tests, Code Style, Pull Request Guidelines.
+5. **CODE_OF_CONDUCT.md e SECURITY.md existem** — Contributor Covenant 2.1 e política de reporte de vulnerabilidades.
+6. **pyproject.toml completo** — Contém `[project.urls]` (Homepage, Repository, Documentation, Issues, Changelog) e email do autor.
+
+## Scope
+
+- Criar `LICENSE` (MIT, 2025, Pedro Menezes)
+- Reescrever `README.md`: corrigir todos os links, adicionar badges reais, remover referência a `packages/memory-sdk` (trocar por `await memory.initialize()`), remover seção "Database Setup" com alembic (o SDK cria as tabelas automaticamente)
+- Criar `CONTRIBUTING.md` em inglês
+- Criar `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1)
+- Criar `SECURITY.md` (reportar via email pedromenezesrs@gmail.com)
+- Atualizar `pyproject.toml`: adicionar `[project.urls]`, adicionar email ao autor
+
+## Anti-scope
+
+- NÃO alterar código-fonte em `src/`
+- NÃO criar workflows (Part 2)
+- NÃO criar issue/PR templates (Part 2)
+- NÃO traduzir CONTRIBUTING/CODE_OF_CONDUCT para PT-BR
+- NÃO adicionar CHANGELOG.md
+- NÃO modificar conteúdo da documentação MkDocs
+
+## Technical Decisions
+
+| Decisão | Escolha | Justificativa |
+|---------|---------|---------------|
+| Idioma dos arquivos OSS | Inglês | Padrão da indústria; devs de qualquer país leem |
+| License year | 2025 | Ano de início do projeto |
+| CONTRIBUTING: install command | `pip install -e ".[dev]"` | Já funciona com o pyproject.toml atual |
+| CONTRIBUTING: test command | `pytest` | asyncio_mode=auto já configurado |
+| CONTRIBUTING: lint command | `ruff check . && ruff format --check .` | Já configurado no pyproject.toml |
+| CONTRIBUTING: type check | `mypy src/` | Strict mode já configurado |
+| Badge de CI | Aponta para workflow `ci.yml` | Será criado na Part 2; badge já fica correto |
+| Seção "Database Setup" do README | Remover referência a alembic/packages | O path `packages/memory-sdk` não existe; `await memory.initialize()` já é documentado |
+
+## Applicable Patterns
+
+Nenhum `.vibeflow/patterns/` existe. Convenções inferidas do código:
+- Markdown files usam heading hierarchy padrão
+- pyproject.toml usa hatchling como build backend
+- Projeto é bilíngue mas arquivos de governança ficam em inglês
+
+## Risks
+
+| Risco | Mitigação |
+|-------|-----------|
+| Badge de CI vai mostrar "not found" até Part 2 ser implementada | Aceitável — badge aponta para URL correta, só precisa do workflow existir |
+| README pode ter links que dependem de paths futuros | Usar apenas URLs que já existem hoje (GitHub Pages, GitHub repo, PyPI project) |
+
+## Budget
+
+6 arquivos: `LICENSE`, `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `pyproject.toml`

arandu-0.1.0/.vibeflow/specs/oss-ready-part-2.md

@@ -0,0 +1,72 @@
+# Spec: OSS-Ready — Part 2: CI/CD + GitHub Templates
+
+> Source PRD: `.vibeflow/prds/oss-ready.md`
+
+## Objective
+
+Automatizar qualidade (CI em todo push/PR) e publicação no PyPI, e padronizar a contribuição com templates de issues e PRs.
+
+## Context
+
+O repo já tem um workflow `docs.yml` para deploy de documentação. Não existe CI para testes/lint/typecheck — qualquer PR pode quebrar o código sem ninguém perceber. O Trusted Publisher do PyPI já está configurado (arandu → pe-menezes/arandu, workflow publish.yml, environment pypi). Faltam templates para issues e PRs.
+
+## Dependencies
+
+- `.vibeflow/specs/oss-ready-part-1.md` — pyproject.toml precisa estar atualizado (URLs, email) antes do publish workflow rodar.
+
+## Definition of Done
+
+1. **CI roda em push/PR** — Workflow `.github/workflows/ci.yml` executa pytest, ruff check, ruff format --check, e mypy em Python 3.11 e 3.12.
+2. **Publish workflow existe** — `.github/workflows/publish.yml` publica no PyPI via Trusted Publishers quando uma release é criada no GitHub.
+3. **Bug report template funciona** — `.github/ISSUE_TEMPLATE/bug_report.yml` com campos: description, steps to reproduce, expected behavior, environment.
+4. **Feature request template funciona** — `.github/ISSUE_TEMPLATE/feature_request.yml` com campos: problem, proposed solution, alternatives considered.
+5. **PR template existe** — `.github/PULL_REQUEST_TEMPLATE.md` com checklist: description, tests, lint, breaking changes.
+
+## Scope
+
+- Criar `.github/workflows/ci.yml`
+- Criar `.github/workflows/publish.yml`
+- Criar `.github/ISSUE_TEMPLATE/bug_report.yml` (YAML form, não markdown)
+- Criar `.github/ISSUE_TEMPLATE/feature_request.yml` (YAML form)
+- Criar `.github/PULL_REQUEST_TEMPLATE.md`
+
+## Anti-scope
+
+- NÃO modificar `docs.yml` existente
+- NÃO adicionar codecov/coverage reporting
+- NÃO adicionar pre-commit hooks
+- NÃO adicionar dependabot/renovate
+- NÃO criar workflow de release notes automáticas
+- NÃO usar matriz com OS (ubuntu-only é suficiente)
+- NÃO rodar testes com Postgres real (todos usam mock)
+
+## Technical Decisions
+
+| Decisão | Escolha | Justificativa |
+|---------|---------|---------------|
+| CI matrix | Python 3.11 + 3.12 no ubuntu-latest | pyproject.toml declara >=3.11; testar nas 2 versões estáveis |
+| CI trigger | push to main + pull_request | Padrão; PR verifica antes de merge, push garante main limpo |
+| Publish trigger | `on: release: types: [published]` | Padrão PyPI; tag-based é alternativa mas release é mais explícito |
+| Publish method | Trusted Publishers (OIDC) | Já configurado no PyPI; sem tokens para gerenciar |
+| PyPI environment | `pypi` | Configurado no Trusted Publisher |
+| Issue templates | YAML forms (não .md) | UX melhor: campos estruturados, dropdowns, validação |
+| Build tool no publish | `hatchling` via `python -m build` | Já é o build backend do projeto |
+
+## Applicable Patterns
+
+Nenhum `.vibeflow/patterns/` existe. Convenções inferidas:
+- Workflow existente (`docs.yml`) usa `actions/checkout@v4`, `actions/setup-python@v5`, `actions/cache@v4`
+- pip install com `pip install -e ".[dev]"` para testes
+
+## Risks
+
+| Risco | Mitigação |
+|-------|-----------|
+| Testes falham no CI por dependência não declarada | CI instala `pip install -e ".[dev]"` — mesmo comando do dev local |
+| mypy falha no CI por tipagem incompleta | mypy já roda local com strict; se passa local, passa no CI |
+| Publish falha por Trusted Publisher mal configurado | Já verificado: screenshot confirma config correta no PyPI |
+| Rate limit no PyPI em primeiro publish | Improvável para projeto novo; retry manual se necessário |
+
+## Budget
+
+5 arquivos: `ci.yml`, `publish.yml`, `bug_report.yml`, `feature_request.yml`, `PULL_REQUEST_TEMPLATE.md`

arandu-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+By participating in this project, you agree to abide by its terms.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please report it by emailing **pedromenezesrs@gmail.com**. All reports will be handled with discretion.

arandu-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to arandu
+
+Thank you for your interest in contributing to arandu! This guide will help you get started.
+
+## Prerequisites
+
+- Python 3.11 or later
+- Git
+
+## Development Setup
+
+1. **Fork and clone the repository:**
+
+   ```bash
+   git clone https://github.com/<your-username>/arandu.git
+   cd arandu
+   ```
+
+2. **Create a virtual environment:**
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Linux/macOS
+   # or
+   .venv\Scripts\activate     # Windows
+   ```
+
+3. **Install in development mode:**
+
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Running Tests
+
+All tests use mock providers (no database required):
+
+```bash
+pytest
+```
+
+To run a specific test file:
+
+```bash
+pytest tests/test_extraction.py
+```
+
+## Code Style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy-lang.org/) for type checking.
+
+**Check linting and formatting:**
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+**Auto-fix lint issues and format code:**
+
+```bash
+ruff check --fix .
+ruff format .
+```
+
+**Run type checking:**
+
+```bash
+mypy src/
+```
+
+Please ensure all three checks pass before submitting a pull request.
+
+## Pull Request Guidelines
+
+1. **Create a feature branch** from `main`:
+
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+
+2. **Keep changes focused.** One pull request per feature or bug fix.
+
+3. **Write tests** for new functionality.
+
+4. **Ensure all checks pass:**
+
+   ```bash
+   pytest
+   ruff check .
+   ruff format --check .
+   mypy src/
+   ```
+
+5. **Write a clear PR description** explaining what changed and why.
+
+6. **Link related issues** in the PR description (e.g., "Closes #42").
+
+## Reporting Bugs
+
+Please use the [GitHub Issues](https://github.com/pe-menezes/arandu/issues) page to report bugs. Include:
+
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs. actual behavior
+- Python version and OS
+
+## Questions?
+
+Feel free to open an issue for questions or discussions about the project.

arandu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Menezes
+
+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.