Telvyn

# Telvyn

A local-first agent runtime for technical development tasks — investigate, execute controlled actions, and generate traceable responses.

## Quick start

```bash
./install.sh                     # local repo install (recommended)
# or remote bootstrap install:
curl -fsSL https://raw.githubusercontent.com/Angeles-HO/Telvyn/release/v0.1.0-beta/install.sh | bash

# optional: choose another branch/tag for remote bootstrap
curl -fsSL https://raw.githubusercontent.com/Angeles-HO/Telvyn/release/v0.1.0-beta/install.sh | \
	bash -s -- --repo-ref main

# backward-compatible wrapper still supported:
bash scripts/install.sh

telvyn run --task "Your task" --no-tui --wait --json    # or: python3 cli/run.py --task "your task"

# first run right after curl install (without reloading shell):
~/.local/bin/telvyn run --task "Your task" --no-tui --wait --json
```

## Install as package

```bash
pip install .
telvyn run --task "your task"
```

## Project structure

```
Telvyn/
├── telvyn/              # core package
│   ├── core_router/     # semantic router, intent classification
│   ├── runtime/         # task runner, engine resolution
│   ├── i18n/            # en.json / es.json + loader
│   ├── backends/        # ollama, claude, openai_compat
│   ├── tui_screens/     # Textual TUI screens
│   ├── executor.py      # main executor (prompt building, tool dispatch)
│   ├── session_runtime.py
│   ├── task_memory.py
│   └── config.py
├── cli/                 # CLI entrypoints (run.py, plan.py)
├── scripts/             # install.sh, doctor.py, setup_wizard
├── tests/               # unittest suite
├── docs/                # contracts and design docs
└── config/              # user-editable config files
```

## Key design pillars

- **Local-first**: runs on local models (Ollama, compatible APIs) — no cloud dependency required
- **Scope-safe**: workspace policies prevent writes outside the project root
- **Traceable**: every execution flows through Session → Run → Result
- **Deterministic I/O**: workspace reads are contract-driven, no LLM in the loop
- **Hardened**: prompt context limits, confidence decay, single-active goal policy

## i18n

Set `TELVYN_LANG=es` (or `en`, default) to switch UI strings:

```python
from telvyn.i18n import t
print(t("ready"))  # "Listo. ¿Qué necesitas?" or "Ready. What do you need?"
```

## Running tests

```bash
python3 -m unittest discover -s tests -v
```

## Contributing

Open an issue titled `[contrib] area + proposal`. Contributions welcome in:

- Runtime, routing, UX, security, observability
- Testing and regression
- Documentation and examples

## Donations

If you want to support the project, open an issue or PR with your preferred donation channel (GitHub Sponsors, Ko-fi, Buy Me a Coffee) and we'll make it official.

## Reference docs

- [Deterministic Workspace IO Contract](docs/DETERMINISTIC_WORKSPACE_IO_CONTRACT.md)
- [Conversation Session Runtime Model](docs/CONVERSATION_SESSION_RUNTIME_MODEL.md)
- [Architecture overview](docs/ARCHITECTURE.md)
- [Memory model overview](docs/MEMORY_MODEL.md)
- [Workspace contract overview](docs/WORKSPACE_CONTRACT.md)
- [Beta release checklist](docs/BETA_RELEASE_CHECKLIST.md)
- [CHANGELOG](CHANGELOG.md)
- [COMMERCIAL_LICENSE](COMMERCIAL_LICENSE.md)
- [TRADEMARK_POLICY](TRADEMARK_POLICY.md)
- [Backends](backend_local/README.md)

## License

Telvyn is licensed under AGPL-3.0. See [LICENSE](LICENSE) for details.

Local-first usage is free: running Telvyn on your own machine for personal or
internal local workflows is allowed under AGPL terms.

Commercial usage (including hosted services, distributed execution networks, or
monetized infrastructure built on top of Telvyn) may require a separate
commercial agreement in the future.

Planned future direction (not active yet): a commission-based commercial model
for remote task delegation via daemon + SSH, for example delegating from
Termux/mobile or a notebook console to another PC/server.

Community note: there are no penalties for users building their own SSH
delegation scripts for non-commercial use. These scripts are welcome and are
seen as ecosystem support that helps Telvyn continue improving.