Gyovana Santos do Prado

Built in FastAPI with Pydantic AI for parsing. Core pipeline: fact extraction → multi-pass atomization → document generation (H3 pattern). Grounding guardrail rejects any claim without direct record provenance. Multi-provider architecture (OpenAI and Anthropic validated interchangeably via model-as-config). DAG-aware build sequencing: parallel cards where dependencies allowed, sequential where schemas needed to stabilize first. Empirically closed one architectural question — on-demand fact calculation was scoped out after zero occurrences appeared in real data runs, avoiding premature abstraction. Six stacked PRs structured for clean merge sequence.

Spike comparing three LLM extraction flows for qualitative open-ended survey data using Pydantic AI and Jinja-templated prompts (via ai-prompter):

• H3 (two-stage: facts → atomic claims → synthesis): $0.0216/doc, 0 altitude violations, 100% quote grounding
• H1+separate-doc: $0.0296/doc, 1 altitude violation, 71% fact-family coverage
• H3+predraft (H3 + refinement draft): $0.0348/doc, 3 altitude violations, 60% more claims but noisier

Key trade-off: H3+predraft generated 60% more claims than H3 but introduced 3 'altitude violations' (over-generalized statements unsupported by the data). H1 had better fact coverage (71% vs 57% of families) but higher cost and one violation. H3 won on every weighted criterion.

Pipeline also includes a deterministic PII guard (emails, phones, CPF, social handles) running before any LLM call — 20% of real responses contained PII, making this non-optional. A quote_grounding validator confirms every generated claim traces back to a verbatim quote, making the pipeline fully auditable. Fact index covers 67 facts across 7 families (boolean, categorical, cooccurrence, cross_tab, matrix, multi_select, persona).

The parser uses Pydantic AI with output_type=PersonaSpec, and PersonaSpec contains PersonaVariable objects with optional order and scale fields. The design choice: both fields use Optional[list] = None rather than list[str] = []. Reason: the downstream factory calls model_dump(exclude_none=True) and then checks 'order' in var — an empty list [] would be falsy in a boolean check but truthy for in, silently breaking ordinal variable handling. With None defaults, exclude_none=True removes the keys entirely, and 'order' in var correctly returns False for categorical variables. The test suite uses Pydantic AI's TestModel(custom_output_args={...}) to override the LLM with deterministic structured output — no API calls needed in CI. One test (test_parse_persona_spec_model_dump_exclui_nulos) explicitly documents the key-absence invariant. Stack: Pydantic AI, FastAPI, Pydantic v2, pytest.

SurrealDB v3, Python, uv. The migration adds new SCHEMAFULL tables and re-types several existing fields. Key constraint: re-typing a field on a pre-existing SCHEMAFULL table requires DEFINE FIELD OVERWRITE — a plain DEFINE FIELD silently no-ops or errors depending on SurrealDB version. The down migration reverses in strict dependency order and explicitly removes array sub-fields to avoid residual ghost sub-fields after table cleanup.

Environment bug: two projects sharing the same SurrealDB namespace/database made their migration tracking tables collide. The other project's runner had inserted rows into the shared table; when rolling back, the runner couldn't find the corresponding migration files in the current project's directory and aborted. Immediate fix: manual deletion of the contaminating rows. Long-term fix: each project gets its own namespace/database pair in local dev.

Architecture session for an async FastAPI service (Python / Pydantic AI / SurrealDB) that processes survey data into structured, auditable insights — replacing a legacy claude -p shell pipeline.

Measure before decide: Before committing to a retrieval/selection pipeline, wrote a scratch script querying the live SurrealDB instance to measure the actual persisted fact space. Result: 12–14 k tokens (6% of context window). No pipeline was justified until that symptom appeared in production — a concrete number closed a debate that would otherwise have been speculative.

Hybrid deterministic/LLM regime: Split the insight core into two invariant regimes:

• Closed questions (Likert, NPS, multiple-choice): pure Python, fully deterministic, golden-testable — LLM never touches this path.
• Open-ended / qualitative: LLM identifies themes and frequency patterns; a deterministic quote-grounding check (verbatim substring match against the source CSV) validates every claim before persistence. Hallucination caught without embeddings — zero cost, fully auditable. The invariant: every qualitative fact must cite a traceable source fragment.

Guardrail failure as eval signal: Pydantic AI output validator retries once on failure; persistent failures are stored with a guardrail_failed flag rather than discarded. Rationale: in early production runs, failure rate is the most useful quality signal — silently discarding failed outputs hides exactly what you need to learn.

Fact space recomputed per run: Each run rebuilds its own fact space from source specs and persists it independently. Trade-off: redundant computation vs. full reproducibility — any run can be re-audited in isolation regardless of future schema or data changes.

Three components: an Astro static site (i18n EN/PT, feed/projects/CV rendered from JSON at build time), a Python MCP server exposing five tools (log_activity, review_and_publish, add_project, update_now, get_portfolio_state) that write through the GitHub Contents API, and a Stop hook that embeds the rubric verbatim so criteria changes require no code changes. Validation runs three layers deep: JSON Schema, bilingual completeness (a missing translation fails the build, by design), and a local denylist as a deterministic backstop behind the LLM's category-based sanitization.

animation-timeline: view() maps an animation's progress to an element's position in the viewport — the timeline border scales from 0 to full height as each entry crosses it. Wrapped in @supports so unsupported browsers just see the static border, and disabled under prefers-reduced-motion. The rest of the motion system is a ~30-line inline IntersectionObserver (staggered reveal) gated behind an html.js class, so a JavaScript failure can never leave content hidden.

• Stack: Python + subprocess, Claude Code CLI (claude -p --output-format json)
• Added ROTAS_LLM_PROVIDER=claude-code provider alongside the existing API-based path, so both can coexist
• Root cause: global Stop hooks (used for portfolio session evaluation) were inherited by the headless CLI child process, appending their evaluation output to the result field and breaking JSON parsing downstream
• Fix: --settings '{"disableAllHooks": true}' passed to the subprocess invocation
• JSON parser made tolerant of surrounding markdown prose as a defensive measure against future prompt drift
• Trade-off accepted: ~95s per query vs 5-10s with a real API key — cost-zero outweighs latency for a personal prototype; UX shows a 'slow AI' warning
• Acceptance criteria met: 6/6 itinerary IDs correct, justifications ≤280 chars, contextual re-ranking correctly inverted priority order and flagged a late-night street transfer as eliminatory

A competent peer might reasonably have chosen a headless CMS or a small API. Git-as-database won on three fronts: full history and rollback for free, zero infrastructure cost, and a deploy pipeline (push → rebuild) that static hosts provide out of the box. The drafts branch exists for confidentiality, not relevance — client work must never auto-publish without a human glance. Trade-off accepted: no real-time updates, which a portfolio doesn't need.