# Technical Choices (Sketch): FPF Agent Stack
Decisions + trade-offs.
## 1. Hard constraints (given)
- Only FunctionGemma is used for intelligence (tool selection and argument construction).
- State/files/auditing must use AgentFS.
- Tools must follow the Agent Skills packaging pattern (skills as folders).
- BDD tests written in Cucumber/Gherkin.
## 2. Recommended baseline stack (v0)
| Area | Pick | Why it fits |
| :--- | :--- | :--- |
| **Runtime language** | TypeScript (Node.js 20+) | Strong JSON tooling, great Cucumber support, easy schema validation. |
| **BDD runner** | Cucumber.js | Native Gherkin; rich reporters. |
| **Schema validation** | Zod or Ajv | Fail-fast tool-call argument validation. |
| **Process isolation** | AgentFS CLI for dev; AgentFS SDK later | CLI gives quick wins; SDK gives tighter integration. |
| **Model runtime** | Ollama local API | Simple local inference for functiongemma tags. |
| **Logging** | Structured JSON logs + RunTrace file | Auditable by humans and machines. |
| **CI** | GitHub Actions | Run unit tests + cucumber; store artifacts. |
## 3. Alternatives (keep honest)
| Choice | Alt | Cost/benefit |
| :--- | :--- | :--- |
| **Runtime language** | Python | Faster prototyping, but Cucumber is less native (often Behave). |
| **Schema validation** | JSON Schema only | Simple but harder to give good error messages without a validator library. |
| **BDD runner** | SpecFlow / Cucumber-JVM | Great in .NET/Java ecosystems; heavier setup. |
## 4. Function calling contract
Treat the model output as untrusted. Enforce a strict tool-call JSON envelope.
```typescript
ModelResponse {
thought?: string # optional; ignored by executor
tool_calls?: [{name: string, arguments: object}]
final?: string
}
```
**Rules:**
- executor ignores thought
- `tool_calls` validated against `ToolSpec.input_schema`
- unknown tool => abstain (no execution)
## 5. Training loop (after baseline)
Start with prompt discipline; only then consider fine-tuning. Use audited traces as ground truth.
- Collect RunTrace + expected tool calls from passing cucumber scenarios.
- Derive supervised examples: (messages + tool schemas) -> (tool call JSON).
- Fine-tune FunctionGemma with LoRA (or the published recipe) to reduce schema errors and improve tool selection.
- Re-run full cucumber suite as the acceptance gate for each new model tag.
## 6. Operational posture (risk control)
- Skill allowlist by folder and by tool name.
- No network by default. If you add network tools, ship them as separate skills with explicit guards and auditing.
- AgentFS sessions are treated as artifacts: keep DB snapshots alongside run traces for reproducibility.
## Appendix: Version pinning
Pin everything: functiongemma tag + skill commit hashes + schema IDs. Without pinning, debugging becomes folklore.
