Temporaeth

# Temporaeth

<p align="center">
  <img src="./assets/branding/logo.svg" alt="Temporaeth logo" width="88" />
</p>

![Language](https://img.shields.io/badge/language-Python%203.11%2B-blue)
![License](https://img.shields.io/github/license/smouj/Temporaeth)
![Last Commit](https://img.shields.io/github/last-commit/smouj/Temporaeth)
![CI](https://img.shields.io/github/actions/workflow/status/smouj/Temporaeth/ci.yml?branch=main)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20this%20project-ff5f5f?logo=ko-fi&logoColor=white)](https://ko-fi.com/smouj013_dev)

<p align="center">
  <a href="./README.md"><img src="https://img.shields.io/badge/README-English-1f6feb?style=for-the-badge" alt="English"></a>
  <a href="./README.es.md"><img src="https://img.shields.io/badge/README-Español-c92a2a?style=for-the-badge" alt="Español"></a>
</p>

**Predictive planning engine for intelligent scheduling.**

## Vision
Transforms constraints into adaptive plans with conflict-aware scheduling logic.

## What problem it solves
Manual planning fails under conflicting priorities and time constraints.

## Core superpower
- ⚡ **Constraint-aware agenda optimization with predictive prioritization**

## Key use cases
- ✅ Calendar planning
- ✅ Task prioritization
- ✅ Conflict resolution
- ✅ Deep-work scheduling


## API surface
`POST /plan`, `GET /caldav`, `GET /health`

## Technical stack
- **Core stack:** FastAPI + planning heuristics + temporal models
- **Runtime:** local-first, self-hosted friendly
- **Infra:** Docker Compose + Caddy + Redis/Chroma/Ollama compatibility

## Current status (Feb 2026)
- ✅ Public scaffold available
- ✅ Bilingual README (EN default + ES)
- ✅ CI + release baseline configured
- 🚧 Feature hardening in progress

## Quick start
```bash
git clone https://github.com/smouj/Temporaeth.git
cd Temporaeth
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m src.temporaeth.cli --help
```

## Documentation
- [Implementation Guide](./docs/IMPLEMENTATION.md)
- [Architecture](./docs/ARCHITECTURE.md)
- [Runbook](./docs/RUNBOOK.md)
- [Deployment Guide](./docs/DEPLOYMENT.md)
- [Release Process](./docs/RELEASE.md)
- [Changelog](./CHANGELOG.md)

## Contributing
Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md).

## License
MIT © 2026 smouj

---

### Other skills
Explore the full ecosystem here: **[smouj/smouj](https://github.com/smouj/smouj)**

**Signature:** [@Smouj013](https://x.com/smouj013)