Jinx — Autonomous Engineering Agent

I’m Jinx. An autonomous engineering agent built for teams that ship. I convert intent into execution: understand goals, generate code, validate, run in a sandbox, and deliver — auditable and reproducible by design.

Enterprise standards. Minimal surface area. Maximum signal.

Built for engineers. Comfortable in regulated environments. Consistent about reliability.

🚀 Features

• Autonomous loop with safe, sandboxed code execution
• Durable memory: <evergreen> facts + compact rolling context
• Embeddings retrieval from recent dialogue/sandbox for grounded answers
• Retry/timeout wrappers around model calls; structured OpenAI request logging
• Zero‑friction setup: optional dependencies ensured at runtime
• Extensible prompts via jinx/prompts/ and configuration
• Real‑time snippet caching (TTL + LRU + coalescing) with file‑watcher invalidation
• Micro‑modular architecture: thin facades in jinx/embeddings/*, logic in jinx/micro/*

🔧 Environment Setup

Python Virtual Environment

Before setting up the project, it's recommended to create a virtual environment. Follow these steps:

Learn about virtual environments: Python Packaging Guide

Create and activate a virtual environment:

Windows:

py -m venv .venv
.venv\Scripts\activate

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate

Project Setup

• Runtime ensures optional dependencies when needed (e.g., aiofiles, prompt_toolkit). No requirements.txt necessary.
• Provide an OpenAI API key and configuration via .env at project root. See .env.example for all keys:

Required:

OPENAI_API_KEY=

Optional (defaults in code / example):

PULSE=120           # initial error-tolerance pulse
TIMEOUT=300         # seconds before autonomous thinking
OPENAI_MODEL=gpt-5  # model override; service falls back to gpt-5 if unset
# PROXY=socks5://127.0.0.1:12334

Create .env from the example:

Windows (PowerShell):

Copy-Item .env.example .env
  - Integrates embeddings context (`jinx/embeddings/retrieval.py`)
  - Injects durable `<evergreen>` facts (`jinx/memory/storage.py` → `read_evergreen()`)
  - Invokes the model (`jinx/openai_service.py`) and executes code blocks in sandbox
- **Memory Optimization**: `jinx/memory/optimizer.py`
  - Compacts transcript into `<mem_compact>` and persists `<mem_evergreen>`
  - Writes state via `jinx/memory/storage.py`
- **Embeddings**: `jinx/embeddings/pipeline.py`, `jinx/embeddings/retrieval.py`
  - Facades live in `jinx/embeddings/*`; heavy retrieval/snippet logic in `jinx/micro/embeddings/*`
- **Sandbox**: `jinx/sandbox/*` (separate process, non-blocking)
- **Logging**: targets defined in `jinx/log_paths.py`; OpenAI request dumps under `log/openai/*`
- **Prompts**: configured via `jinx/config.py`, defined under `jinx/prompts/`


## 🧪 Testing Tips

- Keep services small and injectable. The `jinx/contracts.py` file outlines optional Protocols to guide decoupling.
- For sandboxed execution, assert on log file contents rather than stdout.

## 🔐 Security & Compliance

- **Secrets**: Provide keys via `.env` or environment variables (see `.env.example`). Keys are not logged.
- **Sandbox boundary**: All code generated by the model executes in an isolated sandbox process. This is a safety layer, not a hard security boundary.
- **Logging scope**: Structured logs live under `log/`. Avoid placing sensitive data in prompts. OpenAI request dumps capture instructions and input payloads for auditability.
- **Data retention**: Evergreen memory stores durable facts you explicitly surface; ephemeral transcript is compacted routinely.
- **Network/Dependencies**: Optional dependencies are ensured at runtime; pin if your environment requires deterministic builds.

## 🤖 Responsible AI

- Human-in-the-loop recommended for critical paths.
- Deterministic audit trail: inputs, headers, model outputs, and executed code are logged.
- No training occurs on your data within this repository. External model behavior is governed by your chosen provider’s policies.

## 💬 Support

- File issues and feature requests in GitHub Issues.
- For questions and design proposals, open a Discussion or start with an Issue to scope the change.